> ## 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/claim — Release a Held Order
> Release delivery of a held (escrow) order once its hold has cleared. Some held orders deliver automatically; others require this explicit claim.
Some orders land in a **held** state: the item sits under a marketplace escrow window and cannot be delivered until that window clears. A held order shows `status: "hold"` and a `hold_until` timestamp in `GET /v1/orders` and `GET /v1/orders/{id}`.
Once `hold_until` has passed:
* **Some held orders deliver automatically** — you do nothing, and calling this endpoint returns `claimed: false` as a harmless no-op.
* **Other held orders must be claimed** — you call this endpoint to release the trade. Without a claim they stay held indefinitely.
Because you cannot tell the two apart from the outside, the safe pattern is: **after `hold_until` passes, call claim once.** If the order was the auto-delivering kind, you get a no-op. If it needed a claim, it is released.
Prefer not to poll and claim per order? Set the account-wide [`autoclaim`](/api-reference/post-orders) flag to `true` and every held order is released automatically the moment its hold clears — no claim calls needed.
## Recommended flow
1. Place a buy with `POST /v1/orders` or `POST /v1/market/buy`.
2. Poll `GET /v1/orders/{id}`. While the order reads `status: "hold"`, check `hold_until`.
3. Once `hold_until` is in the past, `POST /v1/orders/{id}/claim`.
4. On `claimed: true`, the marketplace sends a Steam trade offer to your trade URL. **Your bot must accept it within \~15 minutes** or the trade is cancelled and your balance refunded.
## Responses at a glance
| Status | Meaning |
| ---------------------- | --------------------------------------------------------------------------------------- |
| `200` `claimed: true` | Trade released now; `steam_trade_offer_id` returned. Accept within \~15 min. |
| `200` `claimed: false` | This order delivers automatically; nothing to do. |
| `409 not_claimable` | Order is not in a held state (already delivering/completed/failed). |
| `425 hold_not_cleared` | Still inside the hold window — retry after the returned `hold_until`. |
| `502 delivery_failed` | Marketplace rejected the release. If the hold was cancelled upstream, `refunded: true`. |
| `404 order_not_found` | No such order on this account. |
The claim is idempotent while a release is in flight — a duplicate call returns a conflict, never a double delivery. Retrying after a network timeout is safe.
## OpenAPI
````yaml POST /orders/{id}/claim
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/{id}/claim:
post:
tags:
- Trading
summary: Claim a held order
description: >-
Release delivery of a held (escrow) order once its hold has cleared.
Held orders appear with `status: "hold"` and a `hold_until` timestamp;
after `hold_until` passes some orders deliver automatically while others
require this explicit claim. On a successful claim the marketplace sends
a Steam trade offer to your trade URL that your bot must accept within
~15 minutes or it is cancelled and refunded. Idempotent: a duplicate
call while one is in flight returns a conflict, never a double-send.
Prefer the account-wide `autoclaim` setting if you would rather never
call this per order.
operationId: claimOrder
parameters:
- name: id
in: path
required: true
description: CSBoard order id of the held order to claim.
schema:
type: string
responses:
'200':
description: >-
Claim accepted. `claimed: true` means the trade was released now;
`claimed: false` means this order delivers automatically and no
action was needed.
content:
application/json:
schema:
type: object
properties:
order_id:
type: string
status:
type: string
enum:
- delivering
- hold
claimed:
type: boolean
steam_trade_offer_id:
type:
- string
- 'null'
description: Present when claimed just released a trade offer.
detail:
type: string
description: Present on the auto-delivering no-op case.
required:
- order_id
- status
- claimed
examples:
released:
summary: Manual hold released
value:
order_id: ord_01J9Z3K8Q2
status: delivering
claimed: true
steam_trade_offer_id: '5512345678'
auto:
summary: Auto-delivering hold (no-op)
value:
order_id: ord_01J9Z3K8Q2
status: hold
claimed: false
detail: >-
This order delivers automatically once its hold clears; no
claim needed.
'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 is not in a claimable (held) state, or cannot be claimed
right now.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: not_claimable
detail: Order status is 'completed'; only held orders can be claimed.
'425':
description: The item is still under its hold window. Retry after `hold_until`.
content:
application/json:
schema:
type: object
properties:
code:
type: string
hold_until:
type:
- string
- 'null'
format: date-time
detail:
type: string
example:
code: hold_not_cleared
hold_until: '2026-07-02T20:00:00Z'
detail: Item is still under its hold window; retry after hold_until.
'429':
$ref: '#/components/responses/RateLimited'
'502':
description: >-
Withdraw was attempted but the marketplace rejected it. If the hold
was cancelled upstream your balance was refunded (`refunded: true`).
content:
application/json:
schema:
type: object
properties:
code:
type: string
detail:
type: string
refunded:
type: boolean
example:
code: delivery_failed
detail: The hold was cancelled upstream; your balance was refunded.
refunded: true
components:
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.
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.
````