Carts & checkout

Carts are server-authoritative: prices, discounts and totals are computed by the core, never trusted from the client.

The checkout state machine

Every order moves through defined states, and transitions are validated on the server. An order cannot skip payment or ship twice — the type system will not allow it.

Cart → Reserved → Payment → Paid → Fulfilled

• Declined payments return the order to Cart and release reserved stock.
• Refunds are reversible from Paid onward, with a full audit trail.

Creating a cart

curl -X POST :8080/carts \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "customer_id": "cus_12" }'

Add items, apply a discount, then check out:

curl -X POST :8080/carts/$ID/checkout \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "payment": "pm_123" }'
# 201 Created
# { "id": "ord_8f2", "total": "129.00", "currency": "USD" }