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	Validate order details before booking: ✓ Confirm guest allocation (prevents pricing errors) ✓ Verify the final price breakdown. ✓ Retrieve the `order_token` required by orders/create. ✓ Review available payment timings, methods and schedules.
/orders/create	Confirm the booking and process payment using the `order_token`. This token encapsulates all order information, no need to rebuild the order.

Endpoint

Use it to...

/orders/preview

Validate order details before booking:

✓ Confirm guest allocation (prevents pricing errors)

✓ Verify the final price breakdown.

✓ Retrieve the order_token required by orders/create.

✓ Review available payment timings, methods and schedules.

/orders/create

Confirm the booking and process payment using the order_token.
- This token encapsulates all order information, 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 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.
Search, look and book	/accommodations/availability endpoint.

Define the request

Your /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 preceding response.
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`
Optional	`booker.travel_purpose` and `booker.user_groups` — Include if returned in the preceding response; otherwise, can be omitted.

Example:

{
  "booker": {
    "country": "nl",
    "platform": "mobile",
    "travel_purpose": "leisure",
    "user_groups": [
      "authenticated"
    ]
  },
  "currency": "EUR",
  "accommodation": {
    "id": 6745031,
    "checkin": "2025-11-10",
    "checkout": "2025-11-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.

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

{
  "products": [
    {
      "id": "1050736002_377311511_0_2_0",
      "number_of_adults": 1,
      "room": 1050736002
    },
    {
      "id": "1050736002_377311511_0_2_0",
      "number_of_adults": 1,
      "room": 1050736002
    }
  ]
}

Allocation data depends on your integration type:

Integration type	Guest allocation
Search and book	Guest allocation is already included in the `products` from the /accommodations/search endpoint response.
Search, look and book flow	Guest allocation is included in `recommendation.products` from the /accommodations/availability response.

Example with recommendation.products:

{
  "recommendation": {
    "products": [
      {
        "id": "1050736003_377312697_1_2_0",
        "number_of_adults": 1,
        "room": 1050736002
      },
      {
        "id": "1050736003_377312697_1_2_0",
        "number_of_adults": 1,
        "room": 1050736002
      }
    ]
  }
}

For non-recommended products, check products.maximum_occupancy from the /accommodations/availability and assign guests manually. See the Occupancy guide

Orders/preview response

A successful response from the /orders/preview endpoint includes:

Accommodation-specific data `id` `currency` `general_policies.payment` - Supported payment timings and methods. If products support different payment options, the payment object in the preview shows only the methods and timings supported by all selected products.
Product-specific data `id` `policies` - cancellation conditions and meal plans. `price` - Final price for product (See Accommodation pricing guide for details and examples) `room` - The id of the room. `third_party_inventory` - If the rate is provided by a thid party source. See TPI rates guide.
Order token Encapsulates order details for use in /orders/create request.

Accommodation-specific data

id
currency
general_policies.payment - Supported payment timings and methods.

If products support different payment options, the payment object in the preview shows only the methods and timings supported by all selected products.

Product-specific data

id
policies - cancellation conditions and meal plans.
price - Final price for product (See Accommodation pricing guide for details and examples)
room - The id of the room.
third_party_inventory - If the rate is provided by a thid party source. See TPI rates guide.

Order token

Encapsulates order details for use in /orders/create request.

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

Step 3 - Call the /orders/create endpoint

→ Once the traveller confirms, call /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 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.

Admonition name

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 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 once payment is due (e.g. 3 days before arrival).

Order token

order_token
Token from the /orders/preview response.
Expires after 15 minutes. Repeat /orders/preview if expired.

The order_token is only valid for 15 minutes after it is issued. If the order_token expires, repeat the /orders/preview call to generate a new one.

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:

{
  "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) required to pay at the property. May be null.
`accommodation.order`	Unique identifier for the booking, which can be used for cancellations, customer support or post-booking tasks (see /orders/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

Example response

{
  "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 for instructions and examples on how to use this endpoint.
Learn more about Accommodation pricing and how you can display it in your application.