Skip to main content
POST
Create an order
Orders one or more eSIMs. The 201 lists one topup_id per unit; each eSIM’s activation data then arrives on your webhook as esim.issued.

Retrying an order

external_order_id is your idempotency key. Sending an order again with the same external_order_id returns the original order rather than placing a new one, so when a request times out or answers 5xx or a provider 422, retry it as it was.
  • Keep the same external_order_id and products on a retry.
  • Use a new external_order_id only for a genuinely new order.
  • Another partner using the same value does not affect you: it is unique within your account only.

Errors

The field messages you can get:
  • external_order_id must be 1-64 characters of letters, digits, '-' or '_'
  • products must be a non-empty array
  • products[N] must be an object
  • products[N].qty must be a positive integer
  • products[N].option_id is not a known product

Authorizations

X-Esimmu-Access-Key
string
header
required

Your partner access key. Identifies you on every request.

X-Esimmu-Signature
string
header
required

Lowercase hex HMAC-SHA256 over the five-line string {METHOD}\n{REQUEST_PATH}\n{TIMESTAMP}\n{ACCESS_KEY}\n{BODY_SHA256}, keyed with your Base64-decoded secret key.

REQUEST_PATH includes the /api prefix and excludes the domain and any query string. BODY_SHA256 is the lowercase hex SHA-256 of the exact body bytes you send; for a request with no body, hash the empty string. The string always has five lines.

X-Esimmu-Timestamp
string
header
required

Unix seconds (UTC), within 5 minutes of our clock.

Body

application/json
external_order_id
string
required

Your own reference for the order, unique within your account. Sending it again returns the original order instead of placing a new one, so it is safe to retry with.

Pattern: ^[A-Za-z0-9_-]{1,64}$
products
object[]
required
Minimum array length: 1

Response

Order accepted. One entry in products per unit ordered.

external_order_id
string
required
products
object[]
required

One entry per unit ordered.

Last modified on November 16, 2026