Skip to main content
eSIM Story API lets you order eSIMs from your own systems over HTTP.

​
How an order works

Orders are asynchronous. You get an acknowledgement straight away, and the eSIM itself arrives later on your webhook.
  1. Sign the request. Every call carries three headers derived from your secret key. See Authentication.
  2. Create the order. POST /v1/api_partner/orders with your own order ID and the products you want.
  3. Read the 201. It returns one topup_id per unit ordered. The eSIM data is not in this response.
  4. Receive a webhook per unit. Once each eSIM is issued, we POST its activation data to your webhook URL. Failed deliveries are retried, so the same unit can arrive more than once.
  5. Verify the signature, then process. Match the delivery to your order with external_order_id, and to the unit with topup_id — which is also the key to deduplicate on.
To refund an eSIM later, see Request a refund.
There is no endpoint to poll for eSIM data. If you have not configured a webhook URL, you will never receive it.

​
Base URL

Production
Sandbox
Paths in these docs are relative to that base. POST /v1/api_partner/orders means https://api.esimstory.com/api/v1/api_partner/orders.

​
Credentials

Three values, issued per environment: Production credentials are in your partner dashboard. Sandbox credentials are issued separately — contact support to have a sandbox account set up. Sandbox and production do not share credentials. Sandbox orders use test data and cost nothing, and its webhooks are signed exactly as production ones are, so you can build and test signature verification there before going live.

​
Before you write any code

Two of these come from us and cannot be worked out from the docs, so collect them first rather than discovering them mid-integration.
1

Your product catalogue

The option_id values you order with come from List products, at your own price. We may also send you the catalogue as CSV files, such as with your price list — see The catalogue CSV.
2

A registered webhook URL

The eSIM never appears in an API response, and there is nothing to poll instead. Give support the URL before you place your first order.

​
Reading these docs with an AI assistant

The docs are published in machine-readable form, so you can point a coding agent at them rather than pasting pages:
An assistant working from the docs alone has no real option_id values, and will invent one if you let it. Have it call List products for them, or paste a few into the prompt.

Authentication

Sign your requests

List products

The catalogue, at your price

Create an order

The endpoint and its errors

Webhooks

Issued eSIMs and refund decisions

Request a refund

Ask for a refund on one eSIM
Last modified on November 2, 2026