Subscription Lifecycle

A subscription moves through a number of states over its lifetime. These transitions happen automatically, and you get a webhook at each stage.

Subscription States

PENDING

Subscription created and waiting for checkout, nothing has been charged. You receive subscription.created. Don't provision access yet.

ACTIVE

The subscriber has authorised the subscription and the first payment has been confirmed. Recurring charges then run on schedule, each firing subscription.payment.succeeded — provision and extend access on these. A healthy subscription spends most of its life here, and indefinite plans (no termCycles) stay here until canceled.

PAST_DUE

A recurring charge failed, usually because the wallet balance is too low or the subscriber has revoked their on-chain allowance. It is recommended at this stage to prompt the subscriber to top-up their balance. Confirmo retries through the grace period configured for the plan; if one succeeds, the subscription returns to ACTIVE (subscription.resumed).

CANCELED

Stopped for good before its natural end (subscription.canceled), at this stage you should turn off the subscriber's access. See cancellation.reason for why. Terminal state.

EXPIRED

Ended on its own terms (subscription.expired), at this stage you should turn off the subscriber's access.. See expiration.reason for why. Terminal state.

How subscriptions move between states

From → To	What triggers it
`PENDING` → `ACTIVE`	The subscriber completes checkout and the first charge confirms.
`PENDING` → `CANCELED`	Checkout isn't completed before it times out.
`PENDING` → `EXPIRED`	The first charge fails.
`ACTIVE` → `PAST_DUE`	A recurring charge fails.
`PAST_DUE` → `ACTIVE`	A retry succeeds during the grace period.
`PAST_DUE` → `CANCELED`	The grace period runs out with no successful charge.
`ACTIVE` → `CANCELED`	You or the subscriber cancels the subscription before the term ends.
`ACTIVE` → `EXPIRED`	A subscription with a fixed term completes. Subscriptions on indefinite plans never expire.

Reason codes

A terminal event carries the reason it ended — cancellation.reason for CANCELED, expiration.reason for EXPIRED.

cancellation.reason

Value	What it means
`SUBSCRIBER`	The subscriber canceled.
`MERCHANT`	You canceled.
`MERCHANT_DISABLED`	Canceled because your account was disabled.
`ADMIN`	Canceled by Confirmo e.g. for compliance reasons.
`EXPIRED`	Canceled as part of the subscription expiring.
`DUNNING_EXHAUSTED`	Auto-canceled after the grace-period retries ran out.
`SANCTIONS_HIT`	Auto-canceled because a sanctions / risk screening blocked the payment.
`CHECKOUT_TIMEOUT`	Auto-canceled because checkout wasn't completed in time.

expiration.reason

Value	What it means
`TERM_REACHED`	The plan's fixed `termCycles` finished.
`PAYMENT_FAILED`	Ended after a terminal payment failure — the first charge failed, or no grace period was set.