eSIM Reseller API: A Practical Integration Guide for Developers

Short answer: the eSIM Signal reseller API is a JSON REST API at https://esimsignal.com/api/v1. You authenticate with a Bearer API key, read the catalogue, place an order with a package_id, and get the ICCID, activation code, QR code URL and install page URL back in the response. Signed webhooks tell your system when an order completes and when an eSIM activates or expires.

The whole flow in five calls

1. Check your key — GET /ping confirms the key works and GET /balance shows your prepaid balance.
2. Browse destinations — GET /countries, GET /regions or GET /destinations. Every destination has an id, such as IT or EUROPE-USA.
3. List packages — GET /packages?region=IT returns every plan for that destination at your partner price.
4. Place an order — POST /orders with a package_id such as IT_5GB_30D_FIXED and an Idempotency-Key header.
5. Deliver — the response carries the ICCID, the activation code, qr_code_url and install_page_url for your customer.

API keys, scopes and test keys

Create API keys in the Business Panel and send one with every request as Authorization: Bearer <key>.

• Shown once. We store only a hash of each key, so copy it when you create it.
• Scopes. A key can be limited to catalogue, orders, esims and refunds. Give your website a catalogue-only key and keep the ordering key on your server.
• IP allow-list. A key can be restricted to your server's addresses.
• Test keys can read the catalogue and your account but cannot place orders — ideal while you build, because every live order is a real, paid eSIM.
• Roll or revoke a key at any time if it leaks.

Readable, stable package IDs

Package IDs describe the product: IT_5GB_30D_FIXED is 5 GB for 30 days in Italy. The ID names the product, not a network, so it stays valid when the network behind the plan changes. Store it in your catalogue and order with it directly — no mapping table required.

Orders that never double-charge

Mobile connections drop and requests time out. Send a unique Idempotency-Key with every order: if you retry with the same key, you receive the original order instead of a second eSIM. Reusing a key for a different package is refused, so a bug cannot quietly turn into the wrong order.

Attach your own customer_ref — a booking number or a user ID — to any order, then filter GET /orders and GET /esims by it later.

Webhooks

Register an HTTPS endpoint in the Business Panel to receive these events:

• order.completed — the eSIM is ready to deliver.
• order.failed — the order could not be completed.
• order.refunded — a refund was credited to your balance.
• esim.activated — your customer's eSIM connected for the first time.
• esim.expired — the plan has ended.

Every delivery is signed with HMAC-SHA256 in the X-ESIMSIGNAL-Signature header, so you can check it came from us. The panel keeps a delivery log where you can send a test event and resend any delivery.

Top-ups and refunds

• Top-ups: GET /esims/{iccid}/topups lists the packages that can be added to an existing eSIM, and POST /esims/{iccid}/topup adds one. Your customer keeps the same eSIM, with no second install.
• Refunds: an eSIM that was never installed can be refunded within your refund window with POST /orders/{id}/refund, and the amount returns to your balance.

Reliability tips

• Treat 202 as "in progress". Now and then a network needs a moment to issue an eSIM. A 202 means the order is accepted and paid, and order.completed follows.
• Branch on the error code, not the message. Errors come back as a stable machine-readable code, such as package_not_found or insufficient_funds.
• Refresh your catalogue regularly. Prices and plans follow the live catalogue.
• Watch your balance. Poll GET /balance or switch on low-balance alerts so orders never fail for lack of funds.

Documentation and help

The full API reference — every endpoint with a request and response example — is available to partners and can be downloaded as a PDF. During integration our technical team reviews your flow, tests orders with you and helps you go live safely. Not ready to code? You can also start selling from the Business Panel with no integration at all.

Apply for API access

Frequently asked questions

Is there an API for reselling eSIMs?

Yes. eSIM Signal offers a JSON REST API for resellers at https://esimsignal.com/api/v1, with catalogue, order, eSIM, top-up and refund endpoints and signed webhooks.

How do I authenticate with the eSIM Signal API?

Send your API key as a Bearer token in the Authorization header. Keys are created, scoped, rolled and revoked in the Business Panel.

How fast is eSIM delivery through the API?

Most orders return the activation code, QR code URL and install link in the same response. If a network needs a moment, the API answers 202 and a webhook follows when the eSIM is ready.

Can I test the eSIM API without being charged?

Yes. Test keys can read the catalogue and your account without placing orders. Every order made with a live key is a real, paid eSIM.

How do I avoid duplicate eSIM orders?

Send an Idempotency-Key header with every order. A retry with the same key returns the original order instead of creating a new one.