> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pageonetravel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Book API

> Create a booking using a quote reference.

## Endpoint

```http theme={null}
POST /api/book
```

## Authentication

* Required header: `api-key: <partner-api-key>`
* Required body field: `settings.access.code`

## Headers

| Header            | Required | Description               |
| ----------------- | -------- | ------------------------- |
| `Content-Type`    | Yes      | `application/json`        |
| `api-key`         | Yes      | Partner API key           |
| `connection-code` | Optional | Auto-filled from body     |
| `session-id`      | Optional | Auto-generated if missing |

## Request Body

### Top-level fields

| Field                 | Type   | Required | Notes                      |
| --------------------- | ------ | -------- | -------------------------- |
| `bookCriteria`        | object | Yes      | Booking input payload      |
| `settings`            | object | Yes      | Must include `access.code` |
| `distributionContext` | object | No       | Optional                   |

### `bookCriteria` fields

| Field                           | Type   | Required | Notes                                                            |
| ------------------------------- | ------ | -------- | ---------------------------------------------------------------- |
| `quoteId`                       | string | Yes      | From quote response `data.id`                                    |
| `accommodation.type`            | string | No       | Default `Hotel`                                                  |
| `accommodation.code`            | string | Yes      | Must match quoted payload                                        |
| `occupancies[]`                 | array  | No       | Optional override; if provided, validated against quote snapshot |
| `occupancies[].occupancyId`     | number | Yes\*    | Required when `occupancies` provided                             |
| `occupancies[].paxes[]`         | array  | Yes\*    | Required when `occupancies` provided                             |
| `occupancies[].paxes[].age`     | number | Yes      | Guest age                                                        |
| `occupancies[].paxes[].name`    | string | No       | Guest first name                                                 |
| `occupancies[].paxes[].surName` | string | No       | Guest last name                                                  |
| `market`                        | string | No       | Market code                                                      |
| `paymentType`                   | string | No       | Supported enum; practical flow uses `MerchantPay`                |
| `partnerReference`              | string | Yes      | Partner-side booking reference                                   |
| `holder.name`                   | string | Yes      | Booking holder first name                                        |
| `holder.surName`                | string | Yes      | Booking holder last name                                         |
| `checkIn`                       | string | Yes      | Must match quote                                                 |
| `checkOut`                      | string | Yes      | Must match quote                                                 |
| `language`                      | string | No       | Optional                                                         |
| `currency`                      | string | No       | Optional                                                         |
| `nationality`                   | string | No       | Optional                                                         |

## Example Request

```json theme={null}
{
  "bookCriteria": {
    "quoteId": "cb4af805-08aa-4ec4-9f90-a8b94e6d9d54",
    "accommodation": {
      "type": "Hotel",
      "code": "6475503709317edd78e1dbd9"
    },
    "occupancies": [
      {
        "occupancyId": 1,
        "paxes": [
          { "age": 30, "name": "John", "surName": "Smith" },
          { "age": 28, "name": "Jane", "surName": "Smith" }
        ]
      }
    ],
    "paymentType": "MerchantPay",
    "partnerReference": "partner-ref-10001",
    "holder": {
      "name": "John",
      "surName": "Smith"
    },
    "checkIn": "2026-03-01",
    "checkOut": "2026-03-03",
    "language": "EN",
    "currency": "USD",
    "nationality": "US"
  },
  "settings": {
    "access": { "code": 10001 }
  }
}
```

## Success Response

```json theme={null}
{
  "data": {
    "bookingReference": "BK_EXAMPLE_001",
    "partnerReference": "partner-ref-10001",
    "status": "success",
    "chargeTotal": 138.5,
    "hotelConfirmationNumber": "CNF_EXAMPLE_001",
    "requestId": "req_book_64f5..._1739260000000_62131",
    "responseTime": 241
  },
  "message": "success"
}
```

## Response Fields

| Field                          | Type   | Notes                                |
| ------------------------------ | ------ | ------------------------------------ |
| `data.bookingReference`        | string | System booking reference             |
| `data.partnerReference`        | string | Partner reference from request       |
| `data.status`                  | string | `success` on successful booking      |
| `data.chargeTotal`             | number | Charged total amount                 |
| `data.hotelConfirmationNumber` | string | Optional supplier/hotel confirmation |
| `data.requestId`               | string | Trace ID                             |
| `data.responseTime`            | number | Milliseconds                         |

## Validation Behavior

* `quoteId` must exist in quote cache and not be expired
* Accommodation and stay dates must match quote snapshot
* If occupancies are provided, adult/child counts and pax counts must match quote snapshot
* `settings.access.code` must belong to partner linked to API key
* On supplier booking failure, API returns `400 The booking was not successful.`

## Common Errors

* `400 optionId is required`
* `400 Quote reference expired or invalid. Please quote again.`
* `400 Accommodation code mismatch`
* `400 Stay dates mismatch`
* `400 occupancyId is required when providing occupancies`
* `400 Occupancy X not found in cached quote`
* `400 Missing rate snapshot for booking`
* `400 Missing supplier metadata for booking`
* `400 The booking was not successful.`
* `403 Invalid connection code.`
* `404 Accommodation not found`