# Book hotels (/docs/api-reference/hotels/create-order)

`POST /v1/hotels/order`

Places and pays for hotel bookings of up to 5 searched or quoted rates.

Requires an `Idempotency-Key` header (a new UUID per purchase) and an API key with order-manage
permission. Repeating the same request with the same key returns the original order; while the first
request is still running the response is 409 / 12002 with `Retry-After`, after which you send the
same request again. The order is paid from your wallet balance and each booking
completes asynchronously: track it with `GET /orders/{id}` or the `order.fulfillment.updated`
webhook.
            
The body is `{ currency, referenceId, items }` with 1 to 5 items, each
`{ publicId, quantity, inputs }`. `publicId` is an offer's `publicId` from search, or the
newer one from quote, and `quantity` must be 1. `inputs` holds the holder and one
`roomGuests` entry per searched room (`roomIndex` 1 to N), whose guests must match the searched
occupancy and child ages, the optional `specialRequests`, and the optional price guard
`maxPrice` in the order currency. Unknown fields are rejected with 400.
            
The whole body is validated first: a body error gives 400 / 10001, also when it is in a later item. Once
the body is valid, each item is checked completely before the next, and an error names its item in
`details[].path`.
Before any money moves each rate is priced again in the order currency and capped: at
`inputs.maxPrice` when sent, else at the price shown with the `publicId`. Above the cap the order
returns 409 / 11002 at `items[i].inputs.maxPrice` or `items[i]` (quote again); at or below it
the rate is charged as priced, so a `maxPrice` above the shown price accepts a rise up to it. A rate
that cannot be booked now returns 409 / 11003, an offer priced in another currency than the order
400 / 11005, and an unknown, expired or another partner's `publicId` 400 / 11004, each at
`items[i]`. Offer and hotel-system failures return their hotel codes (21003, 21007–21010) without a
path. A wallet charge that fails 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. Nothing is created or charged when the order is refused.

## Parameters

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

## Request body

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

## Responses

### 200

OK

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

### 400

Invalid partner request or model validation failure.

- `application/json`: `ErrorResponse`

### 402

Payment Required

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