Best practices for Reservation API implementation

How to react to HTTP 500 errors

Sometimes a Booking.com API will return an HTTP status code 500, 502, or other 5XX. For the Reservation API, it is important to follow web protocol best practices, to ensure that all reservations are delivered even when there is a temporary system fault.

OTA API calls that confirm messages (OTA_HotelResNotifRS/OTA_HotelResModifyNotifRS) must be retried until a result other than HTTP 5XX is obtained. When Booking.com sends a result of 5XX for these requests, it means that the message is still pending delivery. If the message remains pending delivery for 30 min, then online delivery may be aborted and the message falls back to email delivery instead.

Processes that fetch new reservation data (B.XML reservations and OTA_HotelResNotifRQ/ HotelResModifyNotifRQ) should normally cover any available reservation within a few minutes. Therefore, the best error-handling strategy for HTTP 5XX is to do nothing special for it, because the next normal poll will serve as the retry. It is important to avoid retrying with zero delay, because such a retry is unlikely to succeed and it may unduly increase the server loads at Booking.com.

Do send acknowledge message to confirm message delivery

Always remember to send an acknowledge message after retrieving reservations.

An OTA acknowledge message confirms positively that the new information is visible within the online system used by the partner. If Booking.com does not receive the acknowledgement, then it is assumed that the partner is not receiving any update.

Use the OTA error facility and do not allow messages to time out

If a reservation fetched is inaccurate or unable to be processed, a rejection should be sent back rather than silently ignoring it, which will lead to fallback after it times out.

For more information, see "OTA_HotelResNotif Response".

Register planned maintenance downtime on the Portal

If reservations are not picked up and acknowledged after 30 minutes, fallbacks will be sent to properties. Hold is a feature which will prevent fallbacks being sent for the time period when it's turned on. Please plan maintenance at least 24 hours in advance and enter the schedule on the Provider Portal.

More information: Reservation holds
To place a hold: Company Settings

Use reservationssummary to import reservations for a newly onboarded property

Of all Reservation API facilities, only reservationssummary provides all currently booked reservations, including older ones which were confirmed before the property became connected.

The other API calls are limited to reservations created or modified in the last two weeks and booked after the property became connected.

Do not periodically query each single hotel_id

Querying all reservations using one hotel_id at a time is likely to create service interruptions for individual partners. We have found this practice to be associated with email fallbacks.

Do not use multiple hotel_ids per query (unless they are the same partner)

Similar to querying using a single hotel_id, using multiple hotel_ids will increase the chance of failing to pick up reservations in time. Furthermore, if any of the hotel_ids are not accessible to the machine account which is sending the request, there will be errors and it will affect points in the Preferred Programme.

It's acceptable to use this query style if the hotel_ids share a common operator or front desk.

Do not use last_changed (except in special cases)

Using the last_changed query parameter will increase the chance of not processing new reservations/sending acknowledgement in time, since the result usually contains a lot of data which is already processed.

Our API selects only messages that have not yet been delivered by default, so the last_changed query parameter is unnecessary.

An example of reasonable use of last_changed would be a server failure causing the loss of reservation data including the booking numbers (reservation IDs). But if the IDs are known, it is more reliable to provide them to the API instead of last_changed.

Typically, a connectivity provider should download and store reservation data, and then present it to the user. It is not necessary to refresh reservations with extra queries. Please report any doubts or concerns to connectivity@booking.com.

Always include a Hotel ID when querying a reservation ID

It is recommended that you provide a hotel ID with every reservation ID query. In the future this will become a requirement.

Prefer OTA protocol over B.XML

If possible, implement the OTA protocol as it offers more safeguards and more features.

Use OTA API hotel reservation response tokens and properly handle HTTP 409

The Reservation API offers the "OTA hotel reservation response token" or ota_res_response_token feature to improve reliability. It is found on the Feature Management page including an on/off switch and extensive documentation.

These tokens identify each confirmation message with specific reservation data from OTA_HotelResNotifRQ or OTA_HotelResModifyNotifRQ. If the data becomes outdated before it is confirmed, then the API responds to the confirmation with the HTTP status, 409 CONFLICT, and an error message,

Response token for hotel reservation does not match. Please pull again (error code 756)

At this point, confirmation is impossible, so the confirmation should not be retried. Instead, the reservation should be updated using a new OTA_HotelResModifyNotifRQ. A new confirmation should then be applied on the new data.

Assuming that OTA_HotelResModifyNotifRQ is retrieved frequently for all properties, the no special action is needed: Simply treat the HTTP 409 response the same as an HTTP 200. The next pull will retrieve another update. This simple implementation strategy does still benefit from the reliability added by the feature.

Use machine accounts to segment the user base

Using well-organized machine accounts not only prevents too many reservations sending to a single account, but also keeps partner accounts categorised and makes it easier for support to pin down errors if they occur.