Subscription Billing State Diagram
The code
stateDiagram-v2
[*] --> Trialing: signup
Trialing --> Active: payment method added
Trialing --> Expired: trial ended
Active --> PastDue: payment failed
PastDue --> Active: retry succeeded
PastDue --> Cancelled: grace period over
Active --> Cancelled: user request
Cancelled --> [*]: data purged
Expired --> [*]
How this template works
Subscription billing is a negotiation between the customer and the payment processor, and this diagram captures every stage of it. A signup lands in Trialing, which converts to Active once a payment method is attached or expires when the trial runs out. Active subscriptions slip into PastDue when a charge fails, recover when a retry succeeds, and fall out of the system entirely through Cancelled or Expired. Support, finance, and engineering can all point at the same picture when a customer asks what happened to their account.
The transitions encode business rules, so the labels matter more here than in most state diagrams. Active --> PastDue: payment failed and PastDue --> Active: retry succeeded describe the dunning cycle, while PastDue --> Cancelled: grace period over documents the point where the system stops being patient. Notice that Cancelled is reachable from two states — that kind of fan-in is normal and is exactly what a state diagram shows better than prose. The [*] marker appears at both ends: once as the entry point after signup, and once as the shared exit for Cancelled and Expired.
The gotcha is the missing transition everyone forgets: what happens when a cancelled customer wants to come back? If resubscription is a real flow in your product, add an edge from Cancelled back to Active labeled resubscribe; if it is not, the diagram is already honest. Also keep state names to single CamelCase words — PastDue, not Past Due — because spaces in state names are a common parse error.
To adapt it, add a Paused state reachable from Active for subscription holds, rename PastDue to Dunning to match your billing provider, or add a transition label for plan upgrades if upgrades need their own audit trail.
Related templates covering adjacent lifecycles: the order lifecycle state diagram for one-time purchases, the auth session state diagram for access control, and the task queue state diagram for the jobs that charge cards. The state diagram guide documents the notation.
Variations to try
- Add a Paused state reachable from Active for products that support subscription holds.
- Add a transition from Cancelled back to Active labeled resubscribe if win-back flows exist.
- Rename PastDue to Dunning if that is the term your billing provider uses.
