Create your orders

Learn how to use the /orders/preview and /orders/create endpoints to create an order for the selected products

You must use two endpoints to create your orders:

Steps to create an order

When a traveller has chosen the products they want to book, from either your Search results page or Products page, you can create an order for those products.

1. Call the /orders/preview

Define your /orders/preview request using data from the preceding endpoint responses, as appropriate for your particular application flow.

If you are implementing:

• Search and book flow - Define your request using data from the preceding /accommodations/search response.
• Search, look and book flow - Define your request using data from the preceding /accommodations/availability response.

Define your request

Define the /orders/preview request using the fields as follows:

• booker, currency, accommodation.checkin and accommodation.checkout: Use the appropriate values from the preceding request.

• accommodation.id and products: Use the appropriate values from the preceding response for the products selected by the traveller.

Guest allocation

You must specify the exact allocation of guests to each product in the products.allocation field. For example, the following request shows that the order contains two instances of the same product, with one adult guest allocated to each product.

...
"accommodation": {
  "id": 10507360,
  ...
  "products": [{
      "id": "1050736002_377311511_0_2_0",
      "allocation": {
        "number_of_adults": 1
      }
    },
    {
      "id": "1050736002_377311511_0_2_0",
      "allocation": {
        "number_of_adults": 1
      }
    }
  ]
}
...

How you obtain the guest allocation information depends on the application flow that you are using:

• Search and book flow - The preceding /accommodations/search call returns exact guest allocation for each recommended product, in the products object.

  • For example, the following response shows a recommendation of two instances of the same product, with one adult guest allocated to each product.

...
"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
  }
],
...

• Search, look and book flow - The preceding /accommodations/availability call similarly returns exact guest allocation for each recommended product, but in the recommendation.products object.

  For example:

...
"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 other available products, exact allocation data is not provided. Instead, the products.maximum_occupancy object shows the maximum number of guests that can stay in the room when it is part of this product. For example, the following response indicates that the product can accommodate either 1 or 2 adult guests. Children are not allowed.

...
"products": [{
    "id": "1050736002_377311511_0_2_0",
    ...
    "maximum_occupancy": {
      "adults": 2,
      "children": null,
      "total": 2
    },
    "number_available_at_this_price": 10,
    ...
    "price": {
      "book": 184.00,
      "total": 184.00
    },
    "room": 1050736002
    ...
...

If the product selection includes non-recommended products, you must determine and validate the exact allocation, both for each selected product and for the total number of products and guests.

Response

A successful /orders/preview response returns the following information about the order:

• Accommodation-specific details:

  • Final price of the accommodation

  • payment timelines and methods, defining when and how you can pay. Check the Payment section for more details on payment methods and use cases.

• Product-specific details:

  • Final price of each product.

  • The product's cancellation policies: fees and schedules. Refer to Cancellation policies section for more information.

  • The meal_plan policies.

• A secure order_token. The token contains encapsulated details about the selected order, which you will need to pass to the /orders/create request.

  • Using this token reduces the risk of data mismatch errors and provides a more efficient booking experience.

Important considerations

• price details provide a full breakdown of all included charges. See Pricing in /orders guide for more information.

• Different products may support different payment timelines and methods. The payment object contains only timelines and methods that are supported by every selected product in the order.

2. Display your Order preview page

Display all details in your order preview page so the traveller can:

• Check their order details.

• Supply the necessary information on when and how they will pay.

• Supply any other information needed to complete the order - for example, guest details for rooms, estimated arrival times or special requests.

Example:

2. /orders/create

Define your request using the order token from the /orders/preview response, and the traveller's inputs from the Order preview page.

Define your request

You must supply the following information in the /orders/create request:

• booker: Specify the full contact details of the person placing the order.

• order_token: Copy the token from the preceding /orders/preview response.

  Remember that the token is only valid for 15 minutes after it has been issued.

• payment: Specify the required details for the payment option (how and when they want to pay) selected by the traveller.

Optionally, you can also:

• Supply additional information about the requested accommodation or included products, such as guests' arrival times or special requests.

• Generate a receipt for the payment, by setting the payment.include_receipt field to true.

  A receipt is only generated when the payment.timing field is pay_online_now. Receipts are not available for pay_online_later or pay_at_the_property payments.

Response

A successful accommodation /orders/create response returns the following information about the order:

{
"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
    }
}
}

• payment.receipt_url: This is a link to the payment receipt for the order (if provided).

• authorisation_form_url: In this example, this field is null as no payment instructions or authorisations have been included.

  • In case the order is created for Corporate Partners using VCC to pay at the property, this field will become mandatory in the order/create request, and a link to the authorisation form will be generated as part of the response here.

• Order ID (accommodation.order)

  • This is the booking unique identifier that you should use to cancel your order.
  • You can use this id for Customer Services in case any support is needed.
  • Use it if you need order information for post-booking tasks (see /orders/details/*)

• Pincode(accommodation.pincode):

  • This is a shorter authorisation number that is required to perform certain operations on the order.
  • It is also included in the booking confirmation mail.
  • Use it for Customer Services requests.

• Reservation ID(accommodation.reservation):

  • This is a V2 legacy, we keep it for backward compatibility.
  • You should only use this if you need to access orders created using V2 after you have migrated your integration to V3.

3. Confirm the booking with the traveller.

Use the /orders/create response data to populate your Order confirmation page.