Mermaid Sequence Diagram Syntax: A Practical Guide for API and Product Flows

Sequence diagrams are best when order and responsibility matter. They show who called what, when, and why. Mermaid keeps them close to code and docs, which makes them easier to maintain during product changes and incident reviews.

This guide goes beyond the basics with patterns you can reuse for API calls, async work, retries, and webhook flows.

What sequence diagrams are best at

Use sequence diagrams when you need to explain time-ordered interactions:

• API requests across services or domains
• User flows that trigger background jobs or webhooks
• Auth and payment sequences with redirects or callbacks
• Incident timelines and retry behavior

If you are mapping static structure, use a C4 container or component diagram instead. Sequence diagrams are about time, not topology.

Core syntax

Start with sequenceDiagram, then declare participants and messages.

sequenceDiagram
  participant U as User
  participant Web as Web App
  participant API as API Service
  participant DB as Database

  U->>Web: Submit order
  Web->>API: POST /orders
  API->>DB: Insert order
  DB-->>API: Order ID
  API-->>Web: 201 Created
  Web-->>U: Confirmation

Participants and aliases

Aliases keep labels short and message lines readable, especially with long names or spaces.

sequenceDiagram
  actor C as Customer
  participant P as Payments Service
  participant Q as Queue Worker

  C->>P: Start checkout
  P->>Q: Enqueue receipt job

Message arrows that communicate intent

Use a small set of arrows consistently. Reviewers should understand meaning at a glance.

• ->> synchronous call
• -->> return or async response
• -) fire-and-forget async call
• -x failure or message not delivered

sequenceDiagram
  participant Web
  participant API

  Web->>API: POST /login
  API-->>Web: 200 OK
  Web-)API: analytics event
  Web-xAPI: timeout

Activations to show execution time

Activations highlight who is doing work and help explain latency.

sequenceDiagram
  participant Web
  participant API
  participant DB

  Web->>+API: POST /orders
  API->>+DB: Insert order
  DB-->>-API: Order ID
  API-->>-Web: 201 Created

Notes for rationale and constraints

Notes add context without making message labels unreadable.

sequenceDiagram
  participant Web
  participant API

  Note right of API: Validates auth token and scopes
  Web->>API: GET /profile
  API-->>Web: 200 OK

Control flow fragments you should know

Fragments help you document real-world behavior: retries, failures, and conditionals.

alt / else for branches

sequenceDiagram
  participant Web
  participant API

  Web->>API: POST /checkout
  alt Payment approved
    API-->>Web: 200 OK
  else Payment declined
    API-->>Web: 402 Payment Required
  end

loop for retries or polling

sequenceDiagram
  participant Web
  participant API

  loop Retry up to 3 times
    Web->>API: POST /charge
    API-->>Web: 503
  end

opt for optional paths

sequenceDiagram
  participant Web
  participant API

  Web->>API: POST /login
  opt MFA enabled
    API-->>Web: 401 MFA Required
  end

par for parallel work

sequenceDiagram
  participant API
  participant Email
  participant Analytics

  par Send email
    API-)Email: Send receipt
  and Track analytics
    API-)Analytics: Purchase event
  end

Practical patterns you can reuse

1) REST API with request validation

sequenceDiagram
  participant U as User
  participant Web as Web App
  participant API as Orders API
  participant DB as Orders DB

  U->>Web: Submit order
  Web->>API: POST /orders
  activate API
  Note right of API: Validate schema and auth
  API->>DB: Insert order
  DB-->>API: Order ID
  API-->>Web: 201 Created
  deactivate API
  Web-->>U: Confirmation

2) Webhook callback flow

sequenceDiagram
  participant Web as Web App
  participant API as Payments API
  participant Pay as Payment Provider
  participant DB as Orders DB

  Web->>API: POST /pay
  API-)Pay: Create payment intent
  Pay-->>API: Webhook payment.succeeded
  API->>DB: Update order status
  API-->>Web: Payment confirmed

3) Async job with queue worker

sequenceDiagram
  participant API
  participant Q as Queue
  participant W as Worker
  participant DB

  API->>Q: Enqueue export job
  Q-->>W: Deliver job
  W->>DB: Fetch data
  W-->>Q: Ack

Error handling that readers trust

If you never show failure, your diagrams look optimistic. Add failure paths to make the diagram useful in reviews.

sequenceDiagram
  participant Web
  participant API
  participant DB

  Web->>API: POST /orders
  API->>DB: Insert order
  alt DB error
    DB-->>API: Timeout
    API-->>Web: 500 Internal Error
  else Insert ok
    DB-->>API: Order ID
    API-->>Web: 201 Created
  end

Layout and readability tips

• Keep participant names short and consistent across diagrams.
• Avoid long message text. Move details into notes.
• Put the primary flow top to bottom, left to right.
• Prefer a single screen view for shared docs.

Common mistakes to avoid

• Mixing too many arrow styles in one diagram
• Hiding failures or retries from the flow
• Repeating long labels instead of using aliases
• Putting implementation details into message text

A lightweight review checklist

• Participants appear in the order of the main flow
• Each async call has a response or note
• Failures are represented for critical operations
• The diagram still reads clearly in a PR diff

If you want faster editing, live previews, and AI help to refine Mermaid diagrams, UniDiagram keeps the workflow smooth for product and engineering teams.