# Create an order (/docs/api-reference/orders/create-order)

`POST /v1/orders`

Places one order of one to five items, of one or several product types, and pays it from the wallet.

Each item names its `productType`, the `publicId` of the offer from search or quote, a
`quantity` and, where the product needs them, product-specific `inputs` (required for hotels and
flights). An order has at most five items and a total quantity of at most five; an item with quantity
`n` becomes `n` separate order items, each with its own `items[].id`. Every item is
validated before anything is charged; a rejected item is reported at `items[i]` in
`details`, for example `11004` (`OFFER_EXPIRED_OR_INVALID`) for an unknown, expired or
other-product `publicId`, `11003` (`OFFER_UNAVAILABLE`) or `11002`
(`OFFER_PRICE_CHANGED`).
            
The optional `maxTotal` `{ amount, currency }` caps the whole order: the sum of every item's
price times its quantity, in the order currency. Its currency must be the order currency (otherwise
`400`, `10001`, `CURRENCY_MISMATCH` at `maxTotal.currency`). A higher total returns
`409` with code `11002` (`OFFER_PRICE_CHANGED`) at `maxTotal`, after every item is
priced and before anything is charged; a total equal to it is accepted.
            
The order total is charged to the partner's selected wallet. On success the order is
`processing` and its items start as `pending`; delivery continues after the response, so follow
it with `GET orders/{id}`, `GET orders/{orderId}/fulfillment/status` or the
`order.fulfillment.updated` webhook. If the charge fails, no order is created and the call returns
`402` with code `16000` (`PAYMENT_FAILED`); when the reason is known,
`details[0]` names `wallet` with reason `INSUFFICIENT_BALANCE` or `WALLET_BLOCKED`.
Top up or unblock the wallet and send the same request again with the same `Idempotency-Key`.
            
Requires an `Idempotency-Key` header (a UUID) per purchase. Repeating the same request with the
same key never charges twice: once the order is accepted it returns `200` with that order's current
state; while the first request is still running it returns `409` with code `12002`
(`IDEMPOTENCY_KEY_IN_PROGRESS`) and a `Retry-After` header, after which you send the same
request again; a different body with the same key returns `409` with code `12001`
(`IDEMPOTENCY_KEY_REQUEST_MISMATCH`). After a timeout or `5xx`, retry with the same key and
body rather than a new key. A `referenceId` already used by another order of the partner returns
`409` with code `10005` (`CONFLICT`). An eSIM top-up whose `inputs.iccid` is not one
of your eSIMs returns `404` with code `10004` (`NOT_FOUND`) 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`: `MixedOrderRequest`
- `text/json`: `MixedOrderRequest`
- `application/*+json`: `MixedOrderRequest`

## Responses

### 200

OK

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

### 400

Invalid partner request or model validation failure.

- `application/json`: `ErrorResponse`

### 401

Unauthorized

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

### 402

Payment Required

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

### 403

Forbidden

- `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`

### 500

Internal Server Error

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/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.