Orders API

Overview

The Orders API lets you manage orders programmatically. All admin endpoints are under /api/admin/orders.

Endpoints

Query parameters

• search — search by order number, customer name, or email
• status — filter by order status
• excludeStatus — exclude specific statuses
• source — filter by order source
• page and limit — pagination

Creating orders via API

When creating an order via API, you can specify:

• Customer (by ID or create inline)
• Line items with product variants and quantities
• Order source (IN_PERSON, PRIVATE_COMMISSION, etc.)
• Sales rep assignment
• Custom order date (for backdating)
• Notes and tags

Example: create an in-person order

curl https://yourdomain.com/api/admin/orders \
  -X POST \
  -H "Authorization: Bearer kat_live_..." \
  -H "Idempotency-Key: 8b8a2b9e-4a5c-4f9d-9e2a-1f3a8b8a2b9e" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "IN_PERSON",
    "customer": { "email": "alice@example.com", "firstName": "Alice", "lastName": "Smith" },
    "salesRepId": "emp_01HX...",
    "lineItems": [
      { "variantId": "var_01HX...", "quantity": 1, "price": 4800.00 }
    ],
    "currency": "USD",
    "tax": 384.00,
    "subtotal": 4800.00,
    "total": 5184.00,
    "paymentStatus": "PAID",
    "paymentMethod": "CARD_TERMINAL",
    "note": "Walk-in, sized to 6.5"
  }'

Status transitions

Use PATCH /api/admin/orders/[id] with { "status": "..." }. Valid transitions:

• PENDING → PAID | CANCELLED
• PAID → IN_PRODUCTION | PROCESSING | REFUNDED
• IN_PRODUCTION → PROCESSING
• PROCESSING → SHIPPED
• SHIPPED → DELIVERED

Invalid transitions return 422 with code: "invalid_transition" and the allowed next states in the response body.

Webhooks emitted

• order.created — fired on POST
• order.updated — fired on any PATCH
• order.paid — when payment status crosses to PAID
• order.shipped — when status moves to SHIPPED (includes tracking number)
• order.cancelled, order.refunded

Related

• Customers API
• Webhooks
• Managing orders (admin guide)