Order lifecycle

OverviewCopy Anchor Link

Prood uses a three-dimensional order status model inspired by Commerce Layer. Instead of a single status field that conflates payment and shipping state, orders track three independent dimensions:

This separation makes it trivial to answer questions like "show me paid orders that haven't shipped yet" or "which orders have partial refunds" without parsing a single overloaded status field.

Order statusCopy Anchor Link

The primary lifecycle status of the order.

State machineCopy Anchor Link

placed → approved → fulfilled
  ↓         ↓
cancelled  cancelled

Payment statusCopy Anchor Link

Independent from order status. Tracks the payment lifecycle.

TransitionsCopy Anchor Link

unpaid → authorized → paid → partially_refunded → refunded
  ↓         ↓
voided    voided

For auto-capture providers (Stripe default), unpaid transitions directly to paid.

Fulfillment statusCopy Anchor Link

Tracks shipping progress. Independent from payment — an order can be fulfilled before capture in delayed-capture scenarios.

Per-item fulfillmentCopy Anchor Link

Each OrderItem also has its own fulfillmentStatus for granular tracking:

Lifecycle timestampsCopy Anchor Link

Each status transition records a timestamp:

Complete lifecycle exampleCopy Anchor Link

Happy path (card payment, physical goods)Copy Anchor Link

Payment failureCopy Anchor Link

Refund after fulfillmentCopy Anchor Link

Free order (100% coupon)Copy Anchor Link

Database schemaCopy Anchor Link

CREATE TABLE orders (
  id TEXT PRIMARY KEY,
  order_number TEXT NOT NULL UNIQUE,
  customer_id TEXT REFERENCES customers(id),
  contact_email TEXT,

  -- Three-dimensional status
  status TEXT NOT NULL DEFAULT 'placed',
  payment_status TEXT NOT NULL DEFAULT 'unpaid',
  fulfillment_status TEXT NOT NULL DEFAULT 'unfulfilled',

  -- Lifecycle timestamps
  placed_at TIMESTAMPTZ,
  approved_at TIMESTAMPTZ,
  cancelled_at TIMESTAMPTZ,
  fulfilled_at TIMESTAMPTZ,

  -- Totals, addresses, etc.
  ...
);

TypeScript typesCopy Anchor Link

type OrderStatus = 'placed' | 'approved' | 'fulfilled' | 'cancelled'

type PaymentStatus =
  | 'unpaid' | 'authorized' | 'paid'
  | 'partially_refunded' | 'refunded'
  | 'voided' | 'free'

type OrderFulfillmentStatus =
  | 'unfulfilled' | 'in_progress' | 'fulfilled' | 'not_required'

interface Order {
  status: OrderStatus
  paymentStatus: PaymentStatus
  fulfillmentStatus: OrderFulfillmentStatus
  placedAt: string | null
  approvedAt: string | null
  cancelledAt: string | null
  fulfilledAt: string | null
  // ... other fields
}

Webhook-driven transitionsCopy Anchor Link

The payment status is updated exclusively by webhooks from the payment provider. The API app's reconcilePayment handler maps provider events:

A failure or refund about a payment the order no longer uses changes nothing: a shopper's retry replaces the payment on the order, and the abandoned one can still report in. A capture of another payment on an order that already has its money leaves one history note per transaction, because that money may be owed back.

Order historyCopy Anchor Link

Every status change is recorded in the order_history table:

CREATE TABLE order_history (
  id TEXT PRIMARY KEY,
  order_id TEXT REFERENCES orders(id),
  from_status TEXT,
  to_status TEXT NOT NULL,
  note TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

This provides a full audit trail visible in the dashboard order detail page.

Related pagesCopy Anchor Link