stateDiagram-v2 [*] --> Pending: order placed Pending --> Authorised: payment approved Pending --> Rejected: payment declined Pending --> Expired: no response in 24h Authorised --> Picking: stock allocated Authorised --> Cancelled: customer cancels Picking --> Shipped: consignment handed to carrier Picking --> Backordered: stock unavailable Backordered --> Picking: stock replenished Backordered --> Cancelled: customer cancels Shipped --> Delivered: carrier confirms Shipped --> Lost: no scan in 14 days Delivered --> Returned: return accepted Rejected --> [*] Expired --> [*] Cancelled --> [*] Delivered --> [*] Returned --> [*] Lost --> [*]
What it is
The complete set of states one entity may be in, and the only events that may move it between them. Anything not drawn is illegal, and that negative space is the deliverable's real output: it is where you discover that the refund path allows a cancelled order to be shipped.
When you produce it
For any entity whose status field has more than about four values and is written to by more than one service. Orders, claims, applications, tickets, subscriptions, deployments, KYC cases. Also whenever an incident review concludes with "it got into a state we did not think was possible".
Who reads it
Engineers, who translate it directly into guards. Testers, who use it to enumerate cases. Operations, who need to know which states are terminal and which are stuck. Product, who own the vocabulary the states are named in.
What good looks like
- Terminal states are marked and there are not many of them.
- Every transition is labelled with the event, not the method name.
- Timeouts are transitions like any other — "no response in 24h" is an event.
- States are named with the business's own words, so product can check it.
Common mistakes
- Missing the timeout transitions. Almost every real stuck-record incident is a state with no exit when nothing happens.
- Confusing state with substate. If half the transitions leave from the same place, you probably have a nested state that has not been drawn as one.
- Modelling the workflow instead of the entity. A workflow crosses several entities; this artifact is about one.