eSIM Data Store API (1.0.0)

Purchase eSIM plans, manage eSIMs, monitor usage, and control your wallet balance.

Base URL: https://api.esimdatastore.com/api

Welcome to the eSIM Data Store API. This RESTful JSON API lets you browse eSIM plans, purchase eSIMs, monitor data usage, top up active eSIMs, and manage your prepaid wallet balance. The wholesale customer surface documented here is JSON and API-key authenticated. A few sibling surfaces on the same host behave differently and are noted where they appear: the public voucher-redemption and install-landing routes (/r/*, /install/*) are anonymous; admin routes require a bearer token; report endpoints can return text/csv or application/pdf when the caller passes ?format=csv or ?format=pdf on the query string (JSON is the default).

Authenticate every request by including your API key in the X-API-Key header. Each key is scoped to a single customer account — all resources you create and query are automatically isolated to your account.

X-API-Key: your-api-key-here

API keys are provided during onboarding. If you need a key or need to rotate an existing one, contact support.

Requests without a valid API key receive a 401 Unauthorized response. Keep your key secret and never expose it in client-side code.

Follow these steps to make your first eSIM purchase and monitor it.

1. Browse plans. Fetch the list of available eSIM plans with pricing and coverage details.

curl -X GET https://api.esimdatastore.com/api/plans \
  -H "X-API-Key: your-api-key"

2. Purchase a plan. Buy an eSIM by submitting an order with the desired planId. Include an Idempotency-Key header to prevent double charges.

curl -X POST https://api.esimdatastore.com/api/orders \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"planId": "plan-uuid-here"}'

3. Get your eSIM. List your eSIMs, then fetch a specific eSIM to get the esimQr value for device installation.

curl -X GET https://api.esimdatastore.com/api/esims \
  -H "X-API-Key: your-api-key"

4. Monitor usage. Check data consumption, activation time, and expiry for any eSIM.

curl -X GET https://api.esimdatastore.com/api/esims/{esim-id}/usage \
  -H "X-API-Key: your-api-key"

5. Top up. When data is running low, check available top-up plans and add more data.

# Check available top-ups
curl -X GET https://api.esimdatastore.com/api/esims/{esim-id}/topups/available \
  -H "X-API-Key: your-api-key"

# Apply a top-up
curl -X POST https://api.esimdatastore.com/api/esims/{esim-id}/topup \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001" \
  -d '{"planId": "topup-plan-uuid"}'

6. Check balance. View your prepaid wallet balance. Purchases are deducted automatically.

curl -X GET https://api.esimdatastore.com/api/wallets/balance \
  -H "X-API-Key: your-api-key"

To prevent duplicate charges on write operations, include an Idempotency-Key header with a unique value (UUID recommended). When the API sees the same key within a 24-hour retention window, it returns the original cached response instead of re-executing the request. This is the safe way to retry after a network timeout — see the Orders tag for the full list of idempotent endpoints and their per-endpoint semantics.

If a duplicate arrives while the original is still in flight, the API returns 409 Conflict. Reusing the same key with a different request body is undefined behaviour — always mint a fresh UUID per logical operation.

All API errors emit application/problem+json per RFC 7807. The envelope carries type, title, status, detail, and — for machine-driven callers — a code field naming the error family:

{
  "type": "https://esimdatastore.com/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Duplicate request in progress",
  "code": "CONFLICT"
}

The code values you should branch on: VALIDATION_ERROR (request shape or field rejection — 422), NOT_FOUND (unknown resource or one that belongs to another account — 404), CONFLICT (idempotency collision, state conflict, in-flight duplicate — 409), UPSTREAM_ERROR (eSIMfx call failed or timed out — 502), RATE_LIMITED (throttle exceeded — 429, always paired with a Retry-After header), UNAUTHORIZED (missing or invalid API key — 401), and INTERNAL_ERROR (uncategorized server failure — 500). Validation errors carry a per-field errors extension; circuit-open 503 and throttled 429 responses carry a retryAfterSeconds extension mirroring the header.

Requests are rate-limited per API key. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header (in seconds) indicating how long to wait before retrying. Typical ceilings are 30 requests/minute for cheap reads, 10/minute for writes and sensitive reads, and 5/minute for refunds — but do not hard-code these numbers; treat the Retry-After header as authoritative.

Implement exponential backoff on 429. Retrying inside the Retry-After window will not succeed and can compound the throttle.

Admin surface for managing per-customer plan pricing. Each customer has an independent rate-card in customer_plan_prices that determines the price returned by GET /plans and the amount debited on POST /orders. Prices are uploaded in bulk via CSV; the upload path also enforces the plan-level margin floor (rate must be greater than or equal to upstream cost) and auto-disables plans that go underwater for a given customer, emitting a NEGATIVE_MARGIN_PLAN critical event.

A customer must have a rate-card row for a plan before that plan is orderable or votable for a voucher batch — the pre-flight check in POST /admin/code-batches returns 422 INVALID_REFERENCE if a row is missing. Requires an admin bearer token.

Manage the eSIMs on your account. GET /esims lists inventory with status and creation time; GET /esims/:id returns the full record including the LPA esimQr string used for device installation and a live liveStatus block fetched from the upstream provider. GET /esims/:id/usage returns data consumption, activation time, and expiry — polled with a 60-second per-ICCID window to protect the upstream (window-hit returns 429 with Retry-After, never stale data).

Top-ups live under the same resource: GET /esims/:id/topups/available lists the top-up plans valid for a given eSIM, and POST /esims/:id/topup applies one against the ICCID (idempotent, wallet-charged). Sandbox eSIMs always report ACTIVE and return simulated usage.

Public, anonymous eSIM install surface. GET /install/:token resolves an Ed25519-signed JWT install token and returns the LPA activation string plus a data-URI QR image for one-tap device activation — no Authorization header, no API key, and no ICCID in the response. The token itself is the credential: anyone with the URL can fetch the payload while it is valid, so responses carry Cache-Control: no-store and are throttled per-IP (10/min) and per-token (30/min, SHA-256 hashed).

Install tokens are minted by admin-scoped origination flows (POST /origination/issue) and by anonymous voucher redemption. Malformed or unverifiable tokens return 422 INVALID_REFERENCE; a valid token whose eSIM row no longer exists returns 404 NOT_FOUND; expired eSIMs return 410 GONE; already-redeemed eSIMs return the metadata with blank lpaString and qrDataUri and status: "redeemed".

Purchase eSIM plans and retrieve order state. POST /orders charges your prepaid wallet, provisions an eSIM upstream, and returns an OrderResponse that tracks the full lifecycle — from PENDING through COMPLETED, REFUND_PENDING, REFUNDED, or one of the terminal failure states. Include an Idempotency-Key header on every write; the same key within 24 hours replays the cached response instead of double-charging.

Fetch a single order via GET /orders/:id or paginate the full list via GET /orders?limit=&cursor= (cursor-based, max 100 per page). Sandbox customers receive dummy eSIMs (ICCID prefix 89990) with no real upstream provisioning.

Browse the eSIM plan catalog. GET /plans returns the plans that are available to your account — plans that are neither disabled nor removed from upstream, and priced under your customer rate-card. Each PlanResponse carries the display metadata (name, coverage, duration, data allowance), the customer-facing price in USD, and the fixed provisioningFee charged on top of the plan price for NEW orders (top-ups always carry a "0.00" fee). The catalog is the source of planId values you pass to POST /orders and POST /esims/:id/topup.

The /r/:code surface lets anonymous holders resolve and redeem voucher codes without an API key. GET /r/:code returns the current redemption state (used by the public lander to render the redeem page); POST /r/:code performs the redemption. POST /r/:code for an eSIM voucher returns 201 with { kind: "esim", installToken, installUrl } on synchronous success, or 202 with { kind: "processing", pollAfterMs } when eSIMfx accepted the order but the LPA isn't yet available. On 202 the traveller-facing lander polls GET /r/:code every pollAfterMs ms until the state settles; a second POST while the code is PROVISIONING returns 409 CONFLICT pointing at GET /r/:code. Terminal REDEEM_FAILED (worker exhausted attempts or hit INVALID_REFERENCE) collapses to an opaque 410 GONE — the same shape as REVOKED / EXPIRED / REFUNDED — so the internal redeem_fail_reason never leaks to the anonymous caller. GET /r/:code/usage returns remaining-data for a redeemed code, polled with a 60-second per-ICCID window and always-200 with a discriminated status field.

Access is IP-bucket and per-code-hash throttled (GET /r/:code: 10/min/IP + 30/min/code; POST /r/:code: 5/min/IP + 5/min/code; GET /r/:code/usage: 5/min/IP + 15/min/code) — never API-key authenticated. The :code path parameter is length-capped at 32 characters; error responses do not echo the raw caller-supplied code, and throttled responses are emitted before the service is consulted so brute-force enumeration stays bounded.

Refunds are asynchronous. POST /orders/:id/refund returns 202 Accepted with a refundRequestedAt timestamp; the wallet credit and the REFUNDED status flip commit atomically only after upstream termination succeeds. Poll GET /orders/:id until status reaches REFUNDED (success) or REFUND_FAILED (60-day window exceeded, or admin-forced fail).

The credited amount equals the order's planPrice — that is, salePrice − provisioningFee. The $0.50 provisioning fee is retained on NEW orders because the upstream does not refund ESIM_CARD on termination; TOPUP refunds credit the full salePrice since their provisioningFee is "0.00". Sandbox refunds skip real upstream termination and commit inline.

Admin-only financial exports, scoped by calendar month. GET /reports/financial?month=YYYY-MM returns per-month revenue, profitability, and per-customer rollups — with optional sections filtering (revenue, profitability, customers) and format selection (json, csv, pdf). Every response carries net-of-upstream-refund fields (upstreamRefundedAmount, netUpstreamCost, netMargin) alongside the gross figures so you can reconcile true after-refund margin.

Authenticate with either the full ADMIN_TOKEN or the read-only ADMIN_REPORT_TOKEN as a bearer credential. Throttled at 5 reports/minute/IP because report generation pulls multi-month aggregates and PDF exports run pdf-lib synchronously.

Your prepaid wallet funds every purchase. GET /wallets/balance returns the current balance in USD as a decimal string (e.g. "150.00"). Purchases via POST /orders and POST /esims/:id/topup debit the wallet atomically at order creation; approved refunds credit it back once upstream termination completes. There is no self-serve top-up endpoint — wallet reloads are handled out of band during onboarding and via account manager.

Wholesale customers can register an HTTPS endpoint to receive real-time eSIM lifecycle events. PUT /webhooks/endpoint mints a fresh signing secret, POSTs a synchronous webhook.test event under a 10-second timeout, and persists the URL only on 2xx — the plaintext secret is returned in the response body exactly once, so capture it immediately. Companion routes let you rotate the secret, read the current configuration, and delete the endpoint (which clears URL, secret, and circuit state).

Delivered events are signed with HMAC-SHA256 in Stripe format (X-Esimds-Signature: t=<sec>,v1=<hex>). We enforce HTTPS, block private/loopback/metadata hosts against SSRF, and DNS-re-check the hostname at delivery time. Retryable failures (5xx, 408, 429, network errors) follow a 1m → 5m → 30m → 2h → 6h → 24h retry curve; other 4xx responses are treated as terminal on the first attempt. Sustained failure cools off the endpoint and eventually auto-disables it (a fresh PUT /webhooks/endpoint from you is the only way to re-enable). A self-contained reference verifier is shipped at docs/wholesale-webhooks-verifier.ts.