# Order eSIM

> Orders an eSIM for one of the account's numbers. The setup fee and the first period of the tier are charged on the subscription you pay for the account: Allo…

`POST /v2/api/partner/accounts/{account_id}/esims`

<Note>
**Required scope:** `PARTNER`
</Note>

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`](/docs/webhooks/event-catalog#partneresimready) 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](/docs/partner/create-account), [Add number](/docs/white-label/add-number) and [Add member](/docs/white-label/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](/docs/white-label/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](/docs/white-label/add-member) or [List members](/docs/white-label/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](/docs/partner/get-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](/help/support/partner-portal), then retry.
- A number whose eSIM was [revoked](/docs/white-label/revoke-esim) 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

| Code | What it means |
|------|---------------|
| `ESIM_ALREADY_EXISTS` | The number already has an eSIM that is not revoked. Read it with [Get eSIM](/docs/white-label/get-esim), or [revoke it](/docs/white-label/revoke-esim) to order a new one. |
| `ESIM_ORDER_IN_PROGRESS` | An order for this number is still provisioning. Wait for `partner.esim.ready` or `partner.esim.failed`. |
| `ESIM_ORDER_NEEDS_SUPPORT` | A previous order was charged but did not complete, and Allo support is handling it. Write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co) before ordering again. |
| `PARTNER_ESIM_HOLDER_NOT_FOUND` | `holder_id` cannot hold an eSIM for this number. Leave it out to use the account. |
