Purchase Status

GET /api/v1/merchant/purchase/status

Retrieves the current status of a purchase. Look up by internal id or your merchant_tx_id.

Request

Headers

Header	Required	Description
X-Api-Key	✅	Your merchant API key
Accept	—	application/json

Query Parameters

Parameter	Type	Required	Description
id	integer	✅*	Purchase ID
merchant_tx_id	string	✅*	Your transaction ID

* At least one of id or merchant_tx_id is required.

Response

{
  "success": true,
  "message": "Purchase status fetched successfully",
  "data": {
    "id": 178,
    "merchant_tx_id": "order-12345",
    "status": "completed",
    "steam_id": "76561198338314767",
    "steam_name": "PlayerOne",
    "steam_avatar_url": "https://avatars.steamstatic.com/...",
    "amount": 45.99,
    "trade_offer_id": "6912345678",
    "date": "2026-03-24T10:30:00Z",
    "item": {
      "id": "38029384123",
      "name": "AK-47 | Redline (Field-Tested)",
      "price": 45.99,
      "image_url": "https://steamcommunity-a.akamaihd.net/economy/image/class/730/..."
    }
  }
}

Response Fields

Field	Type	Description
id	integer	Purchase ID
merchant_tx_id	string	Your transaction ID (only present if provided at creation)
status	string	Current purchase status
fail_reason	string | null	Failure reason (present when status is failed, canceled or reverted, see Fail Reasons)
steam_id	string	User's Steam ID (64-bit, as string)
steam_name	string	User's Steam display name (only present if available)
steam_avatar_url	string	User's Steam avatar URL (only present if available)
amount	number	Purchase amount (USD)
trade_offer_id	string	Steam trade offer ID (only present if available)
hold_end_date	string	When the hold ends (ISO 8601). Set once the purchase enters hold and kept on later statuses
date	string	Purchase creation timestamp (ISO 8601)
item	object	Purchased item details (only present if available)
item.id	string	Catalogue item ID (the id you bought by), not a Steam asset ID. See Available Items
item.name	string	Item market name
item.price	number	Item price (USD)
item.image_url	string	Steam CDN image URL

INFO

Optional fields (merchant_tx_id, fail_reason, steam_name, steam_avatar_url, trade_offer_id, hold_end_date, item) are omitted from the response when not available — they will not appear as null.

Examples

By merchant_tx_id

curl "https://api.skinslink.com/api/v1/merchant/purchase/status?merchant_tx_id=order-12345" \
  -H "X-Api-Key: your-api-key" \
  -H "Accept: application/json"

By internal ID

curl "https://api.skinslink.com/api/v1/merchant/purchase/status?id=178" \
  -H "X-Api-Key: your-api-key" \
  -H "Accept: application/json"

Purchase Statuses

Status	Description	Final?
new	Purchase created, not yet processed	No
pending	Processing, awaiting trade offer creation	No
active	Trade offer sent, waiting for user to accept	No
hold	Item delivered and under Steam trade protection until hold_end_date. See Hold	No
completed	Purchase successful, item delivered ✅	Yes
failed	Purchase failed (see fail_reason) ❌	Yes
canceled	Purchase canceled	Yes
reverted	Previously held purchase was reversed	Yes

TIP

For real-time updates, use Webhooks instead of polling.

Hold

• CS2 — every delivered item is under Steam's 7-day trade protection, during which the trade can still be reversed. The purchase stays in hold until hold_end_date, then moves to completed within about a minute. If the item turns out not to be protected, the purchase completes right away without a hold.
• Rust — may enter hold for up to 1 hour before completing.
• Dota 2, TF2 — usually complete without a hold.

A purchase reversed during the hold ends as reverted, and its amount returns to your balance.

Fail Reasons

When status is failed, canceled or reverted, fail_reason explains why. In each of these cases the full purchase amount returns to your available balance.

Value	Status	Description
canceled_by_user	canceled	The user declined the trade offer
buyer_too_slow	canceled, failed	The user did not accept the trade offer in time
skinslink_too_slow	canceled, failed	The item was not sent in time
timeout_error	canceled, failed	The trade timed out before completing
canceled_by_skinslink	canceled	Canceled by Skinslink
trade_url_error	failed, canceled	The trade could not be sent to the user's trade link (invalid or changed link, or the account cannot trade)
user_reverted	reverted	The user reversed the trade during the hold
skinslink_reverted	reverted	The trade was reversed by Skinslink during the hold

Purchases rejected at creation (insufficient_balance, price_changed, item_not_available, …) are listed in Create Purchase. Other values may appear — treat any unknown fail_reason as a generic failure.

Errors

Status	Message	Cause
400	validation error	Neither id nor merchant_tx_id provided
401	missing authorization header	X-Api-Key header not provided
401	invalid API key	API key not found or inactive
403	merchant account is disabled	Merchant account deactivated
403	IP not whitelisted: <ip>	Request IP not in whitelist
404	not found error	No purchase matches the given ID