Purchases

Fetch and list merchant purchases. All require Authorization: Bearer mer_live_… (Authentication).

To create a purchase, see Buy.

Fetch a purchase

GET /api/v1/merchant/purchases/{purchaseId}

curl "https://api.tradeon.market/api/v1/merchant/purchases/1a2b3c4d-5e6f-7080-91a2-b3c4d5e6f708" \
  -H "Authorization: Bearer mer_live_…"

200 OK:

{
  "purchase_id": "1a2b3c4d-5e6f-7080-91a2-b3c4d5e6f708",
  "custom_id": "order-2026-05-05-0001",
  "status": "completed",
  "item": {
    "id": "8e42bb9c-2e11-4d40-9d51-6e5d2d4b2cf1",
    "market_hash_name": "AK-47 | Redline (Field-Tested)",
    "price": 18.40,
    "image_url": "https://cdn.tradeon.market/items/ak47-redline-ft.png",
    "exterior": "Field-Tested",
    "float": 0.2451,
    "delivery_type": "instant",
    "estimated_delivery_minutes": 2
  },
  "price": 18.40,
  "target_steam_id": "76561198000000000",
  "trade_offer_id": "9876543210",
  "trade_offer_url": "https://steamcommunity.com/tradeoffer/9876543210",
  "created_at": "2026-05-05T16:00:00.000Z",
  "completed_at": "2026-05-05T16:02:13.421Z",
  "failure": null
}

When the purchase has failed, failure is non-null:

"failure": {
  "code": "STEAM_DECLINED",
  "message": "buyer declined the trade offer",
  "refunded_amount": 18.40
}

Errors

HTTP	`code`	When
400	`MERCHANT_INVALID_STATUS`	`?status=` is not one of `created`, `processing`, `sent_to_steam`, `completed`, `failed` (`GET /purchases` only).
404	`MERCHANT_PURCHASE_NOT_FOUND`	Purchase does not exist or belongs to another merchant.

List purchases

GET /api/v1/merchant/purchases

Cursor-paginated.

Query parameters

Name	Type	Notes
`cursor`	string	Opaque, from previous `next_cursor`.
`limit`	int	1–200, default 50.
`status`	string	Filter — one of `created`, `processing`, `sent_to_steam`, `completed`, `failed`. See status values. Unknown values return `400 MERCHANT_INVALID_STATUS`.
`custom_id`	string	Exact match.
`target_steam_id`	string	Exact match.
`from` / `to`	ISO 8601	`created_at` window.

Example

curl "https://api.tradeon.market/api/v1/merchant/purchases?status=completed&limit=2" \
  -H "Authorization: Bearer mer_live_…"

{
  "purchases": [ /* PurchaseDetail objects */ ],
  "next_cursor": null
}

Status values

completed and failed are terminal; the rest are in-flight.

Status	Terminal	Meaning
`created`		Accepted, balance debited, awaiting worker pickup.
`processing`		Acquiring the item from upstream (incl. provider-top-up retries).
`sent_to_steam`		Trade offer dispatched on Steam, waiting for buyer to accept.
`completed`	✓	Buyer accepted. Item delivered.
`failed`	✓	Buyer-declined / cancelled / refunded. Inspect `failure.code` and `failure.refunded_amount`.

failure.refunded_amount is non-null when the failure was settled with an automatic refund. Prefer webhooks over polling: Event Catalogue.

Buy Balance