Orders & Fulfillment

Order lifecycle

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

Orders move through defined states. Transitions are validated on the server — an order can’t skip payment or ship twice.

Order statuses

Status	Description
pending	Order created, awaiting payment
confirmed	Payment received, awaiting fulfillment
processing	Being prepared for shipment
on_hold	Manual review required
completed	Shipped and delivered
cancelled	Cancelled before fulfillment
refunded	Payment refunded

Create an order

Orders are created through the checkout flow:

POST /api/v1/checkout/complete
{
  "cart_id": "uuid",
  "shipping_address": { ... },
  "payment_method": { "type": "stripe_elements" },
  "customer_email": "john@example.com",
  "selected_shipping_rate": { ... }
}

Get order details

GET /api/v1/orders/:id

Response includes order items, addresses, payment status, and fulfillment status.

Fulfillment

Create a fulfillment to mark items as shipped:

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

Partial fulfillment

Orders can be partially fulfilled — ship some items now, the rest later. Each fulfillment tracks its own items and tracking.

Order notes

Add internal notes to orders:

POST /api/v1/orders/:id/notes
{ "content": "Customer requested gift wrapping", "is_internal": true }

Refunds

Process a refund through the original payment gateway:

POST /api/v1/payments/:id/refund
{ "amount": 50.00, "reason": "Customer request" }

Partial refunds supported. The order status changes to refunded when fully refunded.

Order emails

• Order confirmation — sent after payment succeeds
• Shipping notification — sent when fulfillment is created
• Cancellation — sent when order is cancelled

Emails are sent via Postmark (or SMTP) with HTML templates.