# Create your orders

**Learn how to create an order using the /orders/preview and /orders/create endpoints**

To complete an order, call the following endpoints in sequence:

|  Endpoint  |  Use it to... |
|  --- | --- |
| [/orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview)
 | Validate order details before booking:
✓ Confirm and validate guest allocation (prevents pricing errors) - It may return an `occupancy_mismatch` when the selected product cannot accommodate all guests.
✓ Verify the final price breakdown.
✓ Retrieve the `order_token` required by orders/create.
✓ Review available [payment timings](/demand/docs/payments/payments-timings), [methods](/demand/docs/payments/payments-methods) and [schedules](/demand/docs/payments/payments-timings#payment-schedules).
 |
| [/orders/create](/demand/docs/open-api/demand-api/orders/orders/create) | * Confirm the booking and process payment using the `order_token`.
  * This token encapsulates all order information — there is no need to rebuild the order.

 |


## Order creation process

Once the traveller has selected their desired products, follow these steps to create the booking.

## Step 1 - Call the /orders/preview

→ Use the [/orders/preview endpoint](#orderspreview) to validate the order details before proceeding.

Build the request using the product and accommodation data returned in the previous step of your integration flow.

| Integration type: | Retrieve data from |
|  --- | --- |
| Search and book | [/accommodations/search endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/search) |
| Search, look and book | [/accommodations/availability endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) |


### Define the request

Your [/orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) request must include:

| Required / Optional: | Field and value to use |
|  --- | --- |
| Required | `booker.platform` and `booker.country` — Use the values provided by the traveller in the previous step of the integration. |
| Required | `currency` — Use the currency value returned from the preceding response. |
| Required | `accommodation` — Use these values from the preceding response for the products selected by the traveller:- `id`
- `checkin` / `checkout`
- `products[].id`
- `products[].allocation`

 |
| Optional | `booker.travel_purpose` and `booker.user_groups` — Include if returned in the preceding response; otherwise, can be omitted. |


Example:


```json
{
  "booker": {
    "country": "nl",
    "platform": "mobile",
    "travel_purpose": "leisure",
    "user_groups": [
      "authenticated"
    ]
  },
  "currency": "EUR",
  "accommodation": {
    "id": 6745031,
    "checkin": "2026-03-10",
    "checkout": "2026-03-15",
    "products": [
      {
        "id": "674503106_275710478_0_2_0",
        "allocation": {
          "number_of_adults": 1,
          "children": [
            8
          ]
        }
      },
      {
        "id": "674503113_275710486_0_1_0",
        "allocation": {
          "number_of_adults": 1,
          "children": []
        }
      }
    ]
  }
}
```

#### Guest allocation

For multi-room bookings, specify guest distribution using `accommodation.products.allocation`.

Each product must define the number of guests assigned to that room.

Example - Booking two identical rooms, with one adult and one child allocated to each:


```json
{
  "products": [
    {
      "id": "1050736002_377311511_0_2_0",
      "allocation": {
        "number_of_adults": 1,
        "children": [2]
      }
    },
    {
      "id": "1050736002_377311511_0_2_0",
      "allocation": {
        "number_of_adults": 1,
        "children": [5]
      }
    }
  ]
}
```

Allocation data depends on your integration type:

| Integration type | Guest allocation source |
|  --- | --- |
| Search and book | Guest allocation is already included in the `products` from the [/accommodations/search endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/search) response. |
| Search, look and book flow | Guest allocation is included in `recommendation.products` from the [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) response. |


Example with `recommendation.products`:


```json
{
  "recommendation": {
    "products": [
      {
        "id": "1050736003_377312697_1_2_0",
        "allocation": {
          "number_of_adults": 1,
          "children": []
        }
      },
      {
        "id": "1050736003_377312697_1_2_0",
        "allocation": {
          "number_of_adults": 1,
          "children": []
        }
      }
    ]
  }
}
```

For non-recommended products, check `products.maximum_occupancy` from the [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) response and assign guests manually. See the [Occupancy guide](/demand/docs/accommodations/child-policies#occupancy)

### Orders/preview response

A successful response from the [/orders/preview endpoint](/demand/docs/open-api/demand-api/orders/orders/preview) includes:

| 
| **Accommodation-level data**
 | * `id`
* `currency`
* `general_policies.payment` - Supported [payment timings](/demand/docs/payments/payments-timings) and [methods](/demand/docs/payments/payments-methods).

If selected products support different payment options, the preview response returns only the **payment methods and timings supported by all selected products**.
 |
| **Product-level data** | * `id`
* `policies` - [cancellation](/demand/docs/orders-api/cancellation-policies) conditions and meal plans.
* `price` - Final price for product (See [Accommodation pricing guide](/demand/docs/accommodations/prices-accommodations) for details and examples)
* `room` - Room identifier returned by the API.
* `third_party_inventory` - Indicates if the rate is provided by a third-party partner (See [TPI rates guide](/demand/docs/accommodations/tpi/about-tpi)).
* `occupancy_mismatch` - Preview warning returned when the requested guest allocation exceeds the product capacity (See the [Occupancy and allocation guide](/demand/docs/accommodations/occupancy-allocation) for details).

 |
| **Order token** | `order_token` - Encapsulates the order details required by [/orders/create](/demand/docs/open-api/demand-api/orders/orders/create) request. |


The `order_token` **expires after 15 minutes**.

## Step 2 - Display the order preview page

Show a preview page so travellers can:

* Review booking details.
* Choose a payment method and timing.
* Provide guest and arrival information.


Example:

![order-preview](/assets/order-preview.b039e948303fa75f48a32649c70b3e97dd66d2ceff1ab765a4a424c9243a8184.5e2a7131.png)

In case of occupancy mismatch, inform your travellers so they can change guest allocation. (See the [Occupancy and allocation guide](/demand/docs/accommodations/occupancy-allocation) for details)

## Step 3 - Call the /orders/create endpoint

→ Once the traveller confirms, call [/orders/create](/demand/docs/open-api/demand-api/orders/orders/create), include the `order_token` from the orders/preview response, and all required fields.

The /orders/create request requires the following fields:

### Fields

#### Accommodation

| Field | Required | Notes / Details |
|  --- | --- | --- |
| **accommodation** | Optional | Top-level accommodation object |
| `accommodation.label` | Optional | A free-text label used for identification, campaign attribution or reporting. See [Labels for attribution guide](/demand/docs/orders-api/labels-attributions) for details. |
| `accommodation.products` | Optional | Array of products for this order |
| `accommodation.products.id` | Yes | Must match product IDs from `/orders/preview` |
| `accommodation.products.bed_configuration` | Optional | Optional bed configuration. Identifier for preferred bed setup returned from accommodations/details response. |
| `accommodation.products.guests` | Yes | Array of guest objects, each with:- email (required)- name (required) |
| `accommodation.remarks` | Optional | Traveller’s additional requests. |
| `accommodation.remarks.estimated_arrival_time.hour` | Conditional | Required if estimated arrival time is provided; allowed 0–23 |
| `accommodation.remarks.estimated_arrival_time.next_day` | Optional | Boolean, default `false` |
| `accommodation.remarks.special_requests  ` | Optional | Optional text (e.g. “Extra cot needed”) cannot be guaranteed. |


`accommodation.products.id ` in /orders/create must exactly match /orders/preview. This is a key validation step.

#### Booker fields

| Field | Required | Notes / Details |
|  --- | --- | --- |
| **booker** | Yes | Top-level booker object. |
| `address ` | Conditional | Required **if** `booker_address_required=true` from `/accommodations/details`. If used, all subfields (address_line, city, country, and post_code) are mandatory. |
| `company` | Optional | Booker's company name. For B2B or invoicing purposes. |
| `email` | Yes | Required |
| `language` | Optional | e.g., `en-us`, `nl` |
| `name` | Yes | Includes `first_name` and `last_name` |
| `telephone` | Yes | Required |


#### Payment

| Field | Required | Notes / Details |
|  --- | --- | --- |
| **payment** | Yes | Top-level payment object. |
| `payment.method` | Yes | One of `airplus`, `card`, `wallet` |
| `payment.timing ` | Yes | One of `pay_at_the_property`, `pay_online_now`, `pay_online_later` |
| `payment.card` | Conditional | Required if `method=card`; must include:- cardholder- cvc- expiry_date- number. |
| `payment.airplus ` | Conditional | Required if `method=airplus`; must include `number` and optional `dbi` info. |
| `payment.business_information` | Conditional | Required for some authorisation forms (e.g., virtual credit card) |
| `payment.include_receipt` | Optional | Boolean, determines if `receipt_url` is returned in response. Is set to "false" by default. Set to "true" if you wish to generate a payment receipt. |


See the [Payments section](/demand/docs/payments/overview) for best practices and use cases

##### Receipt generation

| Payment timing | Receipt behaviour |
|  --- | --- |
| `pay_online_now` | Receipt generated immediately via /orders/create. |
| `pay_online_later` | Retrieve a credit slip from [orders/details/accommodations endpoint](/demand/docs/open-api/demand-api/orders/orders/details/accommodations) once payment is due (e.g. 3 days before arrival). |


#### Order token

* `order_token` -  Token from the [/orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) response.
Expires after 15 minutes. Repeat /orders/preview if expired.


### Best practices for optional fields

Only provide optional fields if:

* They are relevant to your integration.
* Your business logic requires them.
* They’re explicitly needed for a specific endpoint or booking context.


This keeps requests lightweight and easier to maintain.

### Example - order/ create request

This example includes optional fields: products `bed_configuration`, `remarks` and receipt generation:


```json
{
  "accommodation": {
    "products": [
      {
        "id": "333",
        "bed_configuration": "123456",
        "guests": [
          {
            "email": "test.name@booking.com",
            "name": "Test Name"
          }
        ]
      }
    ],
    "remarks": {
      "estimated_arrival_time": {
        "hour": 12
      },
      "special_requests": "We will need an extra cot."
    }
  },
  "booker": {
    "address": {
      "address_line": "Road-1, house-2",
      "city": "Amsterdam",
      "country": "nl",
      "post_code": "11111"
    },
    "company": "Booking B.V",
    "email": "test.name@booking.com",
    "language": "en-gb",
    "name": {
      "first_name": "Test",
      "last_name": "Name"
    },
    "telephone": "12345678"
  },
  "order_token": "sample-token",
  "payment": {
    "card": {
      "cardholder": "Test Name",
      "cvc": "111",
      "expiry_date": "2030-10",
      "number": "23333333333333"
    },
    "include_receipt": true,
    "method": "card",
    "timing": "pay_at_the_property"
  }
}
```

### Example - orders/create response

A successful response returns key order and payment details:

| Field | Description |
|  --- | --- |
| `request_id` | Always returned (for support) |
| `payment.receipt_url` | Link to the payment receipt (if available). |
| `authorisation_form_url` | Link to the authorisation form (For [Corporate Partners using VCC](/demand/docs/payments/payments-examples3#paying-at-property-with-authorisation-form)) required to pay at the property. May be null. |
| `accommodation.order` | Unique identifier for the booking, which can be used for [cancellations](/demand/docs/open-api/demand-api/orders/orders/cancel), customer support or post-booking tasks (see [/orders/details/*](/demand/docs/orders-api/order-details)) |
| `accommodation.pincode` | Short authorisation code required for specific operations (used with `third_party_inventory` if applicable). |
| `accommodation.reservation` | For backward compatibility with V2, only used if you need to access legacy accommodation orders. |
| `accommodation.third_party_inventory` | Optional, only for TPI orders. See [TPI rates guide](/demand/docs/accommodations/tpi/about-tpi) |


#### Example response


```json
{
  "request_id": "01j69mtd91x3pdcmqyj0spebt9",
  "data": {
    "payment": {
      "receipt_url": "https://secure.booking.com/payment_receipt.html?product_type=BookingBudget&aid=2373042&auth_key=8riKJJ0XuxDhk4ds&lang=en",
      "authorisation_form_url": null
    },
    "accommodation": {
      "order": "5006302528200239",
      "pincode": "884512",
      "reservation": 55303962
    }
  }
}
```

## Step 4 - Confirm the booking with the traveller

Use the /orders/create data to:

* Display a booking confirmation page.
* Notify the traveller that their booking is confirmed.


Curious to know more?
* Refer to the [orders/details guide](/demand/docs/orders-api/order-details) for instructions and examples on how to use this endpoint.
* Learn more about [Accommodation pricing](/demand/docs/accommodations/prices-accommodations) and how you can display it in your application.