Mermaid state diagrams for payment and order lifecycles
Model an order lifecycle with Mermaid state diagrams. Make events, cancellation, timeout, and terminal states explicit with a practical example.
A state diagram shows which conditions an object can be in and which events change that condition. Use one when the question is “What can happen next?” rather than “Which component calls another component?”
For an order, states might include awaiting payment, paid, shipped, and cancelled. Those names describe durable conditions. “Charge card” describes an action and usually belongs on a transition or in a separate interaction diagram.
Model the normal path and the exits
stateDiagram-v2
[*] --> AwaitingPayment
AwaitingPayment --> Paid : payment confirmed
AwaitingPayment --> Cancelled : customer cancels
AwaitingPayment --> Expired : payment window closes
Paid --> Shipped : fulfillment confirmed
Shipped --> Delivered : delivery confirmed
Delivered --> [*]
Cancelled --> [*]
Expired --> [*]The filled start marker enters AwaitingPayment. Arrows show allowed transitions, with event labels after the colon. End markers show where this particular model stops tracking the order. They do not imply that the business deletes the record.
Read the example as rules. A customer can cancel while awaiting payment. There is no cancellation transition from Shipped. If that is incorrect, change the model before building code around it.
Decide what a failed payment means
A failed payment attempt need not make the order terminal. If the customer can try another card, the order may remain in AwaitingPayment while the payment attempt itself has a separate lifecycle.
This distinction prevents a common modeling problem: combining order state, payment-provider state, and warehouse state into one long list. Three related objects can have three diagrams, connected by named events. Trying to encode every combination in one diagram makes the model difficult to inspect.
Write down which component owns each transition. “Payment confirmed” should correspond to a defined event or decision, not simply the customer clicking a button.
Review difficult event orderings
Imagine a timeout and payment confirmation arriving close together. Which result wins? Can a late confirmation reopen an expired order, or must it trigger a refund process? The diagram above does not answer that question, so the policy needs an explicit note or an additional transition.
Likewise, distinguish an event received twice from an event that legally occurs twice. A lifecycle diagram can guide the discussion, but it does not implement concurrency control or idempotency.
Edit, export, and test the model
Paste the code into Flowgraph Studio. Manual mode supports state editing and arrangement, while the Mermaid source remains available for review. Use the state syntax reference when adding composite states or other notation.
Turn every arrow into at least one behavioral test idea. Then identify forbidden transitions, such as delivering an unpaid order. Those negative cases often reveal missing checks earlier than a polished happy-path picture.
When you need to show the customer, payment service, and webhook interacting over time, link a sequence diagram beside the state model. One explains conversation order; the other explains legal lifecycle changes.
More guides
- Animate a Mermaid diagram as a short technical explanationTurn a static Mermaid flow into a captioned explanation. Plan the story, select GIF or video output, and check that animation preserves the system's meaning.
- Explain an Azure background-job architecture with MermaidDraw an illustrative Azure job-processing architecture with API, queue, worker, and storage boundaries. Explain acknowledgment, completion, and failure handling.
- Build a consistent technical carousel with a reusable brand kitCreate readable technical carousel slides using a reusable brand kit. Keep colors, typography, diagrams, and export checks consistent across the series.