DEVELOPER REFERENCE · V1
Your next integration
starts here.
Browse products, place orders, and retrieve deliveries through a single customer API.
GET /catalog is public and shows standard prices and stock. Sign in to the shop, or use the authenticated API below, for customer discounts and orders.
01 / Authentication
Send your customer key in the X-API-Key header on every request. Get your key and prepaid USD balance from your account administrator. Keep keys on your server.
X-API-Key: rk_your_customer_key
02 / Place your first order
First call GET /v1/products to find the product ID and current customer price. Then create an order with a unique Idempotency-Key. Reuse the same key and exact body if your connection drops; this returns the existing order instead of charging twice.
POST /v1/orders
X-API-Key: rk_your_customer_key
Idempotency-Key: your-unique-order-123
Content-Type: application/json
{
"product_id": "product-uuid-from-the-catalog",
"quantity": 1,
"max_total": "5.00"
}The response contains your order id. Funds are reserved immediately. max_total is optional and protects you against price changes.
GET /v1/orders/your-order-id X-API-Key: rk_your_customer_key
Poll every 15 seconds. Once status is fulfilled, accounts contains objects with an id and credential. A failed order releases the reserved balance. A review order requires administrator reconciliation; do not create a new order to retry it.
03 / Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /v1/balance | Your available USD credit |
| GET | /v1/products | Catalog, prices, stock freshness |
| POST | /v1/orders | Purchase 1–50 accounts |
| GET | /v1/orders | Your orders; limit and offset pagination |
| GET | /v1/orders/{id} | Status and delivered credentials |
| GET | /v1/transactions | Your balance history; limit and offset pagination |
| GET | /v1/accounts/{id}/status | Supplier account status check |
| GET | /v1/accounts/{id}/warranty | Supplier warranty eligibility |
| POST | /v1/accounts/{id}/replacement | Queue a free replacement; requires Idempotency-Key |
04 / Responses & limits
USD amounts are decimal strings with six decimal places. Times are Unix seconds. Lists default to 25 items and allow up to 100. Only your own orders, transactions, and accounts are accessible.
States: queued, submitting, processing, fulfilled, failed, denied, and review. The catalog is a supplier snapshot; availability is confirmed at purchase time.
{"error":{"code":"INSUFFICIENT_BALANCE","message":"Please top up your balance"}}401 Invalid key or suspended customer · 402 Insufficient balance · 404 Not found · 409 Price, stock, or idempotency conflict · 422 Invalid input · 429 Rate limited · 503 Temporary unavailability.
The default limit is 120 requests/minute per customer, shared by all their keys. Supplier checks have a separate shared budget and may return SUPPLIER_BUSY. Honor Retry-After and retry with backoff.
Replacement eligibility and warranty duration are decided by the supplier. A denied replacement was refused by the supplier and costs no credit. Replacement requests return an order ID to poll; repeat requests for the same account return the existing replacement.