Partner API v1
Fetch plans at your wholesale prices, order an eSIM, and retrieve the installation details for your customer.
Getting started
This is the integration guide for developers connecting their store or booking system to eSIMara. The Partner API is currently available in eSIMara’s local development environment. Public API access is pending launch.
API address
$ESIMARA_BASE_URL is a shell variable that holds the common part of the API address. It is used in the examples so that all requests use the same address. The documentation is hosted at docs.esimara.com. For local development on the machine running eSIMara, the full catalogue URL is http://localhost:3211/api/partner/v1/products.
export ESIMARA_BASE_URL="http://localhost:3211/api/partner/v1"
Choose an API key
- Sandbox
- Use this key to test your integration. A test order returns sample installation details and places no supplier order or charge.
- Live
- Use this key for customer orders once eSIMara enables live access. A live order provisions a real eSIM and charges your partner account.
Sign in to the Partner Portal with your approved work email. In API access, create a sandbox key and save it in your server’s secret store as ESIMARA_API_KEY. Then run the catalogue request below. Both key types use the same endpoints and the Authorization header.
List products
GET /productscurl "$ESIMARA_BASE_URL/products?limit=50" \ -H "Authorization: Bearer $ESIMARA_API_KEY"
The response contains a products array and next_cursor. Each offer includes its id, name, product_group, tax_basis, currency, currency_digits and price_minor. For example, AUD 13.95 is 1395 minor units. Use the offer’s quoted currency and integer price when ordering.
The default page size is 50. Set limit to 1–100 and pass the returned cursor as after on the next request. Stop when the cursor is null. An empty first page means your channel has no available priced offers. Contact partner support to check publication and group access.
Create an order
POST /ordersOne request orders one eSIM. Send JSON with a unique business reference (1–100 letters, digits, periods, underscores or hyphens). Replace the illustrative product ID and price below with values from your catalogue.
curl "$ESIMARA_BASE_URL/orders" \
-H "Authorization: Bearer $ESIMARA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reference":"booking-1042","product_id":"10000000-0000-4000-8000-000000000001","price_minor":1395,"currency":"AUD"}'
Store the returned order id. A newly ready order returns HTTP 201. A pending order returns 202. Always inspect status, including on HTTP 200. If the connection drops, retry the identical request with the same reference. A new reference represents another purchase.
Retrieve an order
GET /orders/{id}curl "$ESIMARA_BASE_URL/orders/$ORDER_ID" \ -H "Authorization: Bearer $ESIMARA_API_KEY"
Use a key for the same partner and environment. The response includes the order ID, reference, product ID and name, currency, currency digits, amount in minor units, creation time, mode and status.
- processing · reconciling · awaiting_details
- Fulfilment is pending. GET reads the last saved state. Repeat the original POST with the same reference and payload to request a progress check.
- ready
- Read
installation. Depending on availability, it can includeiccid,lpa,qr_urlandios_install_url. Share installation details privately with the customer. Sandbox values are simulated. - failed
- The order did not complete. Use the reference when contacting support.
Errors and limits
Errors return JSON such as {"error":"price_changed"}. Limits are shared across a partner’s keys in each environment: 120 reads and 30 order submissions per minute.
- 400 · Invalid request
- Check the JSON fields, currency, integer price or pagination parameters.
- 401 / 403 · Access
- Check the bearer key, environment and ordering permission.
- 402 · Insufficient spending capacity
- Review your balance, reservations and credit limit in Billing.
- 404 · Unavailable
- Check the product or order ID and the environment of the key.
- 409 · Conflict
- For price_changed, reload the offer and confirm the revised price. For reference_conflict, retrieve the original order and check its terms before proceeding.
- 429 / 503 · Retry later
- Back off on rate limits or temporary service failures. For live_ordering_disabled, contact eSIMara before retrying. Preserve the original reference on retries.
Developer documentation