> ## Documentation Index
> Fetch the complete documentation index at: https://codebyahmed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Orders API — Manage Orders and Status Transitions

> List all customer orders, view full order detail, and advance orders through the status lifecycle from pending to delivered, cancelled, or refunded.

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.

<Note>
  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.
</Note>

***

## 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)* |

<Note>
  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.
</Note>

***

## 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

<ParamField query="page" type="integer" default="1">
  Page number (1-based).
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Results per page. Range: 1–100.
</ParamField>

<ParamField query="status" type="string">
  Filter by order status. Accepted values: `pending`, `confirmed`, `processing`, `shipped`, `delivered`, `cancelled`, `returned`, `refunded`.
</ParamField>

<ParamField query="search" type="string">
  Free-text search across order number and customer name/email.
</ParamField>

<ParamField query="placed_from" type="string">
  ISO 8601 datetime (with timezone offset) for the inclusive lower bound of the `placed_at` range. Example: `2024-01-01T00:00:00.000Z`.
</ParamField>

<ParamField query="placed_to" type="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`.
</ParamField>

<ParamField query="sort" type="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`.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Always `true` on a 200 response.
</ResponseField>

<ResponseField name="data" type="array">
  Array of order summary objects.

  <Expandable title="Order summary fields">
    <ResponseField name="public_id" type="string">
      Unique order identifier, prefixed `ord_`.
    </ResponseField>

    <ResponseField name="order_number" type="string">
      Human-readable order number, e.g. `ORD-0042`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current order status.
    </ResponseField>

    <ResponseField name="total_amount" type="string">
      Order total as a decimal string, e.g. `"149.99"`.
    </ResponseField>

    <ResponseField name="placed_at" type="string">
      ISO 8601 UTC timestamp of when the order was placed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Pagination metadata.

  <Expandable title="Pagination fields">
    <ResponseField name="total" type="integer">Total matching orders.</ResponseField>
    <ResponseField name="totalPages" type="integer">Total number of pages.</ResponseField>
    <ResponseField name="hasNext" type="boolean">Whether a next page exists.</ResponseField>
    <ResponseField name="hasPrev" type="boolean">Whether a previous page exists.</ResponseField>
  </Expandable>
</ResponseField>

```bash Example — list all shipped orders from Q1 2024 theme={null}
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>"
```

```json 200 Response theme={null}
{
  "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

<ParamField path="order_public_id" type="string" required>
  The order's public ID. Must start with `ord_`.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Always `true` on a 200 response.
</ResponseField>

<ResponseField name="data" type="object">
  Full order detail object.

  <Expandable title="Order detail fields">
    <ResponseField name="public_id" type="string">
      Unique order identifier, prefixed `ord_`.
    </ResponseField>

    <ResponseField name="order_number" type="string">
      Human-readable order number.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current order status.
    </ResponseField>

    <ResponseField name="total_amount" type="string">
      Order total as a decimal string.
    </ResponseField>

    <ResponseField name="placed_at" type="string">
      ISO 8601 UTC timestamp of order placement.
    </ResponseField>

    <ResponseField name="address" type="object">
      The shipping address captured at order time.
    </ResponseField>

    <ResponseField name="items" type="array">
      Line items, each with `variant_public_id`, `quantity`, `unit_price` (decimal string, frozen at purchase time), and `line_total` (decimal string).
    </ResponseField>

    <ResponseField name="payment" type="object">
      Payment summary with `status` and `method`.
    </ResponseField>

    <ResponseField name="shipment" type="object | null">
      Shipment details when available: `carrier` and `tracking_number`. `null` before the order is shipped.
    </ResponseField>
  </Expandable>
</ResponseField>

```bash Example — fetch a single order theme={null}
curl https://api.example.com/api/v1/admin/orders/ord_01HABC \
  -H "Cookie: session=<your-session-cookie>"
```

```json 200 Response theme={null}
{
  "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}
```

<Warning>
  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.
</Warning>

### Path Parameters

<ParamField path="order_public_id" type="string" required>
  The order's public ID. Must start with `ord_`.
</ParamField>

### Request Body

<ParamField body="status" type="string" required>
  The target status. Accepted values: `confirmed`, `processing`, `shipped`, `delivered`, `cancelled`, `returned`, `refunded`.
</ParamField>

<ParamField body="carrier" type="string">
  Shipping carrier name (e.g. `"DHL"`, `"FedEx"`). **Required** when `status` is `shipped`. Maximum 100 characters.
</ParamField>

<ParamField body="tracking_number" type="string">
  Carrier tracking number. Optional, but strongly recommended when transitioning to `shipped`. Maximum 100 characters.
</ParamField>

<CodeGroup>
  ```bash Advance to shipped theme={null}
  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"
    }'
  ```

  ```bash Cancel an order theme={null}
  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"
    }'
  ```

  ```bash Mark as refunded theme={null}
  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"
    }'
  ```
</CodeGroup>

```json 200 Response — shipped theme={null}
{
  "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"
    }
  }
}
```

```json 409 Response — illegal transition theme={null}
{
  "success": false,
  "error": {
    "code": "ILLEGAL_TRANSITION",
    "message": "Cannot transition from 'cancelled' to 'confirmed'."
  }
}
```