Subscription lifecycle state machine
Plan upgrades, downgrades, cancellation, and grace period recovery.
Subscription billing is deceptively complex. A customer upgrades, downgrades, pauses, the payment fails, they're in a grace period, and suddenly it's unclear whether they're still a customer or not. This template shows every state: active subscription, downgrades and upgrades, paused accounts, payment failure with retry and grace period, and the path to cancellation.
The state machine makes visible what many support teams discover through painful incidents: the grace period (when payment fails but the account is still alive and recoverable), the distinction between "requested cancellation" (they asked but still pay through the end of their term) and "canceled" (they're gone), and the common pattern of a customer recovering from a failed payment and staying active.
When to use this template
- Billing flow design — nail down the state transitions with your product and engineering teams before writing the payment processor integration, so failures and retries are handled consistently.
- Support playbooks — when a customer calls saying their account got suspended, the state machine shows exactly what happened (payment failed → grace period → suspension). It's the script for every support conversation.
- Incident postmortems — billing bugs often hinge on unexpected state transitions (e.g., cancel was processed but payment later succeeded). The diagram makes the bug visible.
How to adapt it
Expand the states and transitions to match your billing model:
- Add a Trial state before Active, with an expiration path to Canceled if no payment method is added.
- Insert Upsell and Addon-Active states if you sell add-ons or per-seat upgrades alongside base plans.
- Extend the grace period with Escalation and InReview substates if your support team can manually override suspension for good customers.
Visual edits regenerate the state machine syntax, so you can experiment with state topology and edge labels without writing YAML.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
stateDiagram-v2
[*] --> Active
Active --> Downgraded: Downgrade plan
Active --> Paused: Pause subscription
Active --> CancellationRequested: Request cancel
Active --> FailedPayment: Payment fails
Downgraded --> Active: Upgrade plan
Downgraded --> CancellationRequested: Request cancel
Downgraded --> FailedPayment: Payment fails
FailedPayment --> Active: Retry succeeds
FailedPayment --> GracePeriod: Retry fails
GracePeriod --> Active: Payment recovers
GracePeriod --> Suspended: Grace period expires
CancellationRequested --> Canceled: End of period
CancellationRequested --> Active: Reactivate
Paused --> Active: Resume
Paused --> Canceled: End pause
Suspended --> Canceled: Confirm cancel
Canceled --> [*]
Frequently asked questions
- What is a subscription state machine?
- A state machine models every state a subscription can enter and the transitions between them: active, downgraded, paused, awaiting payment, in a grace period, canceled. Every edge is a business event (upgrade, payment failure, grace period expiry). It makes visible the paths customers use to churn, retry, and reactivate.
- Why do subscriptions have a grace period?
- A customer's payment can fail for temporary reasons — expired card, rate limit, network timeout — that resolve within days. A grace period (typically 7–30 days) gives them time to fix it before the subscription suspends. Showing this state makes the recovery path explicit: payment fails → grace period → either recovery or suspension.
- What happens to the customer's data if a subscription is suspended?
- Suspension is not deletion. Most SaaS products hold the account and data read-only for 30–90 days, then delete. This diagram doesn't show data lifecycle, but you can annotate the Suspended and Canceled states with data-handling rules — those are implementation decisions you make when coding the webhook handler.
- How do I adapt this for a free-to-paid funnel?
- Add a Trial state after [*], with transitions to Active on first paid plan and to Expired on trial end. For add-ons or per-seat billing, add states like Upsell and Downgrade-Pending. Visual edits regenerate clean Mermaid, so you can layer in your plan hierarchy without touching syntax.