How can I implement the Rates & Availability API and Reservations API?

Getting started with our APIs

This guide is designed to speed up and reduce friction during your onboarding process. The topics covered here can help facilitate discussions with your teams, and support you in making design and implementation decisions. 

All relevant endpoints for the Rates & Availability API and Reservations API currently use XML. Some other Connectivity API endpoints that might become interesting for you at a later stage use JSON.

Our XML APIs are currently available in two standards:

• OTA – following the OTA API standard with Booking.com-specific customisations
• BXML – internal Booking.com API standard

Not all endpoints are available in both standards. We recommend developing against our OTA endpoints where available. You can read our latest API documentation here.

 

Errors and warnings

Our APIs follow the HTTP status codes and return the applicable status, as well as a message and RUID, for every API request. API responses can confirm the successful integration of an API request, or they can also include errors or warnings.

If a warning is returned, the corresponding API request has been integrated. The corresponding warning message gives more details about the potential issue.

There are possible behaviours around errors depending on the returned status code:

• 200 – the corresponding API request has only been partially integrated due to an issue with the request. The error message gives further details about the issue and clarifies which elements of the request caused the error and therefore weren’t integrated. You’ll need to resolve the reported issue before sending another API request.
• 4xx – the corresponding API request hasn’t been integrated due to an issue with the request. The error message gives more details about the issue. You’ll need to resolve the reported issue before sending another API request.
• 5xx – the corresponding API request hasn’t been integrated due to an issue on the Booking.com side. The error message gives further details about the issue. You’ll need to wait at least one minute and then resend the same API request.

Many API errors are caused by incorrect or outdated property mappings. We recommend closely monitoring any API errors and implementing measures to prevent them as much as possible. If you need assistance handling and preventing API errors, please contact our Connectivity Support team.

 

RUIDs

All of our API endpoints return unique base64-encoded strings with every API response. These so-called RUIDs are returned with the message header and at the end of the message body. The RUIDs are used to identify individual requests and are crucial to help our Connectivity Support team perform effective troubleshooting.

RUIDs and corresponding API request logs are stored on our platform for 90 days. You’re required to store RUIDs and logs on your system for a minimum of 30 days, but we recommend that you store them for 90 days as well.

Keep in mind that our Connectivity Support team might not be able to help you with certain troubleshooting requests if you can’t provide a valid RUID.

 

API features

There are several API features that allow you to change the API behaviour to make sure that the responses returned by our system can be easily processed on your side. Most of the features change the way the reservations are returned and add more detailed information on the reservation. An example of this is the exact number of adults and children or a list of all applicable taxes and fees. Features can be activated or deactivated on the Booking.com Provider Portal.

 

Connecting and mapping a new property

Once a property has requested an API connection with your account, you can retrieve information about the property to map it on your system.

These endpoints are used for mapping (currently only available in the BXML standard):

• rooms – returns a list of room names and room IDs
• rates – returns a list of rate names and rate IDs
• roomrates – returns a list of active room/rate combinations, including room and rate IDs and the cancellation policy
• roomrateavailability – returns currently loaded rates, availabilities and restrictions
• reservationssummary – returns basic details of active reservations

 

Rates & Availability API requirements

Functionalities

Properties listed on our platform can have multiple rooms and rate plans. Each room/rate combination can be activated and configured individually. Cancellation policies and meal plans, as well as any restrictions, are set on room/rate level.

The number of rooms to sell is set on room level, while prices and restrictions are set per room/rate combination. That means it’s not possible to set the number of rooms to sell on room/rate level or to set prices or restrictions on room level.

For a seamless API integration and the best experience for our mutual property partners, the following functionalities are mandatory:

• Multiple rooms – your system supports a multi-room setup and can push rate and availability information (number of rooms to sell per date) for multiple rooms.
• Multiple rates – your system supports a multi-rate setup and can push rates and availability information (prices and restrictions per date) for multiple rate plans per room.
• Single use – your system sends the price for the maximum occupancy of a room/rate, as well as the price for the single use of that room/rate. Single use doesn’t apply to rooms with a maximum occupancy of one person.
• Restrictions – we recommend that you implement all restrictions that are available on your system. All the available restrictions on Booking.com are listed below.

 

Restrictions (items marked with * are mandatory)

• Minimum stay arrival – a reservation with this restriction on the check-in date must include at least the minimum number of nights configured. This restriction only applies to the arrival date.
• Minimum stay through* – a reservation with this restriction must include at least the minimum number of nights configured. This restriction counts for all nights of the reservation. If different values are configured for different nights of the reservation, the strictest restriction applies.
• Maximum stay arrival – a reservation with this restriction on the check-in date can’t exceed the maximum number of nights configured. This restriction only applies to the arrival date.
• Maximum stay through – a reservation with this restriction can’t exceed the maximum number of nights configured. This restriction applies to all nights of the reservation. If different values are configured for different nights of the reservation, the strictest restriction applies.
• Exact stay – a reservation with this restriction must meet at the exact number of nights configured. This restriction applies to all nights of the reservation. If different values are configured for different nights, then a reservation for that period isn’t possible.
• Closed* – if this restriction is active for a given date, reservations can’t be created for that date.
• Closed on arrival* – if this restriction is active for a given date, reservations arriving on that date can’t be created.
• Closed on departure – if this restriction is active for a given date, reservations leaving on that date can’t be created.
• Minimum advance reservation – a reservation with this restriction can only be made until a pre-configured number of hours or days before the arrival date, and not after. This restriction counts back from midnight on the arrival date.
• Maximum advance reservation – a reservation with this restriction can only be made from a pre-configured number of hours or days before the arrival date, and not before. This restriction counts back from midnight on the arrival date.

 

API implementation

We recommend developing against the OTA_HotelAvailNotif endpoint for number of rooms to sell and restrictions, and against OTA_HotelRateAmountNotif for prices.

Our system supports delta updates. We recommend sending a full update of rates and availability information when the property is first connected to your system. Any subsequent updates only need to include changes to the loaded values. It’s not necessary to send a full refresh with every change. If you want to send a full refresh of rates and availability information to eliminate any potential discrepancies, please don’t run the full refresh more than once a week.

We strongly recommend sending updates on date ranges instead of on individual dates. Your system needs to support date ranges of at least one month. This means an update that sets the same price for a range of three months can be split up into a maximum of three date ranges of one month each.

Our backend is built to handle a steady high load of API requests. However, we can’t always guarantee that API requests are processed in the same order you send them. As a result, you might receive the responses to requests in a different order than they were sent. For this reason, if you receive contradictory updates – for example fast changes to a price – please wait at least one minute before sending any contradicting requests. This ensures that any queued changes take place before follow-up requests.

 

Reservations API requirements

Functionalities

Travellers can make reservations on our platform for several nights and for multiple rooms. Information in various languages can be included on a XML reservation message.

For a seamless API integration and the best experience for our mutual property partners, the following functionalities are mandatory:

• Multiple dates – your system supports reservations made for more than one night.
• Multiple rooms – your system supports reservations made for more than one room.
• Multiple rates – your system supports reservations made using different rate plans.
• Modifications and cancellations – your system can handle modifications and cancellations of existing reservations, and it updates these accordingly.
• UTF-8 characters – your system supports reservation information in various languages and alphabets, such as Cyrillic, Chinese, Japanese and Arabic.
• Reservation details – all the information that must be visible on your system is listed below.

 

Reservation details

The information included on the XML reservation message is roughly the same as shown on the ‘Reservations’ page in the Booking.com extranet, but there are a few differences between the two. The XML reservation includes room IDs and rate IDs, but these are not explicitly shown in the extranet. Some elements are also dependent on your account setup. This means they might be returned differently or not at all on the XML reservation.

The following reservation details are mandatory. Your system needs to show these to the user:

• Booking.com reservation ID
• Reservation status
• Time stamps of reservation creation and latest change
• Booker details: name, alias email address, phone number, Genius status
• Guest names
• Number of guests, and a breakdown by number of adults and children
• Room name and ID
• Rate name and ID, including meal plan and cancellation policy
• Promotions applied
• Rate-rewriting
• Add-ons booked by the guest
• Check-in and check-out date
• Price per room night
• Additional taxes and fees
• Total price including all taxes and fees
• Smoking preference
• Additional information and special requests made by the guest
• Credit card data (in a PCI-compliant format)

 

API implementation

We recommend developing against the OTA_HotelResNotif endpoint for new reservations, and against OTA_HotelResModifyNotif for modifications and cancellations.

Reservations are available to be picked up and confirmed via the API for up to 30 minutes after they’re made. However, we recommend retrieving reservations, modifications and cancellations at least every 30 seconds. This helps prevent any inventory discrepancies and potential overbookings.

Reservations can be retrieved globally with a machine account that is assigned to all connected properties. You can do this without defining any property IDs on the reservation retrieval request. This setup returns new reservations for all properties in a scalable way.

In some cases, you might receive a modification or cancellation for a reservation that was not integrated as a new reservation before. This can happen if a reservation is modified or cancelled within seconds after its creation, or if the new reservation was made before the property had an API connection with your system.

Reservations on our platform can be modified or cancelled after the check-in date has passed. Examples are if a guest changes their stay while they’re already staying at the hotel, or if a guest doesn’t show up and the hotel cancels the reservation as a no-show. Please make sure these modifications and cancellations are integrated on your system.

 

Auto-replenishment

Our platform applies a feature called auto-replenishment to all cancelled and partially cancelled reservations. This feature automatically adds the inventory of any cancelled room nights on top of the loaded inventory. This behaviour helps properties to resell room nights that have been booked and later cancelled. Auto-replenishment can’t be disabled, so your system is always required to be able to handle it and to mirror the behaviour of Booking.com.