---
title: "Order eSIM"
method: POST
path: "/v2/api/partner/accounts/{account_id}/esims"
tags: ["Partner"]
---

# Order eSIM

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

## Request

- Base URL: `https://api.withallo.com`
- URL: `https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims`
- Auth: API key in header `Authorization`

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 draws on your prepaid credit first, then charges your card on file for the rest. The eSIM is returned with status `PROVISIONING` and is usually ready 5 to 15 minutes later: Allo then sends the `partner.esim.ready` webhook. A card that requires 3D Secure is refused with `ESIM_PAYMENT_FAILED`. Requires the `PARTNER` scope.

## Path parameters

- `account_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `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`.
  - `tier` string, required: A tier `code` from Get eSIM offer.
  - `holder_id` string, nullable: 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.
  - `identity` object, required: The business the line is registered to.
    - `corporate_name` string, required
    - `postal_address` string, required
    - `postal_code` string, required: 5 digits.
    - `city` string, required
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `company_name` string, nullable
    - `siret` string, nullable
    - `naf` string, nullable
    - `email` string, nullable

## Response `201`

eSIM ordered

- object
  - `data` object
    - `id` string: The eSIM id (`eso-*`).
    - `account_id` string: The account the eSIM was ordered for.
    - `partner_client_ref` string, nullable: Your own reference, set when the account was created.
    - `phone_number` string: The number the eSIM carries.
    - `tier` string: The tier code that was ordered.
    - `status` 'PROVISIONING' | 'ACTIVE' | 'FAILED': `PROVISIONING`: ordered, not ready yet. `ACTIVE`: ready, calls to the number ring the eSIM. `FAILED`: the order did not complete, see `failure_code`.
    - `failure_code` string, nullable: Why the order failed. Set only when `status` is `FAILED`.
    - `created_at` string, date-time: When the eSIM was ordered.

## Other responses

- `400`: Validation error: MISSING_FIELD, INVALID_ESIM_TIER, ESIM_IDENTITY_INCOMPLETE or INVALID_IDEMPOTENCY_KEY.
- `401`: Invalid or missing API key
- `402`: Billing error, nothing is left pending. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the order and your billing account has no card on file. ESIM_PAYMENT_FAILED: your card was declined or requires 3D Secure.
- `403`: The API key lacks the PARTNER scope.
- `404`: The account was not provisioned by your API key (PARTNER_ACCOUNT_NOT_FOUND), the number does not belong to the account (PARTNER_ESIM_NUMBER_NOT_FOUND), or `holder_id` cannot hold an eSIM for this number (PARTNER_ESIM_HOLDER_NOT_FOUND).
- `409`: The number cannot carry an eSIM (ESIM_NOT_ELIGIBLE), already has one (ESIM_ALREADY_EXISTS), has an order in progress (ESIM_ORDER_IN_PROGRESS) or one handled by Allo support (ESIM_ORDER_NEEDS_SUPPORT), or the subscription you pay for the account cannot take an eSIM right now (ESIM_SUBSCRIPTION_CONFLICT).
- `429`: Rate limit exceeded
- `500`: eSIMs cannot be ordered for this account right now (ESIM_UNAVAILABLE).

## Changes

- **2026-11-03** `46c77103dd14`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withallo/apis/allo-api/changes/v2/api/partner/accounts/:account_id/esims/post.md)

---

[API](https://skmtc.dev/withallo/apis/allo-api.md) - [All operations](https://skmtc.dev/withallo/apis/allo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withallo/apis/allo-api/revisions/46c77103dd14?raw)