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. Each distinct purchase debits separately and has its own events. Persist one custom_id with your business order before sending the POST, and keep it for recovery after timeouts. The example identifiers and trade URL below are synthetic; replace them with an active item and the intended recipient before making a real purchase.

Request body

Example

curl -X POST https://merchant-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_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"
}

max_price is your consent ceiling, not a reserved amount. For a $20.00 ceiling and a $18.40 actual price, only $18.40 is debited; there is no $1.60 refund. balance_after is the balance after creation, or the current balance on an idempotent repeat. 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 after creation (or the existing purchase on a repeat); 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:

A failed existing purchase returns error together with purchase_id, custom_id, failure: { code, message }, trade_offer_id, and trade_offer_url. error.code remains an HTTP MERCHANT_* code; failure.code uses the shared purchase reasons. Unknown offer IDs are null. See the failed purchase response for compatibility and refund semantics.

Example

curl -X POST https://merchant-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_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 success body has the same shape as POST /buy-sync. An initial call returns the accepted attempt or the last in-flight attempt. Attempts have separate purchase_id values and share your custom_id; lookup by custom_id can return more than one purchase. Intermediate failures do not emit purchase.created, and a 202 does not guarantee that event. A concurrent repeat reports the latest existing attempt at that moment; the original call can still advance to another attempt. See idempotency.

When a repeated request reports a specific failed attempt, its 409 body includes that attempt’s purchase_id, shared failure, and known trade offer fields, as for /buy-sync. Retry-cycle exhaustion remains an ordinary HTTP error body; reconcile individual attempts through the purchase list and events.

Errors

Example

curl -X POST https://merchant-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

custom_id identifies your logical operation and is scoped to your merchant. Persist it before the first request. Keep the endpoint and request parameters unchanged on retries; never generate a fresh key just because the response was lost.

For /buy and /buy-sync, changing the item, recipient or trade URL, or lowering max_price below the saved price returns 409 MERCHANT_DUPLICATE_CUSTOM_ID. The response is not a saved copy of the first HTTP body: status can advance and balance_after on a repeat can reflect later balance activity.

For /buy-by-name, custom_id stays stable; purchase_id identifies one attempt. A repeat during the original cycle can return attempt A, while that cycle later creates attempt B with a different ID. Even a failed attempt observed by a concurrent repeat does not prove the original cycle has stopped. Do not create a new business order from that observation. Track the logical order by custom_id, keep the purchase IDs you receive, and reconcile all matching purchases.

Recover after an unknown result

1. Keep the saved custom_id, endpoint and body when a timeout or disconnect leaves the outcome unknown.
2. Repeat that same request to recover the existing purchase or latest by-name attempt.
3. If no purchase_id was received, query GET /api/v1/merchant/purchases?custom_id=YOUR_ID and follow next_cursor. An empty result while the POST is still running is not proof that no purchase will be created.
4. Track the returned purchases and webhooks; confirm refunds separately from failure status.

Full retry semantics: Errors → Idempotency.