Mermaid State Diagram: Order Status Lifecycle
Model an order status lifecycle with a Mermaid state diagram: start and end states, transitions and the events that trigger them. A simple way for business analysts to find missing statuses, shown with an online shop order.
Step by step
Statuses
- Order statuses. An order in an online shop moves through statuses such as Placed, Paid and Shipped. A state diagram shows every status and the events that move an order from one to the next. Here is how to build one in Mermaid.
- Diagram type. Clear the editor and type stateDiagram-v2 on the first line. This tells Mermaid to draw a state diagram in its newer style.
stateDiagram-v2
Transitions
- Start state. On the next line, type [*] --> Placed. The [*] on the left of an arrow is the start point, so the first status is Placed.
[*] --> Placed - Transitions. Each arrow is a transition. After the colon, write the event that causes it. Placed --> Paid : payment received and Placed --> Cancelled : customer cancels give a placed order 2 ways to go. The diagram shows each state as a rounded box, with its event written on the arrow. Then add the happy path. Paid --> Shipped : parcel sent and Shipped --> Delivered : parcel signed for take the order through to the customer.
Placed --> Paid : payment received Placed --> Cancelled : customer cancelsPaid --> Shipped : parcel sent Shipped --> Delivered : parcel signed for
End states
- End states. When [*] is on the right of an arrow, it marks the end. Delivered --> [*] and Cancelled --> [*] mean an order finishes when it is delivered or cancelled. The diagram now shows the whole life of an order, from the start point to the 2 end points.
Delivered --> [*] Cancelled --> [*]
Check it
- Ways in and out. Check each state: how does an order get in, and how does it get out? Cancelled gets in through customer cancels and out to the end point. A state with no way out often points to a missing requirement. Returns are not in the diagram yet. They would be a new state after Delivered. Check with the business before you add it, because it brings new rules about refunds and stock.
Recap
- The rules. In short: begin with [*], write one arrow per transition with its event after the colon, and finish each end state with --> [*].
Common mistakes
- A typo or different capital letters in a state name. Mermaid treats Shiped, shipped and Shipped as 3 different states, and it draws a new box without any error. Copy each state name exactly from the line where you first used it.
- Spaces in a state name. A name like Awaiting payment will not work as written. Give it a short ID and a label, for example state "Awaiting payment" as Awaiting, then use Awaiting in your arrows.
- Writing stateDiagram v2 with a space. The first line must be stateDiagram-v2, with a dash and no spaces, or the diagram won't render.
- Treating the diagram as finished once the happy path works. Ask about every state, not just the main line. In this example, a Paid order has no way to be cancelled or refunded. That is a question to put to the business, not a gap to quietly fill.
When a business analyst uses this
In a requirements workshop with sales and the warehouse team, a business analyst drafts the order lifecycle live in Mermaid. The team sees that a Paid order can't be cancelled and that there is no Returned state. Both go into the requirements log as open questions before sign-off.
Questions people ask
What is the difference between stateDiagram and stateDiagram-v2 in Mermaid?
Both use the same syntax. stateDiagram-v2 uses Mermaid's newer renderer, which is why it is the one to use for new diagrams.
How do I make a Mermaid state diagram go left to right?
Add the line direction LR straight after stateDiagram-v2. The states are then laid out across the page instead of from top to bottom.
Can a state point to itself in a Mermaid state diagram?
Yes. Write the same state on both sides of the arrow, for example Placed --> Placed : reminder sent, and Mermaid draws a loop back to the same box.
