Search for and book accommodation

Learn how to use the Demand API in your client application so that a traveller can search for, look at and book accommodation provided by Booking.com.

Overview

This tutorial provides a simple example of how you can integrate the Demand API with your client application so that:

A traveller can search for accommodation provided by Booking.com.
When the traveller sees a property they like, they can look at detailed information about the property, including real-time room availability and pricing.
When the traveller decides to book, you handle their booking in one of two ways, depending on the integration type that you are using:
- Search, look and book: Process the booking directly in your application, using the /orders API.
- Search and look: Redirect the traveller to Booking.com to make the booking.

Note

The Search, look and book integration type requires an appropriate partner agreement with Booking.com.

The following diagram shows the steps involved. The rest of the tutorial explains each step in detail.

Getting Started Steps

Before you start

If you want to try out the steps in this tutorial yourself, make sure that:

You have a suitable API testing tool, such as cURL or Postman.
You have signed up as a Booking.com Affiliate Partner.
You have a valid API key that allows you to use the required Demand API endpoints and the Demand API sandbox server https://demandapi-sandbox.booking.com.

Attention

**Make sure that you correctly authenticate every call that you make to a Demand API endpoint. For more information, see Authentication and Authorisation

Step 1: Search for matching properties

A traveller visits your website to find somewhere to stay in Amsterdam. They want to book a 2-night stay, for 2 adults with no children, and they want 1 room. The traveller is in the Netherlands and is using your website from their mobile phone.

Call accommodations/search to find properties that match your traveller’s search criteria.

Request

Use the following fields to construct the request body:

city: Specify the unique city id for the required destination. For Amsterdam, this is -2140479. (You can obtain city ids from the List cities endpoint.)
checkin, checkout: Specify the traveller's requested arrival and departure () dates (in yyyy-mm-dd format).
guests.number_of_rooms and guests.number_of_adults: Specify the number of rooms the traveller needs (1), and the number of adults who will be staying (2).
booker.platform: Specify the platform from which the search request is being made (mobile). This is required so that any platform-based prices and deals can be returned correctly.
booker.country: Specify the country from which the search request is being made (nl). This is required to ensure that the response complies with relevant laws on the display of taxes and fees.

Your request body should look like this example. (Try it yourself):

{
  "city": -2140479,
  "booker": {
    "country": "nl",
    "platform": "mobile"
  },
  "checkin": "2023-11-06",
  "checkout": "2023-11-08",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}

Response

The response contains a list of properties that match the specified search criteria. For each property in the list, the response contains:

The property’s unique identifier (id). You will use this id in the next step to get further details about the property.
The best price that the property has available for the specified search criteria. By default, the price is shown in the local currency.

For example:

...
{
  "id": 10507360,
  "currency": "EUR",
  "deep_link_url": "booking://hotel/10507360?affiliate_id=956509&checkin=2023-11-06&checkout=2023-11-08&mcid=10",
  "price": {
    "book": 184.00,
    "total": 184.00
  },
  "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=956509&checkin=2023-11-06&checkout=2023-11-08&no_rooms=1&group_adults=2&mcid=10"
},
...

Step 2: Get details of matching properties

Before you can show the search results to the traveller you need to get some more information about each property.

Call /accommodations/details to get additional information about the properties returned in the accommodations/search response.

Request

Use the following field to construct the request body:

accommodations: Specify the list of property ids returned in the accommodations/search response.

Your request body should look like this example. Try it yourself.

{
  "accommodations": [10507360]
}

Response

The response contains basic information about each property. For example:

...
{
  "id": 10507360,
  "name": {
    "en-gb": "Demand API Sandbox Hotel Orion"
  },
  "accommodation_type": 204,
  ...
  "checkin_checkout_times": {
    ...
    "contacts": {
      "general": {
        "email": "demand.api.dev@booking.com",
        ...
        "currency": "EUR",
        ...
        "location": {
          "address": {
            "en-gb": "Oosterdoksstraat 154"
          },
          "city": -2140479,
          ...
        },
        ...
        "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=956509"
      },
...

Display your search results page

You now have the necessary information to display the search results to the traveller.

Select the data from the accommodations/search and /accommodations/details responses to provide the level of information that is appropriate for your particular business scenario.

Note

The example request shown above uses only the required fields, to provide basic details about the hotel. You can use the optional extras field to get more details about some or all of the following categories: description, facilities, payment, photos, policies, rooms.

For example, if you want to use a photograph in your search results, add the field "extras": ["photos"] to your request.

Step 3: Get a property's availability and prices

*The traveller browses through the search results, looking for properties where they might like to stay. They like the look of the "Demand API Sandbox Hotel Orion". Now they want to see more details about the hotel and the full list of rooms and prices that it has available. *

Call Get a property's availability to provide real-time information about the availability and prices of all rooms offered by the property.

Request

Use the following fields to construct the request body:

accommodation: Specify the id of the property that the traveller wants to look at.
booker, checkin, checkout, and guests: Use the same values that you used in your accommodations/search request in step 1.

Your request body should look like this example. (Try it yourself):

Use the following fields to construct the request body:

accommodation: Specify the id of the property that the traveller wants to look at.
booker, checkin, checkout, and guests: Use the same values that you used in your accommodations/search request in step 1.

Your request body should look like this example. (Try it yourself):

{
  "accommodation": 10507360,
  "booker": {
    "platform": "desktop",
    "country": "nl"
  },
  "checkin": "2023-11-06",
  "checkout": "2023-11-08",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}

Response

The response contains a list of the property's available products that match the specified search criteria.

Note

A product is an item that the property sells. Its definition includes a room, plus the cancellation, meal and payment policies that apply, room occupancy limits, any deals that apply, and a price.

For each product in the products list, the response shows the product's unique identifier (id), and details. For example:

...
"products": [{
    "id": "1050736002_377312697_2_2_0",
    "deal": null,
    "maximum_occupancy": {
      "adults": 2,
      "children": null,
      "total": 2
    },
    "number_available_at_this_price": 10,
    "policies": {
      "cancellation": {
        "free_cancellation_until": null,
        "type": "special_conditions"
      },
      "meal_plan": {
        "meals": [],
        "plan": "no_plan"
      },
      "payment": {
        "timings": [
          "pay_at_the_property",
          "pay_online_later",
          "pay_online_now"
        ]
      }
    },
    "price": {
      "book": 204.00,
      "total": 204.00
    },
    "room": 1050736002
  },
...

There is also a recommendation object, containing details of the cheapest product that matches the specified search criteria, allowing you to highlight this product to the traveller. For example:

...
"recommendation": {
  "price": {
    "book": 184.00,
    "total": 184.00
  },
  "products": [{
    "id": "1050736002_377311511_0_2_0",
    "children": [],
    "number_of_adults": 2,
    "price": {
      "book": 184.00,
      "total": 184.00
    }
  }]
},
...

Note

Note: Product availability can change very quickly. If a product sells in the time between the calls to /accommodations/search and /accommodations/availability, recommendation will be returned as null.

For example, suppose a hotel had one product matching the search criteria for the /accommodations/search request, so was included in the search results. If that product was sold by the time /accommodations/availability was called, recommendation would be returned as null.

A null value can also be returned in some cases if request parameters change between the two calls.

Display your product page

You can now show the traveller complete details of the property they want to look at, including real-time product availability and prices.

Select the data from your /accommodations/details and /accommodations/availability responses to provide the appropriate level of information for your particular business scenario.

Next step - booking

If the traveller decides to make a booking, what you do next depends on your integration type:

Search, look and book: To process bookings directly in your application, using the /orders API, go to Step 4 (Book): Get final booking details.
Search and look: To redirect travellers to Booking.com to process bookings, go to Alternative booking method.

Step 4: Preview the order

After browsing the details of the "Demand API Sandbox Hotel Orion", the traveller decides to book the recommended product.

Call /orders/preview to get final details of what property and products the traveller is booking, what they will have to pay, when and how they can pay it, and the cancellation terms that will apply.

Request

Use the following fields to construct the request body:

booker.platform and booker.country, accommodation.id, accommodation.checkin and accommodation.checkout: Use the same values that you used in your /accommodations/availability request in step 3.
currency: Use EUR, because the traveller is using your website from the Netherlands. All prices in the response will be shown both in this currency (as booker_currency) and in the property's local currency (as accommodation_currency.)
accommodation.products.id: Specify the id of the product that you want to book. Use the recommendation.products.id value (1050736002_377311511_0_2_0) from the /accommodations/availability response in step 3.
accommodation.products.allocation.number_of_adults: Specify the number of adults who will stay in the room used in the product. Use the recommendation.products.number_of_adults value (2) from the /accommodations/availability response in step 3.

Your request body should look like this example. (Try it yourself):

{
    "booker": {
        "platform": "mobile",
        "country": "nl"
    },
    "currency": "EUR",
    "accommodation": {
        "id": 10507360,
        "checkin": "2023-11-06",  
        "checkout": "2023-11-08",  
        "products": [
            {
                "id": "1050736002_377311511_0_2_0",
                "allocation": {
                    "number_of_adults": 2
                }
            }
        ]


    }
}

Response

The response contains the following information about the order:

accommodation.general_policies.payment shows when and how the traveller can pay for the order. In the following example, the traveller must pay_online_now, which they can do using any of the indicated payment cards. (Cards are shown by their id. You can use List payment cards to find card names.)

...
"accommodation": {
  "id": 10507360,
  "currency": {
    "accommodation": "EUR",
    "booker": "EUR"
  },
  "general_policies": {
    "payment": {
      "pay_at_the_property": null,
      "pay_online_later": null,
      "pay_online_now": {
        ...
        "methods": {
          ...
          "cards": [
              1,
              4,
              5,
              11,
              ...
            ]
...

accommodation.general_policies.price gives a detailed breakdown of what the traveller needs to pay for the order. In the following example, the total price (in EUR) of the order is 184. This comprises a base price of 165.14, plus extra_charges of 14.86 for VAT (21) and 4.00 for city tax (22) . (Charges are shown by their charge id. You can use /accommodations/constants to identify charges.) For more information about the individual components of the price object, see Prices and orders.

...
"accommodation": {
  "id": 10507360,
  "currency": {
    "accommodation": "EUR",
    "booker": "EUR"
  },
  ...
  "price": {
    "base": {
      "accommodation_currency": 165.14,
      "booker_currency": 165.14
    },
    "extra_charges": {
      "conditional": [],
      "non_conditional": [{
          "charge": 21,
          "total_amount": {
            "accommodation_currency": 14.86,
            "booker_currency": 14.86
          }
        },
        {
          "charge": 22,
          "total_amount": {
            "accommodation_currency": 4.00,
            "booker_currency": 4.00
          }
        }
      ]
    },
    "total": {
      "accommodation_currency": 184.00,
      "booker_currency": 184.00
    }
  },
...

For each product in the order, accommodation.products.price gives a detailed breakdown of what the traveller needs to pay for the product, including a full breakdown of the charges. As this order only contains a single product, the following example is very similar to the previous one, but you can see that the city tax (22) is levied on a per_person_per_night basis, at a rate of 1.00 EUR.

...
"accommodation": {
  "id": 10507360,
  "currency": {
    "accommodation": "EUR",
    "booker": "EUR"
  },
  ...
  "products": [{
    "id": "1050736002_377311511_0_2_0",
    ...
    "price": {
      "base": {
        "accommodation_currency": 165.14,
        "booker_currency": 165.14
      },
      "extra_charges": {
        "conditional": [],
        "non_conditional": [{
            "charge": 22,
            "mode": "per_person_per_night",
            "percentage": null,
            "total_amount": {
              "accommodation_currency": 4.00,
              "booker_currency": 4.00
            },
            "unit_amount": {
              "accommodation_currency": 1.00,
              "booker_currency": 1.00
            }
          },
          {
            "charge": 21,
            "mode": "percentage",
            "percentage": 9.00,
            "total_amount": {
              "accommodation_currency": 14.86,
              "booker_currency": 14.86
            },
            "unit_amount": {
              "accommodation_currency": null,
              "booker_currency": null
            }
          }
        ]
      },
      "total": {
        "accommodation_currency": 184.00,
        "booker_currency": 184.00
      }
    }
  }]
},
...

For each product in the order, accommodation.products.policies shows the details of the cancellation and meal_plan policies. In the following example, the product does not include any meals or any free cancellation period. In the event of cancellation, a fee of 180 EUR (the total price minus the city tax) applies from the moment of booking.

...
"accommodation": {
  "id": 10507360,
  "currency": {
    "accommodation": "EUR",
    "booker": "EUR"
  },
  ...
  "products": [{
        "id": "1050736002_377311511_0_2_0",
        "policies": {
          "cancellation": [{
            "from": "now",
            "price": {
              "accommodation_currency": 180.00,
              "booker_currency": 180.00
            }
          }],
          "meal_plan": {
            "meals": [],
            "plan": "no_plan"
          }
        },

order_token is a secure token that contains encapsulated details about the order. You will need to pass this token to the /orders/create request in the next step. Using this token reduces the risk of data mismatch errors between the endpoints and provides a more efficient booking experience.

Attention

The order_token expires after 15 minutes. You must therefore call /orders/create within this window.

...
"accommodation": {
  "id": 10507360,
  ...
  ...
  "order_token": "eyJhbGciOiJIUzI1NiJ9.eyJ....<truncated for display in this example>...QytoS0yU"
}
...

Display your order preview page

You can now show the traveller final details of what they are booking, what they will have to pay, when and how they can pay it, and the cancellation terms that will apply.

Select the data from your /orders/preview response to provide the appropriate information on your preview page.

You should also gather any other information needed from the traveller to complete the order - for example, guest details for rooms, estimated arrival times or special requests.

Step 5: Create the order

After checking the details of the order, the traveller supplies their payment information and any other needed information, and proceeds with the booking.

Call /orders/create to process the payment and make the reservation with the property.

Request

Use the following fields to construct the request body:

booker: Specify the address, email, name and telephone number details of the person who is making the booking (the traveller, in this example)..
order_token: Use the order_token returned in the /orders/preview response in step 4.
payment.card: Specify the card details provided by the traveller.
payment.include_receipt: Specify true to generate a receipt that you can provide to the traveller.
payment.timing: Specify pay_online_now, as this was the only supported option for the selected product. Your request body should look like this example. (Try it yourself):

...
"booker": {
  "address": {
    "address_line": "Road-1, house-2",
    "city": "Amsterdam",
    "country": "NL",
    "post_code": "12345"
  },
  "email": "test.name@example.com",
  "name": {
    "first_name": "Test",
    "last_name": "Name"
  },
  "telephone": "12345678"
},
"order_token": "eyJhbGciOiJIUzI1NiJ9.eyJ....<truncated for display in this example>...QytoS0yU",
"payment": {
  "card": {
    "cardholder": "Test Name",
    "cvc": "123",
    "expiry_date": "2030-10",
    "number": "1234123412341234"
  },
  "include_receipt": true,
  "timing": "pay_online_now"
}

Response

The response contains the following information about the order:

order: Unique id for the order that you will need if you subsequently wish to cancel it or to get information about it for use in a post-booking task.
receipt_url: A link to the payment receipt for the order.

...
"accommodation": {
  "order": "xxxxxxxx",
  ...
},
"payment": {
  "receipt_url": "https://secure.booking.com/payment_receipt.html?bn=12345678&pincode=1234&lang=en"
}

Alternative booking method for search and look

If you are using a Search and look integration type, you cannot process bookings directly as described in step 4 and step 5 of this tutorial.

However, you can still process and receive commission on bookings by redirecting travellers to the Booking.com website, so that they can make their booking there. To do this, when a traveller has chosen the product(s) that they want to book, redirect them to the url returned in your /accommodations/availability response.

The url contains your affiliate id (aid), so that the booking can be attributed to you.

For example:

...
   "url": "https://www.booking.com/<SELECTED_ACCOMMODATION>.html?aid=956509&checkin=2023-11-06&checkout=2023-11-08&no_rooms=1&group_adults=2&mcid=10"
...

The Booking.com website displays the property page for the traveller's chosen property:

The Search box shows the traveller's search criteria.
In the Availability section, the details for the traveller's selected product are shown at the top of the list.