# Order eSIMs (/docs/api-reference/esims/create-order)

`POST /v1/esims/order`

Places an order for new eSIMs or a top-up and returns the accepted order.

Takes the same body as quote and needs the `manage` order permission (403 / 10003 without it).
An `Idempotency-Key` header with a new UUID is required for every purchase: a retry with the same key and body
returns the order already accepted, 409 / 12002 with `Retry-After` while it is still being accepted, and a
changed body gives 409 / 12001.
A top-up is an offer from `search?iccid=` ordered with `inputs.iccid` and quantity 1; without
`inputs.iccid` the same offer is bought as a new eSIM. A new eSIM is instant unless `inputs.isInstant`
is false, which delivers an entitlement to provision later. Every price is recalculated: a current price above
`inputs.maxPrice` gives 409 / 11002 before anything is charged. A wallet charge that fails creates no
order and gives 402 / 16000, with `details[0]` naming `wallet` and `INSUFFICIENT_BALANCE` or
`WALLET_BLOCKED`; send the same request with the same key after a top-up. An unknown or foreign
`inputs.iccid` gives 404 / 10004 and charges nothing.

## Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |

## Request body

- `application/json`: `EsimOrderRequest`
- `text/json`: `EsimOrderRequest`
- `application/*+json`: `EsimOrderRequest`

## Responses

### 200

OK

- `text/plain`: `EsimOrder`
- `application/json`: `EsimOrder`
- `text/json`: `EsimOrder`

### 400

Invalid partner request or model validation failure.

- `application/json`: `ErrorResponse`

### 402

Payment Required

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`

### 404

Not Found

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`

### 409

The offer changed since it was quoted: its price rose (11002, for products that check the quoted price) or it is no longer available (11003). Or the idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; it was used for a different request (12001); or its history is ambiguous.

- `application/json`: `ErrorResponse`

### 429

Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.

- `application/json`: `ErrorResponse`

### 503

Idempotency state is temporarily unavailable; retry the same request and key.

- `application/json`: `ErrorResponse`

The full schemas are in the OpenAPI specification at /openapi.json.