About the Booking.com Connectivity APIs

The Booking.com Connectivity APIs enable Connectivity Partners to send and retrieve data for properties listed on Booking.com. They can manage room availability, reservations, prices, and many other things — all using their own systems. This enables them to build a "one-stop shop" for their connected properties, allowing property owners to easily manage their information on multiple websites.

Available APIs

The Booking.com Connectivity APIs offer a number of specialised functions, divided into these categories:

• Content — Create properties, rooms, rates, and policies, and link this information together for the Booking.com website.
• Rates & Availability — Load inventory counts, rates, and price availability restrictions (for specific room-rate combinations), per date and/or date range combination.
• Reservations — Retrieve reservations, modifications, and cancellations made on Booking.com.
• Promotions — Create special promotions for certain date ranges and booker types.
• Reporting — Report credit card problems, changes to reservations after check-in, and no-shows.

In addition to the specialised APIs, we also have a set of supporting APIs for retrieving general Booking.com system information, such as accepted currency codes and room names.

What we expect from Connectivity Partners

To become Booking.com Connectivity Partners, companies must meet specific onboarding requirements. After you become a Connectivity Partner, we expect you to keep up with the continuous changes and improvements we make to the Booking.com Connectivity APIs. This ensures that all connected properties have access to the latest Booking.com features.

As a Booking.com Connectivity Partner, you should strive to:

• support all available API functions;
• work with your PMS partners to implement existing and new Booking.com functionalities in an end-user friendly way;
• load at least a full year of rates and availability for each property;
• provide your connected properties with an easy-to-use interface to manage their rooms and rates;
• encourage your connected properties to visit the Booking.com Extranet to check Booking.com-specific details and verify information.
• minimise the number of reservations falling back to e-mail.

We also recommend that you proactively inform your connected properties about:

• low room availability;
• any dates beyond which they are no longer bookable on Booking.com;
• which specific rooms/rates are no longer bookable after a certain date;
• unmapped rooms or rates;
• opportunities for growing their business.

If you want to request new functionality, please discuss this with your Booking.com Connectivity Account Manager.

Base URLs

The Booking.com Connectivity APIs use these base URLs:

• https://supply-xml.booking.com — For non-PCI servers, used for any non-reservation related information.
• https://secure-supply-xml.booking.com — For PCI servers, used for reservation retrieval and confirmation.

You will find URLs for specific endpoints, as well as information on how to call them, in the rest of this documentation. You must use HTTPS for all calls.

Whitelisting

If you need to add the Booking.com Connectivity APIs to your whitelist, we strongly recommend that you add the domain name(s) only. Our IP ranges are constantly changing. Booking.com accepts no liability if you add a range of IP addresses or a single IP address to your whitelist. For reference, here are the current probable IP ranges for each domain:

Request and response formats

The Booking.com Connectivity APIs accept requests in these formats:

• OTA – OTA is an XML schema developed by the OpenTravel Alliance. It is tailored to the travel industry and provides online travel agencies and channel managers with a common data model to exchange information. You can download the full OTA specification from the OpenTravel Alliance website, or browse the data model here. The Booking.com Connectivity APIs use OTA version 2003B.
• B.XML – B.XML is an XML schema developed by Booking.com. OTA cannot support all the functionality we want to offer, so we use B.XML to fill in the gaps.
• JSON - JSON stands for JavaScript Object Notation. Data is in name/value pairs, and is separated by commas. Curly braces hold objects and square brackets hold arrays. More fields and additional data will be added to the response structure as the API matures so it is advised for integrating clients to be receptive to these changes and not expect a strict schema.

All request bodies must use UTF-8 encoding.

Which format should I use?

In most cases, the answer is: both. Different endpoints accept different formats. Unless you plan to use only a few functions of the API, you will likely need to send requests in both OTA and B.XML.

Security

All requests to the API must use the HTTPS protocol (Hypertext Transfer Protocol [HTTP/1.1], over Transport Layer Security [TLS 1.2]. This ensures the proper encryption of machine account credentials.

Rate limiting

To prevent excessive load on our systems, we limit the number of API calls that a provider can make per minute before the API returns HTTP/1.1 429 Too Many Requests.

The table below lists the rate limits per endpoint at the time of writing. We strive to keep this information up-to-date, but do not guarantee that it always will be. Booking.com reserves the right to 1) change these limits at any time, without prior notice and 2) impose other limits on specific accounts.

Common header issues

This section details common misuse of headers when calling our API endpoints and how to solve it. The known cases of misuse are the following:

• Incorrect Host (name)
• Incorrect Content-Type
• Incorrect Accept-Encoding

Incorrect Host (name)

Misuse example

curl --location --request POST 'https://supply-xml.booking.com/hotels/xml/roomrates' \
--header 'Authorization: Basic TjLUphbnNzZW5zOihSKj9zRS5QbGVfX3hCUVZmZighgji9FUzJOcSpBWEtsb1lAcj8=' \
--header 'Host: supply2-xml.booking.com'
--header 'Content-Type: application/xml' \
--data-raw 
'<request>
  <hotel_id>6314570</hotel_id>
</request>
'

You can see that the Host header value is supply2-xml.booking.com, which is not the correct Host name when it comes to retrieving roomrates. The only correct Host header value for this scenario is https://supply-xml.booking.com.

Correct usage

You must always use either of the following host names:

• secure-supply-xml.booking.com : For consuming the endpoints related to the retrieval and confirmation of reservations.
• supply-xml.booking.com : For consuming all non-reservations endpoints.

Mismatched Content-Type

Misuse example

curl --location --request POST 'https://supply-xml.booking.com/hotels/xml/roomrates' \
--header 'Authorization: Basic TjLUphbnNzZW5zOihSKj9zRS5QbGVfX3hCUVZmZighgji9FUzJOcSpBWEtsb1lAcj8=' \
--header 'Host: https://supply-xml.booking.com'
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 
'<request>
  <hotel_id>6314570</hotel_id>
</request>
'

You can see that the Content-Type header value is application/x-www-form-urlencoded, which does not match the OTA standard XML used in the request body. The correct Content-Type in this situation is application/xml or text/xml.

Correct usage

You can use the following Content-Types:

• application/xml or text/xml: For the API endpoints that make use of OTA standard XML.
• application/x-www-form-urlencoded: For the API endpoints that make use of BXML standard XML.
• application/json: For the API endpoints that make use of JSON.
• text/csv: For the API endpoints that make use of CSV.

Incorrect Content-Encoding

Misuse example

curl --location --request POST 'https://supply-xml.booking.com/hotels/xml/roomrates' \
--header 'Authorization: Basic TjLUphbnNzZW5zOihSKj9zRS5QbGVfX3hCUVZmZighgji9FUzJOcSpBWEtsb1lAcj8=' \
--header 'Host: https://supply-xml.booking.com'
--header 'Content-Type: application/xml' \
--header 'Content-Encoding: UTF-8'
--data-raw 
'<request>
  <hotel_id>6314570</hotel_id>
</request>
'

You can see that the Content-Encoding value is UTF-8. This is not a valid encoding type.

Correct usage

You can only use the following encoding type, depending on the situation:

• gzip
• compress
• deflate
• br
• identity
• * : This is the default value, so when you do not add the header you express no preference for encoding.

Disclaimer

All information contained in this document is subject to the terms and conditions of your contractual agreement with Booking.com.