API integration

API quick start

After your account is approved, sales assigns pricing and enables API access. Create a key in the Partner Dashboard. Read-only keys cannot place orders. Purchasing must also be enabled on your account.

Use a server-side bearer key on every request. Keep the key out of browser code and URLs. Keys can be revoked in the Partner Dashboard.

Create an order

Send a UUID as Idempotency-Key. Reuse that same UUID after any timeout or connection failure. Send the price your customer confirmed and confirm the receiving device supports eSIM and is unlocked. Live price changes return 409 PRICE_CHANGED. This is a live API; accepted purchases use real wallet funds.

POST /api/partner/v1/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 83c77d9f-395f-4ff0-8ed6-c461bda46559

{"productId":"PRODUCT_ID_FROM_CATALOG","expectedPrice":"2.25","deviceConfirmed":true}

A 201 response contains orderId and esim; inspect esim.status and esim.failure. Poll the order every 10 seconds. Funds are held first and captured on verified delivery. A replay may return a failed order. An uncertain supplier outcome keeps the hold while the original order is reconciled. Installation material is private and appears only after verified delivery.

Amounts are decimal USD strings. Lists return items and nextCursor; continue until nextCursor is null. Limit: 120 requests per key per minute, and 10 purchase attempts per user per minute. Respect Retry-After on 429. Other common errors: 401 invalid key, 403 permission denied, 402 insufficient funds, 404 inaccessible order, 409 price or idempotency conflict, 503 service unavailable. Retrieve the original order before attempting another purchase.