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.
A subscription that bills on a billing group is charged on the group's card,
not its own, so it never enters awaiting_payment and never emits a
per-decline subscription.error. It still emits subscription.payment_succeeded
when the group's charge clears, and the exhausted-retries subscription.error
if it never does. Gate access on those two events.
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.