order-lifecycle

Order Lifecycle

Order State Machine

Orders follow a strict state machine. Never skip states or allow arbitrary transitions.

                    ┌─────────┐
                    │ CREATED │
                    └────┬────┘
                         │ payment initiated
                    ┌────▼─────────┐
                    │ PAYMENT_PENDING│
                    └────┬─────────┘
                    ┌────┴────┐
               payment   payment
               success    failed
                    │         │
             ┌──────▼──┐  ┌──▼───────┐
             │CONFIRMED │  │ FAILED   │
             └────┬─────┘  └──────────┘
                  │ fulfillment started
             ┌────▼──────┐
             │ PROCESSING │
             └────┬──────┘
                  │ shipped
             ┌────▼────┐
             │ SHIPPED  │
             └────┬────┘
                  │ delivered
             ┌────▼─────┐
             │ DELIVERED │
             └──────────┘

Allowed transitions:

From	To	Trigger
CREATED	PAYMENT_PENDING	Checkout initiated
PAYMENT_PENDING	CONFIRMED	Payment success webhook
PAYMENT_PENDING	FAILED	Payment failure / timeout
CONFIRMED	PROCESSING	Fulfillment started
CONFIRMED	CANCELLED	Customer cancellation (before fulfillment)
PROCESSING	SHIPPED	Tracking number assigned
SHIPPED	DELIVERED	Delivery confirmed
DELIVERED	RETURN_REQUESTED	Customer initiates return
RETURN_REQUESTED	RETURNED	Return received and inspected
Any (post-payment)	REFUNDED	Refund processed

Rule: Every state transition is an event

Store transitions in an order_events table, not just the current state:

CREATE TABLE order_events (
  id UUID PRIMARY KEY,
  order_id UUID NOT NULL REFERENCES orders(id),
  from_state VARCHAR(50),
  to_state VARCHAR(50) NOT NULL,
  triggered_by VARCHAR(100), -- "customer", "system", "admin"
  metadata JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW()
);