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 --> [*].
Nested states for sub-steps
When one status has its own steps, nest them inside it. Write state Shipped { on its own line, then the inner lines such as [*] --> Packed and Packed --> OutForDelivery, and close it with }. The outer diagram still treats Shipped as one state, so the big picture stays simple and the detail is there for whoever needs it.
Notes and choice points
Add a note next to a state with note right of Paid : card payments only. To show a business rule, add a choice point: declare state stockCheck <<choice>>, then draw Paid --> stockCheck, stockCheck --> Packing : in stock and stockCheck --> Backorder : out of stock. The rule is then on the diagram, where stakeholders can check it in the workshop.
Mermaid or PlantUML for state diagrams?
For a status lifecycle like this one, Mermaid is enough, and GitHub and GitLab draw it from plain text without installing anything. PlantUML has more UML features, such as history states and entry and exit points, which matter more in detailed system design than in business requirements.
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.
