Buy

Create merchant purchases. All require Authorization: Bearer mer_live_… (Authentication).

To fetch or list orders after creation, see Purchases.

Create a purchase

POST /api/v1/merchant/buy

One item per call. To buy multiple items, fan out client-side — each call is independent, debits separately, and emits its own webhook chain.

Request body

Example

curl -X POST https://api.tradeon.market/api/v1/merchant/buy \
  -H "Authorization: Bearer mer_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "8e42bb9c-2e11-4d40-9d51-6e5d2d4b2cf1",
    "max_price": 20.00,
    "custom_id": "order-2026-05-05-0001",
    "target_steam_id": "76561198000000000",
    "target_trade_url": "https://steamcommunity.com/tradeoffer/new/?partner=12345&token=abc123"
  }'

201 Created:

{
  "purchase_id": "1a2b3c4d-5e6f-7080-91a2-b3c4d5e6f708",
  "custom_id": "order-2026-05-05-0001",
  "status": "created",
  "item": {
    "market_hash_name": "AK-47 | Redline (Field-Tested)",
    "price": 18.40,
    "delivery_type": "instant",
    "estimated_delivery_minutes": 2
  },
  "balance_after": 481.60,
  "created_at": "2026-05-05T16:00:00.000Z"
}

balance_after reflects the debit (max_price minus actual fill — refunded immediately if the live price was lower). delivery_type / estimated_delivery_minutes are a snapshot of the catalogue values at purchase time; see CatalogItem schema for semantics.

Errors

Create a purchase (synchronous)

POST /api/v1/merchant/buy-sync

Same request body, validation, debit, idempotency, and webhook chain as POST /buy — the only difference is when the response returns. POST /buy returns 201 immediately with status: "created"; POST /buy-sync holds the response until the upstream provider has acknowledged the purchase (or rejected it), up to a 30-second ceiling.

Use it when you want a single round-trip to tell you whether the provider accepted the order, instead of creating the order and then watching webhooks / polling for the first state transition.

Response

A 202 is not a failure: the purchase exists and keeps progressing exactly like a POST /buy order. If your HTTP client disconnects while waiting, the order is not cancelled — it continues server-side.

Errors

All POST /buy pre-check errors apply identically (returned before the order is created). Additionally, when the provider rejects an already-created order:

Example

curl -X POST https://api.tradeon.market/api/v1/merchant/buy-sync \
  -H "Authorization: Bearer mer_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "8e42bb9c-2e11-4d40-9d51-6e5d2d4b2cf1",
    "max_price": 20.00,
    "custom_id": "order-2026-05-05-0001",
    "target_steam_id": "76561198000000000",
    "target_trade_url": "https://steamcommunity.com/tradeoffer/new/?partner=12345&token=abc123"
  }'

Buy by name (with auto-retry)

POST /api/v1/merchant/buy-by-name

Instead of pinning a specific item_id, you describe what you want to buy (market_hash_name + max_price + optional delivery-time ceiling) and we pick the cheapest matching active item, attempt purchase, and — if the provider rejects it — automatically retry on the next cheapest item. Up to 5 attempts within a shared 30-second budget.

Use it for fungible inventory (“buy me any MIBR Budapest 2025 sticker under $0.05”) where you do not want to manage retries on item-specific races (locked / sold / price moved) yourself.

Request body

{
  "market_hash_name": "Sticker | MIBR | Budapest 2025",
  "max_price": 0.05,
  "trade_url": "https://steamcommunity.com/tradeoffer/new/?partner=…&token=…",
  "custom_id": "order-2026-05-05-0001",
  "estimated_time": 60
}

Response

The response body is identical to POST /buy-sync and describes the final winning order (or the last in-flight order if the timeout elapsed). Intermediate failed attempts are not visible in the response — they exist as separate Order rows in the database (sharing the same custom_id, indexed 1..5) but never trigger a purchase.created webhook.

Errors

Example

curl -X POST https://api.tradeon.market/api/v1/merchant/buy-by-name \
  -H "Authorization: Bearer mer_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "market_hash_name": "Sticker | MIBR | Budapest 2025",
    "max_price": 0.05,
    "trade_url": "https://steamcommunity.com/tradeoffer/new/?partner=12345&token=abc123",
    "custom_id": "order-2026-05-05-0001",
    "estimated_time": 60
  }'

When to use which endpoint

Idempotency

Same custom_id + identical (item_id, target_steam_id, target_trade_url) and the existing order’s live price still ≤ the new max_price → replays the original 201 body without debiting again. Same custom_id with different parameters (different item, different recipient, or a max_price now lower than the existing order’s price) → 409 MERCHANT_DUPLICATE_CUSTOM_ID.

For POST /buy-by-name, idempotency keys off custom_id alone: a re-submit after the previous call reached a terminal state (completed / sent_to_steam / failed / refunded) replays that final order. A re-submit while a previous call is still in flight returns 202 with the in-flight order unchanged — it does not start a second retry cycle (that would double-charge the merchant under one custom_id).

Full retry semantics: Errors → Idempotency.