01Run it
Straight from the command's own help.
p202 ltv subscription upsert --external-sub-id sub_123 --customer-ref CUST-77 --amount 29 --interval month02What you get
Pick the shape you need. People get a table. Add
--json, --csv or --ndjson for scripts, or -q for ids only. An AI agent gets compact JSON without asking. All output formats03Build your command
Pick values and the command line writes itself, quoted and ready to paste.
p202 ltv subscription upsertSet flags below; the command updates as you type.
04Flags
15 flags, plus the global flags every command takes.
| Flag | What it does |
|---|---|
| --amountstringrequired | What one billing interval charges (required) |
| --currencystring | Currency code; must be the account currency (default it) |
| --customer-crmstring | CRM fields as a JSON object, applied only when this call creates the customer, e.g. '{"email":"[email protected]","first_name":"Ada"}' |
| --customer-idstringrequired, or --customer-ref | The customer's internal id (p202 ltv customers) |
| --customer-refstringrequired, or --customer-id | Your system's id for the customer; the server finds it, or creates a customer for it |
| --customer-ref-typestring | What kind of reference --customer-ref is (default custom): email_md5, email_sha256, esp_id, merchant_id, subid, customemail_md5email_sha256esp_idmerchant_idsubidcustom |
| --external-sub-idstringrequired | Your billing system's subscription id (required) |
| --grace-daysstring | Days past the period end before it counts as past_due (default 3) |
| --intervalstring | Billing interval (default month): day, week, month, yeardayweekmonthyear |
| --interval-countstring | Intervals per charge, e.g. 3 with --interval month for quarterly (default 1) |
| --period-endstring | Current period end, unix seconds (default one interval after the start) |
| --period-startstring | Current period start, unix seconds (default --started-at) |
| --plan-namestring | Plan name |
| --started-atstring | When it started, unix seconds (default now) |
| --statusstring | Lifecycle status (default active): trialing, active, past_due, paused, canceledtrialingactivepast_duepausedcanceled |
05How it works
Keyed by --external-sub-id: the same id again updates it (and may move it to another customer). MRR is the amount normalized to a month (a trial carries none).
p202 ltv subscription upsert --external-sub-id sub_123 --customer-ref CUST-77 --amount 29 --interval month
06For agents
Running this from an agent
- Read the same facts as JSON:
p202 commands ltv subscription upsert --json. - With
AI_AGENT,CLAUDECODEor another agent variable set, output is compact JSON and errors arrive on stderr as a JSON envelope with ahint. - Exit codes: 0 ok, 1 bad input, 2 auth, 3 network, 4 server error, 5 partial failure.
- This command writes and cannot be staged:
--stagedis refused before anything is sent. Have a person run it, or give the agent a key without write scope.
{
"path": "p202 ltv subscription upsert",
"use": "upsert --external-sub-id <id> --amount <n> (--customer-ref <id> | --customer-id <id>)",
"short": "Create or update a subscription keyed by your billing system's id; MRR follows from amount and interval",
"long": "Keyed by --external-sub-id: the same id again updates it (and may move it to another customer).\nMRR is the amount normalized to a month (a trial carries none).\n\n p202 ltv subscription upsert --external-sub-id sub_123 --customer-ref CUST-77 --amount 29 --interval month",
"runnable": true,
"flags": [
{
"name": "amount",
"type": "string",
"default": "",
"usage": "What one billing interval charges (required)",
"required": true
},
{
"name": "currency",
"type": "string",
"default": "",
"usage": "Currency code; must be the account currency (default it)",
"required": false
},
{
"name": "customer-crm",
"type": "string",
"default": "",
"usage": "CRM fields as a JSON object, applied only when this call creates the customer, e.g. '{\"email\":\"[email protected]\",\"first_name\":\"Ada\"}'",
"required": false
},
{
"name": "customer-id",
"type": "string",
"default": "",
"usage": "The customer's internal id (`p202 ltv customers`)",
"required": false
},
{
"name": "customer-ref",
"type": "string",
"default": "",
"usage": "Your system's id for the customer; the server finds it, or creates a customer for it",
"required": false
},
{
"name": "customer-ref-type",
"type": "string",
"default": "",
"usage": "What kind of reference --customer-ref is (default custom): email_md5, email_sha256, esp_id, merchant_id, subid, custom",
"allowed_values": [
"email_md5",
"email_sha256",
"esp_id",
"merchant_id",
"subid",
"custom"
],
"required": false
},
{
"name": "external-sub-id",
"type": "string",
"default": "",
"usage": "Your billing system's subscription id (required)",
"required": true
},
{
"name": "grace-days",
"type": "string",
"default": "",
"usage": "Days past the period end before it counts as past_due (default 3)",
"required": false
},
{
"name": "interval",
"type": "string",
"default": "",
"usage": "Billing interval (default month): day, week, month, year",
"allowed_values": [
"day",
"week",
"month",
"year"
],
"required": false
},
{
"name": "interval-count",
"type": "string",
"default": "",
"usage": "Intervals per charge, e.g. 3 with --interval month for quarterly (default 1)",
"required": false
},
{
"name": "period-end",
"type": "string",
"default": "",
"usage": "Current period end, unix seconds (default one interval after the start)",
"required": false
},
{
"name": "period-start",
"type": "string",
"default": "",
"usage": "Current period start, unix seconds (default --started-at)",
"required": false
},
{
"name": "plan-name",
"type": "string",
"default": "",
"usage": "Plan name",
"required": false
},
{
"name": "started-at",
"type": "string",
"default": "",
"usage": "When it started, unix seconds (default now)",
"required": false
},
{
"name": "status",
"type": "string",
"default": "",
"usage": "Lifecycle status (default active): trialing, active, past_due, paused, canceled",
"allowed_values": [
"trialing",
"active",
"past_due",
"paused",
"canceled"
],
"required": false
}
]
}