/orders/preview and /orders/create

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

You must use two endpoints to create an order:

1. Use /orders/preview to obtain final price and payment information, so that you can check that all details are correct before creating the order.

2. Use /orders/create to book the requested products and process payment for the order.

How 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. To do this:

1. Call /orders/preview. Define your request using data from the preceding /accommodations/search or /accommodations/availability call, as appropriate for your particular application flow:

   • For a search and book flow, use data from the preceding /accommodations/search call.

   • For a search, look and book flow, use data from the preceding /accommodations/availability call.

2. Use the /orders/preview response to populate your Order preview page. The traveller can now:

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

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

4. Confirm the booking with the traveller. Use the /orders/create response data to populate your Order confirmation page.

/orders/preview

How to define your request

Populate the /orders/preview request 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:

• For a 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
  }
],
...

• For a 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.

• Product-specific details:

  • Final price of each product

  • The product's cancellation and 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.

  The order_token is valid for 15 minutes. If you try to use it after this period, the /orders/create request will fail.

Notes:

• price details provide a full breakdown of all included charges. See Prices (/orders) 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.

• cancellation fees and schedules are returned for each product.

/orders/create

How to 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.

  Note: 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 do the following:

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

  Note: A receipt will only be generated when the payment.timing field is pay_online_now. Receipts are not available for pay_online_later or pay_at_property payments.

Response

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

• accommodation.order: This is a unique id that you can use to identify the order if you subsequently wish to cancel it (see Cancel an order), or to get information about it for use in a post-booking task (see /orders/details/*).

  Note: An accommodation.reservation id is also provided, for backward compatibility with V2. You should only use this if you need to access orders created using V2 after you have migrated your integration to V3. For more information, see Reservation and order ids.

• accommodation.pincode: This is a 4-digit authorisation number that is required to perform certain operations on the order. For example, it is a required field for the /orders/cancel request.

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

Example

See Search for and book accommodation.