DocumentationOrder Management

Order Management

4 minLast updated: 2026-03-31

Order State Machine

Every order follows a defined state machine:

pending → confirmed → preparing → shipped → delivered
   ↓                                         ↓
cancelled                              return_requested → returned → refunded

Each state transition is validated, you can only move to allowed next states. Invalid transitions are rejected.

Order Events

Every status change creates an order event log entry with timestamp, previous status, new status, and optional notes. This provides a complete audit trail for each order.

Workflow Integration

Orders fire workflow triggers at key points:

  • storefront_order_placed: New order created
  • payment_verified: Payment confirmed by merchant
  • payment_overdue: Invoice past due date
  • cart_abandoned: Customer left items in cart

Use these triggers to automate notifications, update inventory, or notify your fulfillment system.

Cancel & Return Flow

Orders can be cancelled before shipping (status reverts to cancelled, stock is released). After delivery, customers can request a return. The merchant reviews the request and can approve the return, triggering the returned → refunded flow.

API Endpoints

GET    /api/v1/commerce/orders         - List orders (filterable)
GET    /api/v1/commerce/orders/:id     - Order details with events
PUT    /api/v1/commerce/orders/:id/status: Update order status
GET    /api/v1/commerce/orders/stats   - Order statistics

Was this article helpful?