Lifecycle & statuses
A subscription moves through a fixed set of statuses. A read
(GET /v1/subscriptions/{id}) and the status list filter both report the
status of the version running today.
Statuses
| Status | Meaning |
|---|---|
scheduled | Created with a future start date; it has not begun billing yet. |
trial | In its trial period (set via trialDays); no charge until the trial ends. |
awaiting_payment | A card charge for the subscription hasn't cleared — either a pay-first subscription's first charge (no access granted yet) or a declined recurring charge during the retry/grace window. It flips back to active when a charge clears. The status itself doesn't gate access; whether to do so is the integrator's call (see the subscription.error / subscription.payment_succeeded webhooks). |
active | Live and billing on its cadence. |
pending_cancellation | A cancellation is scheduled (e.g. at end of cycle); the subscription stays active until the effective date. |
paused | Temporarily paused; no cycles are billed while paused. |
cancelled | Ended by cancellation; it no longer bills. |
expired | Reached its end date and is no longer active. |
awaiting_payment is the state of a card subscription whose latest charge
hasn't cleared. It arises two ways: a pay-first subscription's first charge,
before any access is granted — don't provision entitlements until it flips to
active on capture — or a previously-active subscription whose recurring charge
was declined, during the retry and grace window. The status alone revokes
nothing; whether to gate access is the integrator's call, driven by the
subscription.error and subscription.payment_succeeded webhooks (see
Webhooks & reconciliation). A subscription
billed by other means (e.g. manual invoice) activates directly and never enters
this state.
Transitions
Status changes are driven by the billing engine and your
change flows, not by direct status writes — the
API has no "set status" call. Each transition emits a subscription.* webhook;
Webhooks & reconciliation maps the events to
these edges.
Scheduled vs. immediate start
A startDate in the future creates the subscription scheduled; it resolves to
active (or trial / awaiting_payment) when the date arrives. This resolution
runs on real wall-clock time — a preview with a future asOf still reports
scheduled.