Order Lifecycle

State machine

Cart → Reserved → Payment → Paid → Fulfilled
  ↓                      ↓
declined → Cart    refunded → Paid

Order statuses

Status	Description	Next
pending	Order created, awaiting payment	confirmed, cancelled
confirmed	Payment received	processing, on_hold, cancelled
processing	Being prepared	completed, on_hold
on_hold	Manual review	processing, cancelled
completed	Shipped and delivered	refunded
cancelled	Cancelled	—
refunded	Payment refunded	—

Checkout flow

1. POST /checkout/initiate — calculate tax, shipping rates
2. POST /checkout/complete — create order, payment intent
3. Client confirms payment (Stripe/Airwallex)
4. POST /checkout/confirm — verify payment, finalize order

Fulfillment

Orders can be partially or fully fulfilled:

POST /api/v1/orders/:id/fulfillments
{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "items": [
    { "order_item_id": "uuid", "quantity": 2 }
  ]
}

Multiple fulfillments per order for split shipments.

Events

Order state changes emit events:

• order.created
• order.paid
• order.shipped
• order.completed
• order.cancelled
• order.refunded

Events trigger webhooks, emails, and analytics.

Inventory

Inventory is reserved when the order is created and decremented when fulfilled. Cancelled orders release the reservation.