Skip to main content
POST
Order eSIM
Required scope: PARTNER
Orders an eSIM for one of the account’s numbers and charges it to your payment method on file. The response returns the eSIM with status PROVISIONING. The eSIM is usually ready 5 to 15 minutes later, and Allo then sends you the partner.esim.ready webhook.

Request

  • phone_number is required. It must be one of the account’s numbers, created with number_preference.esim set to true (see Create account). Any other number fails with PARTNER_ESIM_NUMBER_NOT_FOUND or ESIM_NOT_ELIGIBLE.
  • tier is required: a code from Get eSIM offer, for example ESIM_20GB. An unknown code fails with INVALID_ESIM_TIER.
  • holder_id is optional: the Allo user the eSIM is registered to. Leave it out to make the account itself the holder.
  • identity is required: the business the line is registered to. corporate_name, postal_address, postal_code (5 digits) and city are required. first_name, last_name, company_name, siret, naf and email are optional. A missing required field fails with ESIM_IDENTITY_INCOMPLETE.

Billing

  • The setup fee and the first period of the tier are charged to your payment method, on the subscription you pay for the account, with your partner discount applied. Allo never charges your client.
  • A card that requires 3D Secure is refused with 402 ESIM_PAYMENT_FAILED, as on Create account. A missing or declined payment method fails the same way. Nothing is left pending: update your payment method in the partner portal, then retry.
  • If the subscription you pay for the account cannot take an eSIM right now, the request fails with ESIM_SUBSCRIPTION_CONFLICT. When the error is retryable: true, retry in a few minutes.

Retries

Send an Idempotency-Key header (8 to 100 letters, digits, - or _, for example a UUID) and reuse it when you retry the same order. Retrying with the same key does not charge you twice. A key in another format fails with INVALID_IDEMPOTENCY_KEY.

Errors specific to this number

Authorizations

Authorization
string
header
required

Headers

Idempotency-Key
string

Optional. 8 to 100 letters, digits, - or _, for example a UUID. Retrying with the same key does not charge you twice.

Pattern: ^[A-Za-z0-9_-]{8,100}$

Path Parameters

account_id
string
required

The account id returned by Create account (usr-*).

Body

application/json
phone_number
string
required

One of the account's numbers, created with number_preference.esim set to true.

Example:

"+33745805999"

tier
string
required

A tier code from Get eSIM offer.

Example:

"ESIM_20GB"

identity
object
required

The business the line is registered to.

holder_id
string | null

Optional. The Allo user the eSIM is registered to. Defaults to the account itself.

Example:

null

Response

eSIM ordered

data
object