Order Lifecycle

Every order moves through a fixed set of states. The API never lets an order skip a state or move backwards — understanding the diagram below explains every status code the order endpoints can return.

States

stateDiagram-v2
    [*] --> pending: POST /orders
    pending --> paid: payment captured
    paid --> shipped: warehouse handover
    pending --> cancelled: POST /orders/{orderId}/cancel
    paid --> cancelled: POST /orders/{orderId}/cancel
    shipped --> [*]: delivered
    cancelled --> [*]

Status	Meaning
`pending`	Order placed, payment not yet captured.
`paid`	Payment captured, order queued for the warehouse.
`shipped`	Handed to the carrier — the point of no return.
`cancelled`	Cancelled by the customer or by support. Terminal.

Placing an order

POST /orders prices the items server-side and returns the full order with subtotal, shippingCost and total. New orders always start as pending:

curl -X POST 'https://api.acmewebshop.com/v2/orders' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "b6f2a9d1-4c7e-4a58-9d20-8e3f5c1b7a94",
    "items": [{ "productId": "4f7c2a1e-9b3d-4e8f-a2c6-1d5b8e3f7a90", "quantity": 2 }],
    "shippingAddress": { "street": "Gartenweg 12", "city": "Freiburg", "postalCode": "79098", "country": "DE" }
  }'

Cancelling

POST /orders/{orderId}/cancel works while the order is pending or paid:

200 — the order comes back with "status": "cancelled".
409 with code ORDER_ALREADY_SHIPPED — the order left the warehouse; cancellation is no longer possible. Handle the return through support instead.

Monitoring your orders

GET /orders?status=pending filters by state — poll it to reconcile open orders, or fetch a single order with GET /orders/{orderId}.