Admin Orders API — Manage Orders and Status Transitions

The Admin Orders API gives you full visibility into every order placed on the platform and the ability to drive each order through its lifecycle. You can query the entire order queue with flexible filtering, inspect line-item snapshots and payment details for any individual order, and trigger status transitions that automatically apply side effects — such as creating shipment records, releasing reserved inventory, or marking payments as refunded. All write operations are guarded by CSRF token validation.

All endpoints under /admin/orders require an authenticated session with the ADMIN or SUPER_ADMIN role. For every PATCH request, first call GET /auth/csrf-token and pass the returned token in the x-csrf-token header.

Order Status Lifecycle

Every order begins in pending status and advances through a fixed set of allowed transitions. The server enforces the transition matrix — any attempt to move to a disallowed status returns 409 Conflict.

From Status	Allowed Next Statuses
`pending`	`confirmed`, `cancelled`
`confirmed`	`processing`, `cancelled`
`processing`	`shipped`, `cancelled`
`shipped`	`delivered`, `returned`
`delivered`	`returned`, `refunded`
`cancelled`	(terminal — no further transitions)
`returned`	`refunded`
`refunded`	(terminal — no further transitions)

Status transitions trigger automatic side effects on the server:

→ shipped — creates a shipment record with the provided carrier and optional tracking_number.
→ cancelled — releases any reserved or committed inventory back to quantity_available for the affected variants.
→ refunded — marks the associated payment record as refunded.

You do not need to call separate inventory or payment endpoints — the transition endpoint handles all side effects atomically.

List Orders

Retrieve a paginated list of all orders across all customers. Filter by status, search by order number or customer name, and narrow results to a specific date window.

GET /admin/orders

Query Parameters

integer

default:"1"

Page number (1-based).

integer

default:"20"

Results per page. Range: 1–100.

string

Filter by order status. Accepted values: pending, confirmed, processing, shipped, delivered, cancelled, returned, refunded.

string

Free-text search across order number and customer name/email.

string

ISO 8601 datetime (with timezone offset) for the inclusive lower bound of the placed_at range. Example: 2024-01-01T00:00:00.000Z.

string

ISO 8601 datetime for the inclusive upper bound of placed_at. Must be greater than or equal to placed_from. Example: 2024-12-31T23:59:59.000Z.

string

default:"-placed_at"

Sort field. Prefix with - for descending. Accepted values: placed_at, -placed_at, order_number, -order_number, total_amount, -total_amount, customer_name, -customer_name.

Response

boolean

Always true on a 200 response.

array

Array of order summary objects.

Show Order summary fields

string

Unique order identifier, prefixed ord_.

string

Human-readable order number, e.g. ORD-0042.

string

Current order status.

string

Order total as a decimal string, e.g. "149.99".

string

ISO 8601 UTC timestamp of when the order was placed.

object

Pagination metadata.

Show Pagination fields

integer

Total matching orders.

integer

Total number of pages.

boolean

Whether a next page exists.

boolean

Whether a previous page exists.

Example — list all shipped orders from Q1 2024

curl "https://api.example.com/api/v1/admin/orders?status=shipped&placed_from=2024-01-01T00:00:00.000Z&placed_to=2024-03-31T23:59:59.000Z&sort=-placed_at" \
  -H "Cookie: session=<your-session-cookie>"

200 Response

{
  "success": true,
  "data": [
    {
      "public_id": "ord_01HABC",
      "order_number": "ORD-0099",
      "status": "shipped",
      "total_amount": "149.99",
      "placed_at": "2024-02-10T14:32:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Get Order Detail

Retrieve the full detail of a single order, including all line items with frozen price snapshots, the shipping address, payment information, and shipment tracking data (if available).

GET /admin/orders/{order_public_id}

Path Parameters

string

required

The order’s public ID. Must start with ord_.

Response

boolean

Always true on a 200 response.

object

Full order detail object.

Show Order detail fields

string

Unique order identifier, prefixed ord_.

string

Human-readable order number.

string

Current order status.

string

Order total as a decimal string.

string

ISO 8601 UTC timestamp of order placement.

object

The shipping address captured at order time.

array

Line items, each with variant_public_id, quantity, unit_price (decimal string, frozen at purchase time), and line_total (decimal string).

object

Payment summary with status and method.

object | null

Shipment details when available: carrier and tracking_number. null before the order is shipped.

Example — fetch a single order

curl https://api.example.com/api/v1/admin/orders/ord_01HABC \
  -H "Cookie: session=<your-session-cookie>"

200 Response

{
  "success": true,
  "data": {
    "public_id": "ord_01HABC",
    "order_number": "ORD-0099",
    "status": "confirmed",
    "total_amount": "149.99",
    "placed_at": "2024-02-10T14:32:00.000Z",
    "address": {
      "line1": "42 Market Street",
      "city": "London",
      "country": "GB",
      "postal_code": "EC1A 1BB"
    },
    "items": [
      {
        "variant_public_id": "var_01HXYZ",
        "quantity": 2,
        "unit_price": "59.99",
        "line_total": "119.98"
      }
    ],
    "payment": {
      "status": "paid",
      "method": "card"
    },
    "shipment": null
  }
}

Update Order Status

Advance an order to the next permitted status. Pass the target status in the request body. When transitioning to shipped, you must also provide a carrier; tracking_number is optional but recommended.

PATCH /admin/orders/{order_public_id}

Invalid status transitions — for example, attempting to move an order from pending directly to shipped, or re-opening a cancelled order — return 409 Conflict. Always check the transition table above before calling this endpoint. A 409 is also returned if a concurrent update wins a row-lock race.

Path Parameters

string

required

The order’s public ID. Must start with ord_.

Request Body

string

required

The target status. Accepted values: confirmed, processing, shipped, delivered, cancelled, returned, refunded.

string

Shipping carrier name (e.g. "DHL", "FedEx"). Required when status is shipped. Maximum 100 characters.

string

Carrier tracking number. Optional, but strongly recommended when transitioning to shipped. Maximum 100 characters.

CSRF=$(curl -s https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-cookie>" | jq -r '.data.csrf_token')

curl -X PATCH https://api.example.com/api/v1/admin/orders/ord_01HABC \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped",
    "carrier": "DHL",
    "tracking_number": "TRK98765432"
  }'

CSRF=$(curl -s https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-cookie>" | jq -r '.data.csrf_token')

curl -X PATCH https://api.example.com/api/v1/admin/orders/ord_01HABC \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cancelled"
  }'

CSRF=$(curl -s https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-cookie>" | jq -r '.data.csrf_token')

curl -X PATCH https://api.example.com/api/v1/admin/orders/ord_01HABC \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "refunded"
  }'

200 Response — shipped

{
  "success": true,
  "data": {
    "public_id": "ord_01HABC",
    "order_number": "ORD-0099",
    "status": "shipped",
    "total_amount": "149.99",
    "placed_at": "2024-02-10T14:32:00.000Z",
    "shipment": {
      "carrier": "DHL",
      "tracking_number": "TRK98765432"
    }
  }
}

409 Response — illegal transition

{
  "success": false,
  "error": {
    "code": "ILLEGAL_TRANSITION",
    "message": "Cannot transition from 'cancelled' to 'confirmed'."
  }
}

Catalog Management

Operations

Users & Moderation

Analytics & Audit

Admin Orders API — Manage Orders and Status Transitions

Order Status Lifecycle

List Orders

Query Parameters

Response

Get Order Detail

Path Parameters

Response

Update Order Status

Path Parameters

Request Body

​Order Status Lifecycle

​List Orders

​Query Parameters

​Response

​Get Order Detail

​Path Parameters

​Response

​Update Order Status

​Path Parameters

​Request Body

Order Status Lifecycle

List Orders

Query Parameters

Response

Get Order Detail

Path Parameters

Response

Update Order Status

Path Parameters

Request Body