Subscriptions
The Subscriptions API lets you read and manage recurring purchases in your store — cancel them, resume a pending cancellation, or switch a customer to a different variant of the same product.
Overview
The Subscriptions API provides endpoints to:
- List subscriptions
- Retrieve a subscription
- Cancel a subscription
- Resume a subscription
- Change a subscription's plan
A subscription represents a recurring purchase made by a customer. Each
record carries the customer (its owner), the current variant (price), the
originating order, and the cycle and cancellation dates.
Status
Every subscription carries a status:
| Status | Meaning |
|---|---|
trialing | Inside the trial period |
active | Trial ended, billing succeeds |
past_due | Latest renewal payment failed; retries are in progress |
canceled | The subscription has ended |
incomplete | First payment is still pending or requires customer authentication |
incomplete_expired | The first payment was abandoned |
unpaid | Retries have stopped after past_due; access typically revoked |
The list endpoint's status filter accepts these values.
Cancellation
Cancelling a subscription stops billing. By default it takes effect at the
end of the current billing period — the customer keeps access until
current_period_end. Pass immediately: true to cut access right away.
There is no pause action.
A subscription in past_due is always cancelled immediately because there
is no period-end grace for an unpaid subscription.
The read response carries an is_cancelable boolean that reflects whether
a cancel request would succeed for the subscription in its current state.
Change plan
POST /subscriptions/{id}/change-plan
switches the subscription to a different variant of the same product.
The change is transactional and prorated; the proration is invoiced
immediately. If the proration payment is declined, the plan change does not
take effect and the endpoint returns 422 with the decline reason.
Includes
GET /subscriptions/{id} accepts an include query
parameter that expands related sections in the same call:
| Include | Returns |
|---|---|
customer | Minimal customer projection: id, email, name |
variant | Full product variant (same shape GET /product-variants/{id} returns) |
product | Lean product projection: id, name, checkout_url |
order | Lean originating-order projection: id, status, created_at |
renewals | Recorded renewal payments |
upcoming_invoice | Preview of the next invoice. Opt in only when you need it — see below. |
Sections that are not requested are returned as null; the keys are
always present so the response shape stays stable.
The upcoming_invoice include triggers a call to the payment provider. If
that call fails, the field is returned as null rather than failing the
whole request.