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.

Updated November 19, 2026 · 2 min read

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