Open the editor

Sequence diagram

Messages between actors over time, with returns, async calls and branches.

1 sequence diagram example

Card payment sequence

A checkout request passing through the web app, the payments API and the bank, with a declined branch.

Time flows down the lifelines. Solid arrows are calls, dashed arrows are returns, and the alt frame holds both outcomes of the authorisation. The accent sits on one message only: the successful 201.

Open in the editor

What is a sequence diagram?

A sequence diagram shows how participants, such as a user, a frontend, an API and a payment provider, exchange messages over time to complete one scenario. It is a UML interaction diagram.

Read it top to bottom. Each participant has a vertical lifeline, solid arrows are calls, dashed arrows are returns and open arrowheads are asynchronous messages. Boxes labeled alt, opt or loop show branches and repetition.

When to use a sequence diagram

  • Use it to design or document an API flow, such as a card payment with authorization and webhook callback.
  • Use it when debugging timing issues, to see which call waits on which.
  • If you need the overall structure of the system rather than one scenario, use an architecture diagram.

How to make a good sequence diagram

  1. Cover one scenario per diagram, such as the happy path, and draw failure paths with alt frames or a second diagram.
  2. Order participants left to right in the order they first act.
  3. Label messages with the actual call or event name, like POST /payments.
  4. Show returns only when they carry information the reader needs.