Order Lifecycle State Diagram
The code
stateDiagram-v2
[*] --> Pending: checkout
Pending --> Paid: payment captured
Pending --> Cancelled: timeout
Paid --> Packed: pick and pack
Packed --> Shipped: handover
Shipped --> Delivered: delivery scan
Delivered --> [*]: complete
Cancelled --> [*]: refund
How this template works
An order is a state machine long before anyone writes the code for one. It starts when a customer checks out, moves through payment, packing, and shipping, and ends either delivered or cancelled. This diagram puts that whole lifecycle on one screen, which makes it the reference document for support teams deciding what an order can do next and for engineers writing the guards that enforce it.
The syntax is compact. The first line, stateDiagram-v2, selects the current state diagram flavor. [*] --> Pending: checkout uses the [*] pseudo-state as the entry point, so the machine has an unambiguous beginning. Every other line is a transition: two state names joined by -->, with the event that triggers the move written after the colon, such as payment captured. The same [*] appears twice more as the exit point, once after Delivered and once after Cancelled, which documents that the machine has two terminal outcomes. State names use CamelCase without spaces, while transition labels are free text and can contain spaces.
The gotcha is unreachable states. Every state you declare should be reachable from [*] and should be able to reach [*]; a state that can only be entered but never left, or that nothing points to, is usually a missing transition rather than a design choice. When you add a state, trace both directions before you commit the file.
To adapt it, add a Refunded state between Cancelled and the end marker, add a PartiallyShipped state for multi-parcel orders, or rename the transition labels to match the exact event names your backend emits so the diagram and the code share vocabulary.
Related templates that model other lifecycles: the auth session state diagram for login and token refresh, the task queue state diagram for background jobs, and the subscription billing state diagram for recurring payments. The state diagram guide covers the full syntax.
Variations to try
- Add a Refunded state between Cancelled and the end marker if refunds run as their own business process.
- Add a PartiallyShipped state for orders that leave the warehouse in more than one parcel.
- Rename the transition labels to match the exact event names your backend emits.
