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

# POST /v1/orders/:id/cancel — 取消尚未交付的订单

> 取消尚无人发货的订单，款项退回您的余额。人工交付的订单在购买 31 分钟后可取消，其他订单在 15 分钟后可取消。

部分订单由人工交付：Steam 交易由真人（或较慢的处理台）发送，最长可能需要 12 小时。此类订单在 `GET /v1/orders` 和 `GET /v1/orders/{id}` 中显示为 `delivery_type: "manual"`，可能会长时间停留在 `delivering` 状态且没有交易报价。`delivery_deadline_at` 表示卖家的交付截止时间。如果卖家未能按时交付，订单会被自动取消并退款。

如果您不想再等，可以自行取消订单。无需请求体。以下情况可以取消：

* **人工交付的订单**：购买 31 分钟后卖家仍未发送任何内容。
* **持有中的订单**：在解除封禁之前，且货源允许取消。
* **其他任何订单**：购买 15 分钟后仍未交付，没有交易报价，且上游没有正在进行的操作。

玩家（P2P）挂单无法通过此接口取消。如果卖家错过 `delivery_deadline_at`，该订单会自动关闭并退款。

## 推荐流程

1. 使用 `POST /v1/orders` 或 `POST /v1/market/buy` 下单购买。
2. 轮询 `GET /v1/orders/{id}`（或监听 `order.updated` 网络钩子），查看 `delivery_type` 和 `delivery_deadline_at`。
3. 如果 `manual` 订单仍没有交易报价且您不再需要它，在 31 分钟后调用 `POST /v1/orders/{id}/cancel`。
4. 收到 `425 too_early` 时，在 `retry_after_sec` 秒后重试。收到 `200` 时，款项已退回余额。收到 `202` 时，款项会在几分钟内随订单的下一次更新到账。

## 响应一览

| 状态 | 含义 |
| - | - |
| `200` `refunded: true` | 已取消并退款到您的余额。对已取消的订单调用也返回相同结果。 |
| `202` `refunded: false` | 取消已提交。退款会在几分钟内随订单的下一次更新到账（网络钩子或 `GET /v1/orders/{id}`）。 |
| `425 too_early` | 尚未开放取消（人工交付为 31 分钟，其他为 15 分钟）。请在返回的 `retry_after_sec` 之后重试。 |
| `409 offer_sent` | Steam 交易报价已发出。请在 Steam 中接受或拒绝。 |
| `409 in_progress` | 交付或取消已在进行中。如果交付失败，订单会自动退款。 |
| `409 not_cancellable` | 订单已无法取消：已交付、已结束、属于 P2P 挂单或不符合条件。 |
| `429 cancel_limit_reached` | 近期取消次数过多。请稍后再试。 |
| `503 cancel_unavailable` | 暂时无法在上游核实订单。未做任何更改，请稍后重试。 |
| `404 order_not_found` | 此账户下不存在该订单。 |

> [!WARNING]
>
> 取消是幂等的：对已取消的订单再次调用会返回相同的 `200`，绝不会重复退款。网络超时或 `503` 后重试是安全的。


## OpenAPI

````yaml POST /orders/{id}/cancel
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: Instant Sell
    description: >-
      Sell CS2, Dota 2 and Rust items from any Steam inventory to the CSBoard
      network and get paid to your balance. Invite-only.
  - name: P2P
    description: >-
      List your own CS2 skins on the CSBoard P2P market. Free — any valid key,
      no balance requirement.
  - name: Account
    description: Your balance, settled funds, and trading status.
  - name: Webhooks
    description: Register an endpoint and receive signed order updates instead of polling.
paths:
  /orders/{id}/cancel:
    post:
      tags:
        - Trading
      summary: Cancel an undelivered order
      description: >-
        Cancel an order nobody has shipped yet; the money goes back to your
        balance. No request body. Cancel opens 31 minutes after purchase for a
        `manual` delivery order whose seller has sent nothing, before the unban
        for a held order (where the source allows it), and 15 minutes after
        purchase for any other order that is still undelivered, with no trade
        offer and nothing in flight upstream. A player's (P2P) lot cannot be
        cancelled here; it is cancelled and refunded automatically if the seller
        misses `delivery_deadline_at`. Idempotent: calling it on an already
        cancelled order returns the same `200`.
      operationId: cancelOrder
      parameters:
        - name: id
          in: path
          required: true
          description: CSBoard order id of the order to cancel.
          schema:
            type: string
      responses:
        '200':
          description: >-
            Cancelled and refunded to your balance. Also the answer for an order
            that was already cancelled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_id:
                    type: string
                  cancelled:
                    type: boolean
                  refunded:
                    type: boolean
                    description: >-
                      `true`: the money is already back on your balance.
                      `false`: the cancel is placed and the refund lands with
                      the order's next update.
                  detail:
                    type: string
                    description: Present when the refund is still on its way (`202`).
                required:
                  - order_id
                  - cancelled
                  - refunded
              example:
                order_id: ord_01J9Z3K8Q2
                cancelled: true
                refunded: true
        '202':
          description: >-
            Cancel placed. The refund lands on your balance within minutes and
            shows up with the order's next update (`order.updated` webhook, `GET
            /orders/{id}`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_id:
                    type: string
                  cancelled:
                    type: boolean
                  refunded:
                    type: boolean
                    description: >-
                      `true`: the money is already back on your balance.
                      `false`: the cancel is placed and the refund lands with
                      the order's next update.
                  detail:
                    type: string
                    description: Present when the refund is still on its way (`202`).
                required:
                  - order_id
                  - cancelled
                  - refunded
              example:
                order_id: ord_01J9Z3K8Q2
                cancelled: true
                refunded: false
                detail: >-
                  Cancel placed; the refund lands on your balance within
                  minutes.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No order with that id on this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: order_not_found
                detail: No such order on this account.
        '409':
          description: >-
            The order cannot be cancelled. `offer_sent`: the Steam trade offer
            is already out — accept or decline it in Steam. `in_progress`:
            delivery or a cancel is already running; if delivery fails the order
            is refunded automatically. `not_cancellable`: the order is
            delivered, finished, a player's (P2P) lot, or not eligible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                offer_sent:
                  summary: Trade offer already sent
                  value:
                    code: offer_sent
                    detail: >-
                      The Steam trade offer is already out; accept or decline it
                      in Steam.
                in_progress:
                  summary: Delivery or cancel already running
                  value:
                    code: in_progress
                    detail: >-
                      Delivery is in progress; if it fails, the order is
                      refunded automatically.
                not_cancellable:
                  summary: No longer cancellable
                  value:
                    code: not_cancellable
                    detail: This order can no longer be cancelled.
        '425':
          description: >-
            Cancel is not open yet: 31 minutes after purchase for `manual`
            delivery, 15 minutes otherwise. Retry after `retry_after_sec`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  detail:
                    type: string
                  retry_after_sec:
                    type: integer
                    description: Seconds until cancel opens.
              example:
                code: too_early
                detail: Cancel opens 15 minutes after purchase.
                retry_after_sec: 540
        '429':
          description: >-
            `cancel_limit_reached`: too many cancels for now — try again later.
            `rate_limit_exceeded`: the per-key trading budget is spent — wait
            `Retry-After` seconds.
          headers:
            Retry-After:
              description: Seconds to wait before retrying (on `rate_limit_exceeded`).
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                cancel_limit_reached:
                  summary: Too many cancels
                  value:
                    code: cancel_limit_reached
                    detail: Cancel limit reached for now; try again later.
                rate_limit_exceeded:
                  summary: Rate limit
                  value:
                    code: rate_limit_exceeded
                    detail: Trading rate limit of 10000 requests/min exceeded.
        '503':
          description: >-
            The order could not be checked upstream right now. Nothing was
            changed; retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: cancel_unavailable
                detail: >-
                  The order could not be checked upstream right now and nothing
                  was changed; retry shortly.
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key (`missing_api_key` or `invalid_api_key`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: missing_api_key
            detail: >-
              Provide your API key via `Authorization: Bearer csb_pub_…`.
              Generate one at https://csboard.com/profile?tab=api
  schemas:
    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
  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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.