---
title: "List orders"
method: GET
path: "/orders"
tags: ["Orders"]
---

# List orders

`GET /orders`

Retrieve a paginated list of orders for your organization.

    Supports filtering by order status:
    - `pending` - Awaiting approval
    - `confirmed` - Approved and in progress
    - `completed` - Fulfilled
    - `cancelled` - Cancelled by customer
    - `refused` - Refused by organization

    The `created_after` parameter (ISO-8601 datetime) enables incremental polling:
    pass the `created_at` of the last order you received to get only newer ones.

    Orders are returned in reverse chronological order (newest first) by default.

    **Response shape note:** `data` is an object `{items, total, limit, offset}` for
    backward compatibility. The top-level `meta` object `{limit, offset, total_items}`
    is the standard pagination envelope and is always present.

    Authentication:
    - API key with READ or READ_WRITE permission

## Query parameters

- `status` string, nullable — Filter by order status
- `limit` integer — Number of items to return
- `offset` integer — Number of items to skip
- `sort` string, nullable — Sort field. Prefix with '-' for descending order. Available: created_at, status, total_amount. A deterministic id tiebreaker is always appended. Example: '-created_at' (newest first, default), 'total_amount' (cheapest first).
- `created_after` string, date-time, nullable — Return only orders created strictly after this ISO-8601 datetime (exclusive). Useful for incremental polling: pass the created_at of the last received order. Example: '2024-01-30T10:00:00Z'.

## Response `200`

Successfully retrieved orders list

- object
  - `ok` boolean
  - `data` object — Backward-compatible wrapper. Use top-level meta for pagination.
    - `items` object[]
    - `total` integer
    - `limit` integer
    - `offset` integer
  - `meta` object
    - `limit` integer
    - `offset` integer
    - `total_items` integer

## Other responses

- `401` — Invalid or missing API key
- `403` — Insufficient permissions

---

[API](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1.md) · [All operations](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yourang/yourang-ai-external-api-v1/revisions/49680ee64400/schema)