In beta
This API endpoint is currently in a beta phase. You should direct any questions during the Beta phase to your Booking.com contact person via the appropriate channels.
Managing reservation recovery¶
This section describes how and in what situations you should recover missed reservations.
What are missed reservations?¶
A missed reservation happens when a reservation (reservation covers confirmations, modifications, and cancellations):
- Is not pulled within 30 minutes: You did not retrieve the reservations within the allotted time (BXML or OTA).
- Is not acknowledged within 30 minutes: You do not send an
OTA_HotelResNotifRS
response within the allotted time (OTA). - Is actively rejected: You send an
OTA_HotelResNotifRS
response with an<Error>
tag (OTA).
Therefore missed reservations are those that for whatever reason did not reach you through Booking.com's reservation delivery system.
Properties still receive emails when implementing this API
When Booking.com determines that a reservation was missed, the property in question receives an email (fallback). This email is similar to the notification used with properties without a Connectivity implementation.
Why use the Reservations Control API?¶
To manage missed reservations without implementing this API, you must either:
- Go to the Connectivity Portal and select Reports > Email Fallbacks.
- Read the fallback emails that Booking.com sends you.
Neither of these options are very reliable. However, the Reservation Control Flow API enables you to process the missed reservations data with better filtering, performance, and accessibility options:
- Ability to filter by check-in dates or time of communication failure.
- More up-to-date and accurate data, which enables you to improve your recovery and set up better follow-ups with your properties.
Retrieving missed reservations¶
GET https://supply-xml.booking.com/reservations-flow-control/missed-reservations
The GET /reservations-flow-control/missed-reservations
request enables you to retrieve missed reservations for all your properties.
Use cases¶
You can use this endpoint to retrieve missed reservations in two ways, depending on the problem you are facing:
-
Temporary outage or other issue: Filter by time of communication failure by using the
from
anduntil
parameters. After retrieving missed reservations, you must use thereservation_id
from the response and set it to theid
parameter in Reservations API to retry retrieving the complete reservation data. -
Issue with reservations integration with check-in dates approaching: Filter by check-in date by using the
check_in_start
andcheck_in_end
parameters. After retrieving missed reservations, you must use thecheckin
data from the response to alert the affected properties about incoming reservations.
After you processed the missed reservations in your system, you must send an acknowledgement for those reservations so that Booking.com's records are updated as well.
You must use query parameters
Keep in mind that you must either include the check_in_start
and check_in_end
parameters, or the from
and until
parameters.
Query parameters¶
You can use the following query parameters to further specify your search.
Element | Description | Type | Required/Optional | Notes |
---|---|---|---|---|
check_in_start |
Specifies the beginning of the check-in date range. | string | optional | You can use this element to search by check-in date range. Follows YYYY-MM-DD . |
check_in_end |
Specifies the end of the check-in date range. | string | optional | You can use this element to search by check-in date range. Follows YYYY-MM-DD . |
from |
Specifies the beginning of a time range. | string | optional | You can use this to search by time range. Refers to the deadline time when the data was "missed." Follows YYYY-MM-DDThh:mm:ss.mmmZ . |
until |
Specifies the end of a time range. | string | optional | You can use this to search by time range. Refers to the deadline time when the data was "missed." Follows YYYY-MM-DDThh:mm:ss.mmmZ . |
property_id |
Specifies the id(s) of the property or properties you want to retrieve missed reservations for. | array of integers | optional | |
limit |
Specifies the maximum amount of missed reservations you want to retrieve per page. | integer | optional | Default value is 50 . |
page_size |
Specifies the maximum amount of missed reservations you want to retrieve per page. | integer | optional | Default: 50 |
reference_type |
Specifies the reservation type you want to retrieve . | string | optional | Possible values are confirmation , modification , and cancellation . |
reservation_id |
Specifies the reservation id(s) you want to retrieve. | array of integers | optional |
Response body example¶
The following is a successful response body example:
{
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9YRXJVNGNM1xbxtwnkx4JfLwqoVPj5OwWtLL9q85pKPTygsQdDURy+bKKasj8aIE0NywVyfhzO//gz+7SN3iJ3fvtl42zpRAM07lJkM5eGptxRJuG37Hnw2E=",
"next_page": "https://supply-xml.booking.com/reservations-flow-control/missed-reservations?from=2021-02-28T00%3A00%3A00Z&until=2021-03-01T00%3A00%3A00Z&cursor=UkoAAAB5AAAAAukR2OW61c_uJ9bquslb7jw6OxsHqLDPUihBfY70-YKXTl_zrFXhaiIT8jGeqsmdsGY3ReGvm0QWpaUBw-o4GT0qpg"
},
"errors": [],
"data": [
{
"reference_timestamp": "2021-02-28T00:00:51Z",
"uri": "https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResModifyNotif?id=3307795069&hotel_id=283442",
"hotel_id": 283442,
"reservation_id": 3307795069,
"reason": "Invalid Credit Card Number",
"failure_type": "refused",
"checkin": "2021-02-28",
"reference_type": "cancellation"
},
{
"reference_type": "cancellation",
"checkin": "2021-02-27",
"reason": "Reservation not found",
"failure_type": "refused",
"reservation_id": 2642335616,
"hotel_id": 29889,
"uri": "https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResModifyNotif?id=2642335616&hotel_id=29889",
"reference_timestamp": "2021-02-28T00:07:09Z"
},
{
"checkin": "2021-03-05",
"reference_type": "cancellation",
"reservation_id": 3154229230,
"hotel_id": 78173,
"failure_type": "missed_reservation",
"reason": null,
"reference_timestamp": "2021-02-28T00:10:30Z",
"uri": "https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResModifyNotif?id=3154229230&hotel_id=78173"
}
],
"warnings": []
Response body elements¶
The following table describes the response elements:
Element | Description | Type | Notes |
---|---|---|---|
data |
Contains the response object. | object | |
> checkin |
Specifies the check-in date. | string | |
> failure_type |
Specifies the type of failure. | enum | Possible values are missed_deadline , missed_reservation , refused , or missed_confirmation . |
> hotel_id |
Specifies the id of the property. | integer | |
> reason |
Specifies the reason for the missed reservation. | string | This is a copy of the the ShortText attribute content within the <Error> element in your acknowledgement feedback. |
> reference_timestamp |
Specifies the time when the reservation reference was sent. | string | Follows YYYY-MM-DDThh:mm:ss.mmmZ . |
> reference_type |
Specifies the reservation type you retrieved. | string | |
> reservation_id |
Specifies the id of the reservation. | integer | |
> uri |
Specifies the link to the full reservation object. | string | This link refers to the OTA endpoint of the Reservations API. |
meta |
Contains the meta data that comes with the response. | object | |
> next_page |
Specifies the URL with the next page of results. | string | |
> ruid |
Specifies the unique id of the request. | string | You can send this id to Booking.com customer support if you run into an issue. This can help to understand what went wrong. |
warnings |
Contains potential warnings. These can help you improve your requests. | array | |
errors |
Contains potential errors. These can help you understand what went wrong with your request. | array |