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

# GET /v1/orders — история ваших покупок

> Пролистывайте историю покупок CSBoard с помощью keyset-пагинации. Фильтруйте по временному окну и статусу; каждый заказ включает сведения о доставке по предметам.

Эндпоинт orders возвращает историю ваших покупок, сначала самые новые, с keyset-пагинацией. Фильтруйте по временному окну и по статусу, затем переходите к более старым страницам, передавая `meta.next_cursor` обратно как `cursor`. Каждый заказ содержит разбивку по предметам со статусом доставки.

**Требуется аутентификация.** Отправьте ключ как `Authorization: Bearer csb_pub_...`.

## Query-параметры

<ParamField query="limit" type="integer" default="50">
  Результатов на странице. Минимум `1`, максимум `100`.
</ParamField>

<ParamField query="start_unix_time" type="integer">
  Возвращать только заказы, созданные не раньше этого Unix-таймстампа (в секундах).
</ParamField>

<ParamField query="end_unix_time" type="integer">
  Возвращать только заказы, созданные не позже этого Unix-таймстампа (в секундах).
</ParamField>

<ParamField query="status" type="string">
  Фильтр по статусу заказа. Одно из: `completed`, `hold`, `delivering`, `pending`, `cancelled`, `failed`.
</ParamField>

<ParamField query="cursor" type="string">
  Keyset-курсор из `meta.next_cursor` предыдущего ответа. Передайте его, чтобы получить следующую страницу.
</ParamField>

## Поля ответа

<ResponseField name="data" type="Order[]" required>
  Массив заказов для этой страницы.

  <Expandable title="Order object">
    <ResponseField name="order_id" type="string" required>
      CSBoard order id.
    </ResponseField>

    <ResponseField name="steam_id" type="string | null">
      Steam ID, на который были доставлены предметы, если известен.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Одно из: `completed`, `hold`, `delivering`, `pending`, `cancelled`, `failed`.
    </ResponseField>

    <ResponseField name="custom_id" type="string | null">
      Ваш собственный id, если вы задали его при покупке.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Всегда `"USD"`.
    </ResponseField>

    <ResponseField name="charged_total_usd" type="number" required>
      Итоговая сумма списания по заказу в USD.
    </ResponseField>

    <ResponseField name="item_count" type="integer" required>
      Количество предметов в заказе.
    </ResponseField>

    <ResponseField name="hold_until" type="datetime | null">
      Когда удерживаемые предметы заказа будут освобождены, либо `null`.
    </ResponseField>

    <ResponseField name="created_at" type="datetime" required>
      Временная метка создания в ISO 8601.
    </ResponseField>

    <ResponseField name="updated_at" type="datetime | null">
      Временная метка последнего обновления в ISO 8601, либо `null`.
    </ResponseField>

    <ResponseField name="items" type="OrderItem[]" required>
      Разбивка по предметам.

      <Expandable title="OrderItem object">
        <ResponseField name="market_hash_name" type="string | null" />

        <ResponseField name="price_usd" type="number | null" />

        <ResponseField name="status" type="string" required>
          Одно из: `hold`, `delivering`, `delivered`, `returned`.
        </ResponseField>

        <ResponseField name="tradable_at" type="datetime | null">
          Когда предмет выйдет из торгового холда Steam, либо `null`.
        </ResponseField>

        <ResponseField name="return_reason" type="string | null">
          Причина возврата предмета, если `status` равен `returned`. Одно из: `trade_timeout`, `declined`, `expired`, `rolled_back`, `unavailable`.
        </ResponseField>

        <ResponseField name="steam_trade_offer_id" type="string | null" />

        <ResponseField name="steam_trade_offer_finished_at" type="datetime | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object" required>
  <Expandable title="meta object">
    <ResponseField name="next_cursor" type="string | null" required>
      Передайте обратно как `cursor`, чтобы получить следующую страницу. `null` на последней странице.
    </ResponseField>

    <ResponseField name="per_page" type="integer" required>
      Размер страницы, использованный для этого ответа.
    </ResponseField>
  </Expandable>
</ResponseField>

## Пример запроса

```bash theme={null}
curl "https://csboard.com/v1/orders?status=completed&limit=50" \
  -H "Authorization: Bearer csb_pub_..."
```

## Пример ответа

```json theme={null}
{
  "data": [
    {
      "order_id": "ord_01J9Z3K8Q2",
      "steam_id": "76561198000000000",
      "status": "completed",
      "custom_id": "batch-2026-06-29-01",
      "currency": "USD",
      "charged_total_usd": 26.47,
      "item_count": 2,
      "hold_until": null,
      "created_at": "2026-06-29T17:12:04Z",
      "updated_at": "2026-06-29T17:15:40Z",
      "items": [
        {
          "market_hash_name": "AK-47 | Redline (Minimal Wear)",
          "price_usd": 14.37,
          "status": "delivered",
          "tradable_at": "2026-07-06T12:00:00Z",
          "return_reason": null,
          "steam_trade_offer_id": "5512345678",
          "steam_trade_offer_finished_at": "2026-06-29T17:15:40Z"
        }
      ]
    }
  ],
  "meta": { "next_cursor": "eyJpZCI6Im9yZF8wMUo5WjNLOFEyIn0=", "per_page": 50 }
}
```

## Коды ошибок

| HTTP-статус | Код                                   | Значение                                                                      |
| ----------- | ------------------------------------- | ----------------------------------------------------------------------------- |
| 401         | `missing_api_key` / `invalid_api_key` | Отсутствует или некорректный API-ключ.                                        |
| 422         | `invalid_request`                     | Некорректные query-параметры (например, `limit` вне допустимого диапазона).   |
| 429         | `rate_limit_exceeded`                 | Слишком много запросов. Подождите время, указанное в заголовке `Retry-After`. |


## OpenAPI

````yaml GET /orders
openapi: 3.1.0
info:
  title: CSBoard API
  version: 1.0.0
  description: >-
    Market data over the CSBoard marketplace — live listings, floats, stickers,
    minAsk prices, FX rates — plus opt-in buying straight from your balance.
    Free to read, key-gated, built for automation.
  contact:
    name: CSBoard
    url: https://csboard.com/docs
servers:
  - url: https://csboard.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Status
    description: Liveness and freshness probes.
  - name: Market data
    description: Read the live catalog, prices, and FX rates.
  - name: Trading
    description: Buy listings from your CSBoard balance. Opt-in, key-gated.
  - name: Account
    description: Your balance, settled funds, and trading status.
paths:
  /orders:
    get:
      tags:
        - Trading
      summary: List purchase history
      description: >-
        Your purchase history, newest first, with keyset pagination. Filter by
        time window and status. Pass `meta.next_cursor` back as `cursor` to walk
        older pages; `next_cursor` is null on the last page.
      operationId: listOrders
      parameters:
        - name: limit
          in: query
          description: Results per page. 1–100. Default 50.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: start_unix_time
          in: query
          description: Only orders created at or after this Unix timestamp (seconds).
          schema:
            type: integer
        - name: end_unix_time
          in: query
          description: Only orders created at or before this Unix timestamp (seconds).
          schema:
            type: integer
        - name: status
          in: query
          description: Filter by order status.
          schema:
            type: string
            enum:
              - completed
              - hold
              - delivering
              - pending
              - cancelled
              - failed
        - name: cursor
          in: query
          description: Keyset cursor from a previous response's `meta.next_cursor`.
          schema:
            type: string
      responses:
        '200':
          description: A page of orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  meta:
                    type: object
                    properties:
                      next_cursor:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Pass back as `cursor` for the next page. Null on the
                          last page.
                      per_page:
                        type: integer
                    required:
                      - next_cursor
                      - per_page
                required:
                  - data
                  - meta
              example:
                data:
                  - order_id: ord_01J9Z3K8Q2
                    steam_id: '76561198000000000'
                    status: completed
                    custom_id: batch-2026-06-29-01
                    currency: USD
                    charged_total_usd: 26.47
                    item_count: 2
                    hold_until: null
                    created_at: '2026-06-29T17:12:04Z'
                    updated_at: '2026-06-29T17:15:40Z'
                    items:
                      - market_hash_name: AK-47 | Redline (Minimal Wear)
                        price_usd: 14.37
                        status: delivered
                        tradable_at: '2026-07-06T12:00:00Z'
                        return_reason: null
                        steam_trade_offer_id: '5512345678'
                        steam_trade_offer_finished_at: '2026-06-29T17:15:40Z'
                meta:
                  next_cursor: eyJpZCI6Im9yZF8wMUo5WjNLOFEyIn0=
                  per_page: 50
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: invalid_request
                detail: limit must be between 1 and 100.
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Order:
      type: object
      properties:
        order_id:
          type: string
        steam_id:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - completed
            - hold
            - delivering
            - pending
            - cancelled
            - failed
        custom_id:
          type:
            - string
            - 'null'
          description: Your own id, if you set one at purchase time.
        currency:
          type: string
          example: USD
        charged_total_usd:
          type: number
        item_count:
          type: integer
        hold_until:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
      required:
        - order_id
        - status
        - currency
        - charged_total_usd
        - item_count
        - created_at
        - items
    Error:
      type: object
      description: >-
        All errors return { code, detail }. Some carry extra fields (e.g.
        price_moved adds current_total_usd, insufficient_balance adds
        required_usd/current_usd).
      properties:
        code:
          type: string
          description: >-
            Machine-readable error code, e.g. rate_limit_exceeded,
            trading_not_enabled, price_moved.
        detail:
          type: string
          description: Human-readable explanation.
      required:
        - code
    OrderItem:
      type: object
      properties:
        market_hash_name:
          type:
            - string
            - 'null'
        price_usd:
          type:
            - number
            - 'null'
        status:
          type: string
          enum:
            - hold
            - delivering
            - delivered
            - returned
        tradable_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the item leaves Steam trade hold, or null.
        return_reason:
          type:
            - string
            - 'null'
          enum:
            - trade_timeout
            - declined
            - expired
            - rolled_back
            - unavailable
            - null
          description: Why the item was returned, if its status is `returned`.
        steam_trade_offer_id:
          type:
            - string
            - 'null'
        steam_trade_offer_finished_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - status
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unauthorized
            message: Missing or invalid API key.
    RateLimited:
      description: Rate limit exceeded. Includes a Retry-After header.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: rate_limit_exceeded
            message: Too many requests.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Send your key as a Bearer token on every request: `Authorization: Bearer
        csb_pub_...`. Generate keys in your CSBoard profile.

````