> ## 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 购买历史。可按时间区间和状态过滤；每个订单包含逐件商品的交付详情。

orders 端点返回您的购买历史，按时间倒序排列，使用键集分页。可按时间窗口和状态过滤，然后通过将 `meta.next_cursor` 作为 `cursor` 传回，遍历更早的页面。每个订单都附带逐件商品明细及其交付状态。

**需要身份验证。** 请将密钥作为 `Authorization: Bearer csb_pub_...` 发送。

## 查询参数

<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">
  来自上次响应中 `meta.next_cursor` 的键集游标。传入以获取下一页。
</ParamField>

## 响应字段

<ResponseField name="data" type="Order[]" required>
  本页订单数组。

  <Expandable title="Order object">
    <ResponseField name="order_id" type="string" required>
      CSBoard 订单 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>
      订单的扣款总额，单位美元。
    </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`                     | 查询参数无效（例如 `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.

````