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 prepaid credit first, then to your card 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, or one of its members’ numbers, created with number_preference.esim set to true (see Create account, Add number and Add member). 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. For a member’s number, send the member’s id from Add member or List members. This includes a number the member took over with phone_number.
  • 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 on the subscription you pay for the account, with your partner discount applied. Allo draws on your prepaid credit first, then charges your card on file for the rest. Allo never charges your client.
  • If your prepaid credit does not cover the order and you have no card on file, the request fails with 402 PARTNER_CREDIT_INSUFFICIENT. Top up your credit or add a card, then retry with a new Idempotency-Key.
  • A card that requires 3D Secure is refused with 402 ESIM_PAYMENT_FAILED. A declined card fails the same way. Nothing is left pending: update your card in the partner portal, then retry.
  • A number whose eSIM was revoked can get a new eSIM. The new order charges the setup fee again. If you order it right after the revocation, it stays PROVISIONING until the mobile network has confirmed the revocation.
  • 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 that can carry an eSIM: created, added or given to a member 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: the account itself by default, or the id of a member returned by Add member for the member's own number, including a number the member took over with phone_number.

Example:

null

Response

eSIM ordered

data
object