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, 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 a
subscription to a different variant of the same product. The change is
prorated and invoiced immediately; if that payment is declined, the plan change
does not take effect. For a subscription paid with BLIK, the call returns 202
while the bank confirms the payment, and the new plan applies once it does.