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 | Card pay-first only: the first invoice is issued but its card charge hasn't cleared, so it grants no access yet — it flips to active on capture. A subscription not charged on a card up front activates directly and never enters this state. |
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 applies only to card pay-first subscriptions — those whose
first charge is taken on a card before access is granted. The first invoice is
issued but the card charge hasn't cleared, so the subscription exists yet grants
no access; it flips to active automatically on capture, so don't provision
entitlements until then. 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.