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.
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.
If you are a developer working with the Booking.com Connectivity APIs for the first time, we recommend starting with the tutorial for creating a test property.
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.
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.
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.
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.
Do not mix formats
Because some of the API's functions overlap, you can sometimes choose whether to perform an operation with either an OTA or a B.XML request. For example, the process of creating and modifying reservations involves a sequence of requests that can be made in either format. When implementing such processes, we strongly recommend that you do not mix OTA and B.XML requests. Instead, use the same format for the entire process.
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.
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.
|API endpoint(s)||Max. calls per minute||Effective from|
|All endpoints||10000||2015-11-24 15:37:02|
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)¶
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
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.
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
You can use the following
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.
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.
You can only use the following encoding type, depending on the situation:
*: This is the default value, so when you do not add the header you express no preference for encoding.
All information contained in this document is subject to the terms and conditions of your contractual agreement with Booking.com.