For resellers & developers
The eSIM API for resellers, agencies & apps
Sell prepaid travel eSIMs for 190+ destinations under your own brand. A REST API with instant delivery, live usage per ICCID, sandbox keys and wallet billing.
What you can do with the API
Full plan catalog
Fetch every travel plan with your own B2B pricing, coverage and validity.
Instant order delivery
Place an order and receive the QR code / LPA activation string in seconds.
Live usage per ICCID
Check line status, activation date, data used and expiry for any eSIM you sold.
Sandbox environment
Build and test with mega_test_ keys — no wallet or real eSIM is consumed.
Wallet billing
Prepaid wallet, no per-call fees. Top up by card (Stripe) or bank (Wise).
Webhooks
Get notified on order events so you can automate your own fulfilment.
Partner API v1 documentation
Public REST API reference. Create a partner account to get your live and sandbox API keys, then use the examples below.
Base URL — browser
https://megaesim.us/api/v1Manual tests or calls from an authenticated browser session.
Base URL — server
https://api.megaesim.us/api/v1Recommended for backends (Render, Node, Python) — bypasses Cloudflare bot challenges.
Authentication: Authorization: Bearer mega_live_…
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /me | Verify the key and return account info |
| GET | /plans | Plan catalog (B2B pricing per account) |
| GET | /plans/{id} | Plan details |
| GET | /wallet | Wallet balance + recent transactions |
| GET | /orders | Order list (?limit=25, max 100) |
| POST | /orders | Place an order (debits wallet) |
| GET | /orders/{id} | Order status |
| GET | /orders/{id}/esim | eSIM data after delivery (QR, LPA, ICCID) |
| GET | /esims/{iccid}/usage | Live usage per ICCID (activation, data, expiry) |
Verify key — GET /me▾
Response 200: ok, accountEmail, apiKeyName, apiKeyId.
Request
GET https://megaesim.us/api/v1/me
Authorization: Bearer mega_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCatalog — GET /plans▾
Returns plans[]: id, name, nameEn, dataDescription, coverage, priceEuro, priceCents, validityDays, carrier, hasInstantDelivery, available, outOfStock.
Request
GET https://megaesim.us/api/v1/plans
Authorization: Bearer mega_live_…Wallet — GET /wallet▾
Returns balanceCents, currency, and transactions[]. There is no top-up endpoint in the API — fund the wallet in the portal: card (Stripe, with fee) or Wise (any amount from €30, no fee, credit 1:1).
Request
GET https://megaesim.us/api/v1/wallet
Authorization: Bearer mega_live_…Place order — POST /orders▾
Response: orderId, amountCents, fulfillmentStatus, autoDelivered, autoRefunded, manualPending, emailSent, esimId (if auto-delivered).
Poll status: GET /orders/{id} — same order object as in the list. Orange ES: LPA may take a few minutes — poll until delivered, then GET /orders/{id}/esim.
In GET /plans, Orange ES plans include supportsActivationScheduling: true.
| Field | Required | Description |
|---|---|---|
| planId | yes | Plan ID from /plans |
| deliveryEmail | no | End-customer email; omit = your account |
| customerNote | no | Internal note (max 500 chars) |
| idempotencyKey | recommended | Same key → same order |
| activation | no | Orange ES only (7984–7986): startDate (YYYY-MM-DD, Europe/Bucharest) + durationMonths (1|2|3). Debit = priceCents × durationMonths. Default: today + 1 month. |
Request
POST https://megaesim.us/api/v1/orders
Authorization: Bearer mega_live_…
Content-Type: application/json
{
"planId": 7985,
"deliveryEmail": "[email protected]",
"customerNote": "Internal ref #12345",
"idempotencyKey": "your-unique-key-2026-001",
"activation": {
"startDate": "2026-10-05",
"durationMonths": 2
}
}Poll eSIM — GET /orders/{id}/esim▾
After delivery: esim with iccid, activationCode, qrCodeData, smdpAddress, deliveredAt.
If not ready yet: 404 with code esim_not_ready.
Request
GET https://megaesim.us/api/v1/orders/123456/esim
Authorization: Bearer mega_live_…Live usage — GET /esims/{iccid}/usage▾
Look up usage and line status using the ICCID returned by /orders/{id}/esim.
200 response → usage object: iccid, supported, status (active | inactive | paused | expired | unknown), dataPlanStatus, dataUsedMb, activatedAt, orderedAt, expiresAt, expiryKind (data_ends | install_by | after_activation), planValidityDays, dailyResetAt, refreshedAt.
Data is cached ~3 minutes per eSIM. Add ?refresh=1 for a live read (use sparingly).
Usage fields are available only for eSIMs on networks that report consumption; otherwise supported:false and usage fields are null. Remaining data is not exposed — only dataUsedMb (total).
Unknown ICCID on your account → 404 esim_not_found. Usage provider temporarily down → 503 usage_upstream_unavailable.
Request
GET https://megaesim.us/api/v1/esims/8939104610004735215/usage
Authorization: Bearer mega_live_…Webhooks — events to your URL▾
Register an HTTPS URL under Developers → Webhooks. We POST JSON for order.placed, order.delivered, order.refunded, wallet.topup.
Header: x-megaesim-signature = t=<unix>,v1=<hmac-sha256(secret, timestamp.body)>.
The payload id uniquely identifies the event. If your server is down, we resend the SAME id (1 min, 5 min, 30 min, 2 h) — we never create a new order or debit the wallet again.
Always send idempotencyKey on POST /orders so your own retries do not place two orders.
Common errors
- 401 — Invalid key, revoked key, or API access disabled
- 402 ·
insufficient_balance— Insufficient wallet balance - 404 ·
plan_not_found— Plan not found - 404 ·
esim_not_ready— eSIM not delivered yet - 404 ·
esim_not_found— No eSIM with that ICCID on your account - 409 ·
out_of_stock— Plan unavailable - 429 — Rate limit exceeded (see below)
- 503 ·
usage_upstream_unavailable— Usage provider temporarily unavailable
Rate limits (per API key)
Reads (GET): 120 / minute · Orders (POST /orders): 30 / minute. When exceeded: HTTP 429 + retryAfterSec.
Security
- Keep the key server-side only — never expose it in a public frontend.
- Use idempotencyKey on every order (retry-safe).
- Revoke compromised keys immediately in the section above.
- Responses do not expose internal provisioning details.
Recommended flow
- GET /plans — show the catalog with your B2B prices.
- GET /wallet — check balance before ordering.
- POST /orders with idempotencyKey — place the order.
- If autoDelivered: false, poll GET /orders/{id} until fulfillmentStatus = delivered.
- GET /orders/{id}/esim — fetch QR / LPA / ICCID for the customer.
- GET /esims/{iccid}/usage — check line usage, activation and expiry anytime.
Support: Technical or commercial questions: [email protected]
Ready to integrate?
Request partner access — after approval you activate sandbox and live API keys.
Technical or commercial questions: [email protected]
