State reference

Order states

An order's status drives whether you can capture payment, fulfill items, or refund. Each transition emits an outbound webhook.

State machine

stateDiagram-v2
  [*] --> draft: cart.checkout
  draft --> pending: checkout-session created
  pending --> paid: payment.captured
  pending --> cancelled: buyer abandons or merchant cancels
  paid --> fulfilled: all fulfillments delivered
  paid --> partially_refunded: payment.refunded (partial)
  paid --> refunded: payment.refunded (full)
  fulfilled --> [*]
  refunded --> [*]
  partially_refunded --> [*]
  cancelled --> [*]

Order lifecycle from draft through terminal.

States

draft — created via POST /carts/{id}/checkout (or directly via the orders API). No payment attached.
pending — a checkout session has been minted against the order. Payment is in flight (PaymentEmbed mounted on the buyer's storefront).
paid — payment was captured. Fulfillments can now be created.
fulfilled — every fulfillment row attached to this order reached its terminal state (shipped/delivered for shipment, granted for access, delivered for digital, etc.).
partially_refunded / refunded — a refund event was processed against the linked payment. Partial refunds remain mutable for further refunds up to the original captured amount.
cancelled — terminal. Reached from pending before payment.

Outbound events

order.created on entering draft.
order.updated on every status transition.
order.cancelled on entering cancelled.
order.fulfilled on entering fulfilled.
order.refunded on entering refunded / partially_refunded.