Orders FAQs

After you check the availability, you need to call the /orders/preview endpoint to return an order token (valid for 15 min).

• This token must be passed in the /orders/create request (equivalent of processBooking).
• This is to reduce the error % caused by property changing prices, or if someone else makes a booking.
• If token expires, you need to call preview again.

In /orders preview, you no longer need to pass a price but just pass block_ID and other details.

Key things to check: price, payment policy and cancellation policy.

Use the /orders/preview endpoint to retrieve the final price, detailed breakdown, and applicable payment and cancellation policies for each product in the booking.

This step is crucial to ensure transparency and accuracy before proceeding with the payment in the orders/create call.

To create a new accommodation order using the /orders/create endpoint, the following mandatory fields are required:

• accommodation.products.id - The product ID, which must match the product ID from the /orders/preview request.
• accommodation.products[].guests[] - The name and email for each guest associated with the product.
• booker - The contact details of the person placing the order.
• order_token - This token is copied from the /orders/preview response and is valid for 15 minutes. If it expires, a new one must be generated by repeating the /orders/preview call.
• payment - Specifies the payment method, timing, and optionally, card details.

Additionally, there are optional fields that you can include:

• accommodation.label - A free-text label to help identify the order later.
• accommodation.products[].bed_configuration - An identifier for the desired bed configuration.
• accommodation.remarks - Contains optional guest requests, such as estimated_arrival_time or special_requests.
• booker.company - The booker's company name.
• payment.include_receipt - Set to true to generate a payment receipt.

Submit this information via the /orders/create endpoint to successfully place a booking.

This token is available for 15 minutes. After this time, it expires.

If you try to make an /orders/create call with an expired order_token, it will return an error.

Repeat the /orders/preview call to get a new order_token and try again with the new token.

The receipt URL is not included automatically in the /orders/create responses.

For pay_online_now bookings, you must:

• Pass the "payment.include_receipt:true" field in your orders/create request.

Example request:

  "payment": {
    "card": {
      "cardholder": "Test Name",
      "cvc": "111",
      "expiry_date": "2030-10",
      "number": "23333333333333"
    },
    "include_receipt": true, 
    "method": "card",
    "timing": "pay_at_the_property"
  }
}

So the response includes the link to the receipt.

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

If the payment timing is pay_online_later, you can retrieve a credit slip by calling the /orders/details/accommodations endpoint once the scheduled payment is active.

Here's an example of the /orders/details/accommodations response including the credit_slip field:

 {
  "booker": {
    "platform": "mobile"
  },
  "cancellation_details": {
    ...
  },
  "credit_slip": 1223445, 
  "currency": {
    "accommodation": "EUR",
    "booker": "USD"
  },
  "total": {
    "accommodation_currency": 170.01,
    "booker_currency": 186.87
  },
  ...

Demand API V3 retrieves only a single order ID together with a single pincode number, as the /orders/create request is for one booking, even when the order includes multiple rooms or travel services.

A cancellation policy is a combination of penalty conditions and determines the terms under which a traveller can cancel their reservation and whether they are entitled to a refund or must pay a fee.

• Each penalty condition defines how much (in percentage of the total booking price or in nights) and when a guest is charged in case of cancellation or no-show.

• Cancellation policies are specific to a property and can be: Flexible, Partially refundable (Special conditions) or Non-refundable.

A cancellation fee is an amount that must be paid upon cancellation of a booking, depending on the applicable cancellation policy and the time of cancellation.

Key points about cancellation fees:

• There are different types of fees that can be applied.

• For partially refundable policies, a fee based on 50% of the total booking price or the cost of the first night stay may apply.

• The specific fee calculation and conditions can be checked in the /orders/preview and orders/details or /orders/details/accommodations endpoint responses.

• In the API responses, the fee is indicated in the price field within the cancellation policy details (e.g., in orders/preview) or in the fee field within cancellation_details (e.g., in orders/details or orders/details/accommodations).

• The fee field is null if the cancelled product has a free cancellation policy.

It is important to inform travellers about applicable cancellation policies and fees during the booking process.

This is for cases when the order has not been cancelled, but there is a no-show on checkin time.

• A "no-show" refers to a situation where a guest fails to arrive for a reservation without prior notification.
• In the case of no-show, the cancellation fee will be the total price of the reservation.

You can find the applicable cancellation policy information at different stages using the Demand API endpoints:

The cancellation policy details are typically found within the policies.cancellation field in the response of these endpoints.

No, cancellation policies can vary per product. This means that in multi-room bookings, each room may have its own cancellation terms. It's essential to review the policies for each room individually.

To cancel an order, follow these steps:

1. Retrieve the order details using the /orders/details endpoint to confirm the reservation status and applicable cancellation policies.
2. If cancellation is permitted, proceed to cancel the order using the /orders/cancel endpoint.

Always review the cancellation policies before initiating a cancellation to understand any potential charges.

You can determine if an order has been cancelled by checking the status field in the responses from the /orders/details and /orders/details/accommodations endpoints.

Additionally, the cancellation_details field will provide information about the terms of cancellation, including any fees charged and when they were charged.

For example, a cancelled order might have a status like "cancelled_by_guest":

Yes, reservations created in V2 can be modified in V3.

• In V2, multiple endpoints were used to modify reservation details. In V3, you can use the /orders/modify endpoint for these modifications.

• The V3 API retains the V2 reservation_id for backward compatibility - use it in your orders/modify request.

This allows you to access orders created using V2 after migrating to V3.

To modify a V2 reservation in V3:

1. Use the V3 /orders/modify endpoint.
2. Identify the reservation using its V2 reservation_id. The V3 API retains the reservation id specifically for backward compatibility with V2 bookings.
3. Include the specific changes you want to make in the request body, such as modifying check-in/check-out dates using the modification.accommodation object and specifying the reservation id.

Yes, you can modify the dates using the /orders/modify endpoint.

However, it's recommended to first check availability for the new dates and updated pricing using the /accommodations/availability endpoint to avoid any unexpected costs.

Modifying the number of guests is subject to certain restrictions:

• If the rate is tied to a specific occupancy, changing the guest count may not be allowed.
• Ensure that the new number of guests does not exceed the room's maximum occupancy.

In cases where guest changes aren't permitted, consider cancelling the existing reservation and creating a new one with the desired guest count.

Yes, you can update the payment method using the /orders/modify endpoint.

Ensure that the new card type is accepted by the property. You can verify the accepted card types via the methods.cards array returned by the /orders/preview endpoint.

There are two possible reasons for this:

• Commission is not enabled for that partner.
• If an order is cancelled, commission will be returned as null.

Right now there is no order ids for testing purposes.

We recommend to create a real booking in our test hotel (Accommodation ID 10507360 - Demand API sandbox Hotel Orion) using a real credit card.

While it's a test booking, the charge is real. However, every Monday following a test booking, we will automatically refund the charge to the used credit card.

• Check the recommendations for testing in the Payments quick guide

• Double-check the reservation ID is correct.
• Use the /orders/details/accommodations endpoint to confirm the reservation’s current status.

You are unable to modify a prepaid online payment order because the system will return a "status": "failed" message, and the modification will not be applied. The booking will remain successfully paid and valid.

To make changes:

1. Retrieve the booking’s cancellation policy using /orders/details endpoint.
2. Cancel the existing booking if allowed.
3. Create a new order with the desired changes.