# Lifecycle & statuses

import { Mermaid } from "zudoku/mermaid";

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

{/* @codegen subscription-statuses — generated by `pnpm docs:generate`; do not edit by hand */}

| 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. |

{/* @codegen-end subscription-statuses */}

`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

<Mermaid chart={`stateDiagram-v2
  [*] --> scheduled: future startDate
  [*] --> trial: trialDays set
  [*] --> awaiting_payment: card pay-first
  scheduled --> active: start date reached
  trial --> active: trial ends
  awaiting_payment --> active: card charge clears
  active --> paused: pause
  paused --> active: resume
  active --> pending_cancellation: cancel (end_of_cycle / specific_date)
  pending_cancellation --> cancelled: effective date reached
  pending_cancellation --> active: clear_schedule
  active --> cancelled: cancel immediately
  active --> expired: endDate reached
`} />

Status changes are driven by the billing engine and your
[change flows](/guides/subscriptions/changes), not by direct status writes — the
API has no "set status" call. Each transition emits a `subscription.*` webhook;
[Webhooks & reconciliation](/guides/subscriptions/webhooks) 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`.