Subscriptions
A subscription is a recurring order. It charges a customer on a defined cadence — monthly, weekly, yearly, or any combination configured on the plan — and continues until canceled.
Subscription is an item of an order:
Internally, a subscription is modelled as an item of an order, not as a separate resource. That is why the subscription ID uses the
ord_prefix (for example,ord_01XYZ) — it is the ID of the order the subscription belongs to. The order generates an invoice for each service period.
What sets a subscription apart from a one-time order
- A subscription can have a trial period before billing starts.
- A subscription renews automatically on the
recurringIntervaldefined by its plan. - A subscription can be paused, resumed, canceled, reactivated, upgraded, and downgraded over its lifetime — each via a dedicated endpoint.
A one-time order, by contrast, runs once and is done. See One-time order.
Plan categories
The subscription resource is driven by the plan it points at. Plans fall into three categories — see Products and plans:
| Plan category | Configuration | Used with |
|---|---|---|
| Trial-only | Plan with trial, no recurringInterval. | POST /subscriptions with isTrialOnly: true. |
| One-time order | Plan without recurringInterval. | POST /subscriptions/one-time-orders — see One-time order. |
| One-time order with trial | Plan with recurringInterval.limit: 1 (single charge) and trial. | POST /subscriptions with isTrialOnly: false. The trial fires once, the main charge fires once, and the subscription ends. |
| Recurring subscription | Plan with recurringInterval (optionally also a trial). | POST /subscriptions. |
Pricing options
Independent of the plan category, a plan defines its pricing via pricing.formula. The supported formulas are:
| Formula | Description |
|---|---|
fixed-fee | A single fixed price per cycle. |
flat-rate | A flat unit price multiplied by quantity. |
tiered | Different unit prices in successive tiers. |
volume | A single unit price determined by total volume. |
stair-step | A fixed total price per quantity tier. |
For pricing-formula details, see Pricing.
For the request shape that selects each plan and pricing combination, see Create a subscription.
API operations
| Operation | Endpoint |
|---|---|
| Create | POST /v1/public-api/organizations/{organizationId}/subscriptions |
| List | GET /.../subscriptions |
| Read one | GET /.../subscriptions/{subscriptionId} |
| Update | PUT /.../subscriptions/{subscriptionId} |
| Delete (while pending) | DELETE /.../subscriptions/{subscriptionId} |
| Upgrade / downgrade | POST /.../subscriptions/{subscriptionId}/items |
For cancellation, pause, and reactivation operations — each on its own resource — see Subscription cancellations, Subscription pauses, and Subscription reactivation.
What a subscription looks like
- A unique ID (
subscriptionId, withord_prefix). - A status (see Subscription statuses).
- A customer (
customerId). - A payment instrument (
paymentInstrumentId). - One or more items, each referencing a plan.
- A renewal anchor and the calculated next charge date.
- Optional trial state.