Order Status Diagram Guide

An order status diagram is a state diagram of a single order's life: every status the order can be in, and every event that moves it from one status to the next. It answers two questions that a written spec answers badly — what statuses exist and what can follow what.

The distinction that matters: an order status diagram is about states, not steps. A step is something someone does ("pack the box"). A state is a condition the order sits in until something happens ("Processing"). Orders spend most of their life sitting still — waiting for payment to clear, waiting for a courier, waiting for a return window to close. Drawing states makes that waiting visible; drawing steps hides it.

Most teams already have this diagram, just not on paper. It lives in an enum, a status column, and a dozen if statements scattered across the codebase. The moment two of those disagree — the API says SHIPPED, the emails table says in_transit, support's macro says "Dispatched" — you get bugs nobody can reproduce. Putting the states on one page is how you find the disagreement before a customer does.

The natural notation is a Mermaid stateDiagram-v2: boxes are statuses, arrows are transitions, and the label on each arrow is the event that fires it.

Almost every order flow, in any industry, is a variation on the same five states plus one escape hatch:

Here is that skeleton as a diagram. It is deliberately minimal — start from this and add states only when you can name the event that reaches them.

Three steps. The first two are thinking; the third is typing.

Do not brainstorm. Go read the enum, the status column, and the list of transactional emails you send. Those three sources are the states your system actually has, and they usually disagree with each other — that disagreement is the first thing this exercise is worth.

Then apply one test to each candidate: can the order sit here indefinitely? If yes it is a state. If it always passes through in milliseconds, it is a step, and it belongs inside a transition, not as a box. "Charging card" is not a state. "Awaiting payment" is.

Watch for the states teams routinely forget: Refunding (money in flight, order neither done nor cancelled), PartiallyShipped (multi-item orders), Lost (carrier stopped scanning), and OnHold (fraud review). Every one of them turns into a support ticket if it has no box.

For each arrow, write down the event that fires it — not the resulting state. Pending --> Confirmed: payment authorized is useful. Pending --> Confirmed: confirm is a tautology.

Then run three checks over the finished graph:

Reachability. Every state must have at least one incoming arrow, and [*] must reach all of them. An unreachable state is dead code in your status enum.

Termination. Every state must lead somewhere, or be explicitly terminal (--> [*]). A state with no way out is an order stuck forever — this is the single most common real bug this diagram catches.

No implicit backwards edges. If support can move an order from Shipped back to Processing, draw that arrow. Undrawn admin overrides are how status machines rot.

Type the states and transitions as plain sentences and let text2diagram lay them out — you write "an order starts as pending, becomes confirmed once payment is authorized, then processing, then shipped, then delivered; it can be cancelled from pending or confirmed", and it comes back as a stateDiagram-v2 you can edit.

Or skip the typing entirely: open any diagram on this page in the editor with one click, then rename the states to match your own. That is usually faster than starting from a blank canvas, because the shape of the graph — not the vocabulary — is the part that takes thought.

Three real shapes. Notice how differently the same six-state skeleton bends once the business is specific.

The complication here is everything that happens after delivery. Delivered is a waypoint, not an end: returns, refunds and lost-parcel claims all branch off it or off Shipped. Teams that model Delivered as terminal end up processing refunds outside the status machine, in a spreadsheet.

A subscription is an order that never ends, so its diagram has cycles where an e-commerce one has a line. PastDue --> Active (a dunning retry succeeded) and Cancelled --> Active (a win-back) are the two arrows people forget, and they are exactly the two the revenue team cares about.

Also note Cancelling as a distinct state from Cancelled: the user has asked to leave but still has paid access until the period ends. Collapsing those two is how you accidentally cut off a customer who paid through the end of the month.

Two things make this one different. First, there are three parties — customer, restaurant, courier — so several transitions are fired by someone other than the buyer or your system. Second, the whole thing runs in about 40 minutes, which means the customer is watching the status change live, and every unlabelled state is a support call.

Rejected deserves its own box rather than folding into Cancelled: the customer paid and it was the restaurant that said no, so the refund path and the messaging are both different.