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 createdpayment_verified: Payment confirmed by merchantpayment_overdue: Invoice past due datecart_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