Migrating to new versions¶
At Booking.com, we want to continuously improve the Connectivity Partner experience. This means we try to build better products and deprecate the older versions. When Booking.com plans to deprecate a feature or a product, you can no longer use it after the communicated date of deprecation. To help facilitate the potential changes you must make, the migration guide tables on this page aim to help you understand what is deprecated and what its (improved) alternative is.
Changes to the roomrates endpoint¶
We plan to roll out the improvements made to the B.XML roomrates
endpoint as a new version, v1.1.
The changes outlined in this section are applicable only when using the B.XML roomrates
endpoint with a special header parameter.
For a detailed explanation of the v1.0 B.XML roomrates
endpoint, see Retrieving active roomrates.
With the v1.1 B.XML roomrates endpoint, you can:
- Query roomrate details with or without rewritten rate details.
- Retrieve additional response details like flexible children prices, if they are set.
- See improved latency.
Also, in version v1.1:
- The endpoint returns all responses within the
roomrates
object. - The endpoint doesn't return the
max_children
attribute anymore. - The endpoint doesn't return the redundant
follows_room_rate_properties
attribute in the response while retrieving roomrates with rate relations.
Header parameter¶
Header | Description | Type | Required/ Optional |
Notes |
---|---|---|---|---|
Accept-Version |
Specify the version number to get the API functionality specific to that version. | string | optional | Supports the following values: - 1.1: New version. - 1.0: Previous version. |
Sample header¶
POST 'https://supply-xml.booking.com/hotels/xml/roomrates' \
--header 'Accept-Version: 1.1' \
--header 'Authorization: Basic THVjLVNhbXVlbMblhWTdlOCghQ29qaU9pNmxlWSpIWXU9OigvS2meQpQ12puj' \
--header 'Content-Type: application/xml'
Additional body parameter¶
The following table includes a body parameter in addition to parameters supported in roomrates v1.0:
Element | Description | Type | Required/Optional | Notes |
---|---|---|---|---|
> support_rate_rewrite |
Specifies whether the API should include rewritten rate details. | boolean | optional | Possible value: - 0 : Include all rates including rewritten rate plan details. - 1 : Do not include rewritten rate plan details. |
Sample request¶
<request>
<hotel_id>123456</hotel_id>
<support_rate_rewrite>0</support_rate_rewrite>
<policy_override_start_date>2023-02-26</policy_override_start_date>
<policy_override_end_date>2023-03-30</policy_override_end_date>
</request>
Response details¶
The endpoint returns the following flexible child rate details (if they are already defined) in addition to the details returned by roomrates v1.0.
Element | Attribute | Description | Type | Notes |
---|---|---|---|---|
roomrates |
Contains the room objects. |
object | ||
>>>> additional_guests |
Contains the price elements for children. |
array | ||
>>>>> price |
Contains the children pricing details. | object | ||
type |
Specifies that the prices are for children. | string | ||
additional_guest_number |
Specifies the order of prices within the same age bucket. | integer | For example: Price for 1 (first child) is 5000, while price for 2 (second child) is 2500, and 3 (third child) is free (0 ). Default value is 0 , meaning all prices are the same for children in the specified age bucket. |
|
age_bucket_id |
Specifies the ID of the property-level age bucket. | integer | ||
from_age |
Specifies the beginning of an age range. | integer | ||
to_age |
Specifies the end of an age range and is inclusive. | integer | ||
additional |
Specifies the fixed price for a child within a certain age bucket. | integer | ||
percentage |
Specifies the price for the child as a percentage of the adult price. | integer | Possible value between 0 and 100 . |
Sample response¶
<roomrates>
<room id="813518802" hotel_id="8135188" hotel_name="Deluxe HillTop Suites" max_children="0" room_name="Classic Quadruple Room">
<rates>
<rate id="25337348" fixed_occupancy="2" max_persons="5" policy="General" policy_id="343709190" rate_name="summer time rates">
<meal_plan meal_plan_code="19"/>
<policies>
<booking_rules>
<booking_rule max_advanced_booking_offset="P14D"/>
<booking_rule min_advanced_booking_offset="P1D"/>
</booking_rules>
<cancel_policy>
<cancel_penalty policy_code="43"/>
</cancel_policy>
<guarantee_payment_policy>
<guarantee_payment policy_code="166" effective_from="after_reservation_is_made" required="1"/>
</guarantee_payment_policy>
</policies>
<pricing type="OBP">
<additional_guests>
<price type="child" additional_guest_number="0" from_age="0" to_age="5" age_bucket_id="1" additional="0"/>
<price type="child" additional_guest_number="0" from_age="6" to_age="10" age_bucket_id="2" additional="40"/>
<price type="child" additional_guest_number="0" from_age="11" to_age="12" age_bucket_id="3" additional="60"/>
</additional_guests>
</pricing>
</rate>
</rates>
</room>
</roomrates>
Changes to the availability endpoint¶
We plan to roll out the improvements made to the B.XML availability
endpoint by March 22, 2023.
The changes outlined in this section are applicable only when using the B.XML availability
endpoint with a special header parameter.
The following section covers only the changes available in v1.1.
For a detailed explanation of the B.XML availability
endpoint, see Create or update inventory, restrictions.
When migrating to the v1.1 B.XML availability
endpoint, you get:
- Improved error handling and error description.
- Improved latency.
Header parameter¶
Header | Description | Type | Required/ Optional |
Notes |
---|---|---|---|---|
Accept-Version |
Specify the version number to get the API functionality specific to that version. | string | optional | Supports the following values: - 1.1: New version. - 1.0: Previous version. |
Sample header¶
POST 'https://supply-xml.booking.com/hotels/xml/availability' \
--header 'Accept-Version: 1.1' \
--header 'Authorization: Basic THVjLVNhbXVlbMblhWTdlOCghQ29qaU9pNmxlWSpIWXU9OigvS2meQpQ12puj' \
--header 'Content-Type: application/xml'
HTTP error code behaviour on v1.1¶
With the v1.1 of the B.XML availability
endpoint, we have standardised the treatment of HTTP error codes.
The following table captures all the common conditions and the HTTP error codes that the v1.1 endpoint returns.
If the endpoint encounters | The endpoint returns |
---|---|
Incorrect username or password. | HTTP 401 |
Schema validations such as invalid integer, date. | HTTP 400 |
All updates with errors. | HTTP 400 |
At least one successful update. | HTTP 200 in addition to errors or warnings, if any. |
All updates are unauthorized. | HTTP 403 |
INTERNAL_SERVER_ERROR. | HTTP 500 |
Changes to existing error messages¶
The following table lists only the error codes that have changed for the B.XML availability
endpoint.
Old error code (v1.0) | Error message | New error code (v1.1) | Error message | Notes |
---|---|---|---|---|
NO_HOTEL_FOUND_FOR_ROOMS | No hotel found for provided room IDs. | ROOM_ID_INVALID | Room ID '%s' is not valid | Incorrect room ID. Make sure to retrieve the correct Room ID using the rooms endpoint. |
ROOM_DOES_NOT_EXIST | Room does not exist. | ROOM_ID_INVALID | Room ID '%s' is not valid | Provide a valid Room ID. Make sure to retrieve the correct Room ID using the rooms endpoint. |
ROOM_NOT_ACTIVE | Room is not active. | ROOM_ID_INVALID | Room ID '%s' is not valid | Provide a valid Room ID. Make sure to retrieve the correct Room ID using the rooms endpoint. |
DATES_TOO_FAR_OR_INVALID | Some of the date(s) for RoomID %s are too much into the future or invalid (e.g. %s) | NOT_A_VALID_DATE | Dates should be in YYYY-MM-DD format, not before '%s',and not be past $y'. The data should also be valid | Avoid providing dates that are too far in the future. |
AVAILABILITY_UPDATE_DISABLE_ HOTEL_SWITCHING_CURRENCY |
Updating availability is temporarily disable for the hotel. Currency switch is in progress. | CURRENCY_SWITCH_IN_PROGRESS | There is a hotel currency switch currently in progress | Try to run the request after the currency switch is in place. |
DATE_ELEMENT_ATTRIBUTE_NOT_SET | Neither from/to nor value attribute has been set. | DATE_ELEMENT_MISSING | Date is missing | A valid date is required for the request. |
FROM_OR_TO_DATE_INVALID | From or To date is invalid. |
DATE_ELEMENT_MISSING | Date is missing | A valid date is required for the request. |
TAG_NOT_ALLOWED | Tag not allowed inside date block when using room level inventory with no rate. | RATE_ID_REQUIRED | Rate Id is required | Rate ID is required for the request. |
OBP_PRICING_PASSED_FOR_ LOS_RATE, OBP_PRICING_PASSED_FOR_ RLO_RATE, OBP_PRICING_PASSED_FOR_ DEFAULT_RATE, OBP_PRICING_PASSED_FOR_ SINGLE_USE_RATE |
OBP_PRICING_PASSED_FOR_ RLO_RATE, OBP_PRICING_PASSED_FOR_ DEFAULT_RATE. Rest are considered valid. |
New warning on v1.1¶
New error code | Error message | Notes |
---|---|---|
WARN_UNPROCESSED_ADDITIONAL_GUEST | Additional guest updates weren't processed. Please try again later. |
New error codes on v1.1¶
The following table summarises the new error codes for the B.XML availability
endpoint.
Error code | Error message | Notes |
---|---|---|
ROOM_ID_MISSING | Room ID is missing | Room ID is required for the request. |
ROOM_ELEMENT_REQUIRED | Room is missing | The request contains an empty request body. |
FROM_DATE_SHOULD_BE_LESS_THAN_TO_DATE | From date should be less than or equal To Date | The From date should be less than or equal to the To date. |
LOS_PRICING_PASSED_FOR_OBP_RATE | LOS pricing format sent for OBP room-rate | The request contains pricing information in LOS pricing format. However, the property is set to OBP pricing type. |
LOS_PRICING_PASSED_FOR_DEFAULT_RATE | LOS pricing format sent for Standard room-rate | The request contains pricing information in LOS pricing format. However, the property is set to Standard pricing type. |
OBP_PRICING_PASSED_FOR_DEFAULT_RATE | OBP format sent for Standard room-rate | The request contains pricing information in OBP pricing format. However, the property is set to Standard pricing type. |
CANT_SET_PERCENTAGE_FOR_OBP_LOS | Cannot set percentage for OBP/LOS room-rate | The request is trying to send percentage pricing for Flexible Children Rates (FCR) while the roomrate is on OBP or LOS pricing mode. This is not accepted. You can set a fixed amount FCR in case the roomrate is on OBP or LOS pricing model. |
ADDITIONAL_PRICE_TYPE_CAN_BE_CHILDREN_ONLY | Additional guest type can only be child | For the Type attribute of <additional_guest> element, the only supported value is child . |
INVALID_CURRENCY_CODE | Supplied currency code '%s' doesn't match the hotel's currency code '%s' for room ID '%s' and rate ID '%s' | Currency code in the request should match the property's currency code. |
INVALID_USE_OF_SINGLE_OCCUPANCY | Cannot set price for occupancy 1. Please check the room-rate pricing model | Cannot set pricing for single occupancy as the pricing type of the property or roomrate is other than Standard . |
RATE_EDITABLE_ONLY_ON_EXTRANET | Rate '%s' is only editable on Extranet | You are not allowed to edit the rate via the connectivity API. The property can edit the rate via the Booking.com extranet. |
ROOM_EDITABLE_ONLY_ON_EXTRANET | Room '%s' is only editable on Extranet | You are not allowed to edit the room via the connectivity API. The property can edit the room via Booking.com extranet. |
RATE_NOT_ACTIVE_FOR_ROOM | Rate '%s' is not active for room '%s' | Rate is not activated for the selected room. Please check allowed roomrates using the roomrates endpoint. |
HOTEL_ACCESS_DENIED | Request for forbidden hotel id(s) | Check the property ID and either provide the correct property ID or make sure the machine account credentials have enough permissions. |
NOT_A_VALID_OCCUPANCY | An occupancy may not be zero, Occupancy '%s' may not be negative, Occupancy '%s' exceeds maximum value $MAX, Occupancy '%s' does not look numeric | Make sure to send pricing information for the correct occupancy level defined in the roomrate for the specific roomtype. |
NOT_A_VALID_DATE | INVALID_DATE | The supplied date format is invalid. The valid format is yyyy-mm-dd . |
PRICE_EXCEEDS_MAX_PRICE | You are setting ‘$price’ for room ID ‘%room_id’, rate ID ‘%rate_id’ and date ‘%date’ which exceeds the maximum allowed price of ‘%max_price’ | You are setting the price for the combination of room, rate and date that exceeds the maximum price set. |
PRICE_BELOW_MIN_PRICE | You are setting ‘$price’ for room ID ‘%room_id’, rate ID ‘%rate_id’ and date ‘%date’ which is below the minimum allowed price of ‘%min_price’ | You are setting the price for the combination of room, rate and date that goes below the minimum price set. |
NOT_A_VALID_RELEASE_TIME | Release times should be in the expected format. This is not the case for room ID $room_id, rate ID $rate_id on date '$date' | Make sure to specify the release time in the expected format. |
TYPE_VIOLATION | Generic error when provided data type is different than specified. | |
HOTEL_HAS_MISCONFIGURED_UFI | The timezone value is missing for the Ufi associated with hotel ID $hotel_id | Check the property's UFI configuration. |
INVALID_GUEST_AGE_BAND | Please define a to and from ages that match an age bucket | This error is related to configurations set for flexible children rates. See also, managing flexible children rates. |
INVALID_GUEST_AGE_BAND_ID | Please define an existing age bucket ID | This error is related to configurations set for flexible children rates. See also, managing flexible children rates. |
INVALID_ADDITIONAL_PRICES | Prices length cannot be 0 | This error is related to configurations set for flexible children rates. See also, managing flexible children rates. |
ADDITIONAL_GUEST_PRICE_DATES_OVERLAP | The dates of the guest prices cannot overlap for the same roomId and rateId | This error is related to configurations set for flexible children rates. See also, managing flexible children rates. |
INVALID_GUEST_AGE_BAND_ID | ageBandId must be 1, 2 or 3 | This error is related to configurations set for flexible children rates. See also, managing flexible children rates. |
PROVIDED_DATES_OUTSIDE_ALLOWED_RANGE | Please check if date is not in the past or more than 4 years in the future | This error is related to configurations set for flexible children rates. See also, managing flexible children rates. |
INVALID_ADDITIONAL_GUEST_NUMBER | Invalid additionalGuestNumber. It should be a non negative number up to + MAX_GUEST_NUMBER | This error is related to configurations set for flexible children rates. See also, managing flexible children rates. |
PRICE_LESS_THAN_0 | There's no support for negative prices | Make sure to specify a price greater than 0. This error is related to configurations set for flexible children rates. See also, managing flexible children rates. |
PRICE_GREATER_THAN_10_DIGITS | Max Price Value is + MAX_PRICE | This error is related to configurations set for flexible children rates. See also, managing flexible children rates. |
PRICE_PERCENTAGE_IS_BIGGER_THAN_100 | Percentage should be between [0.0, 100.0] | This error is related to configurations set for flexible children rates. See also, managing flexible children rates. |
PRICE_PERCENTAGE_IS_ZERO | There's no support for percentage price zero | This error is related to configurations set for flexible children rates. See also, managing flexible children rates. |
Changes to MaxChildOccupancy attribute usage¶
We plan to change the way you can specify child occupancy settings for a room type or a unit using the OTA_HotelInvNotif
endpoint from 20 March 2023.
This section captures the changes to the functionality for existing providers using the MaxChildOccupancy
attribute within the OTA_HotelInvNotif
endpoint and for new implementations.
Currently, the OTA_HotelInvNotif
endpoint has three fields related to occupancy:
MaxOccupancy
: Specifies the maximum number of guests that can physically fit in the room.MaxAdultOccupancy
: Specifies the maximum number of adults that can physically fit in the room.MaxChildOccupancy
: Specifies the maximum number of children that are eligible for the children rate.
We plan to introduce an additional attribute MaxChildPayableOccupancy
under TPA_Extensions
to capture the number of children that are eligible for the children rate.
Starting March 20, the value in the MaxChildOccupancy
attribute no longer reflects the eligibility for children rates and instead specifies the physical child occupancy limit of the room type or unit.
Changes to existing implementations¶
The following changes are expected from March 20, 2023, for providers who are already using the MaxChildOccupancy
attribute:
MaxChildOccupancy
: Specifies the maximum number of children that can physically fit in the room. There is no longer a limit of 4 children per room type/unit. However, the maximum number of children must be less than theMaxOccupancy
value. This does not specify the number of children eligible for the children rate.
We will use the existing value as the maximum child occupancy limit.MaxChildPayableOccupancy
: Specifies the maximum number of children that are eligible for the children rate. Additional children are charged as adults.
We will copy the existing value ofMaxChildOccupancy
attribute to theMaxChildPayableOccupancy
attribute. If you have implemented child rates, by copying the value, we can retain the value of children eligible for the child rate.
New implementations¶
For all new implementations, the following behaviour is expected from March 20, 2023:
MaxChildOccupancy
: Specifies the maximum number of children that can physically fit in the room. There is no longer a limit of 4 children per room type/unit. However, the maximum number of children must be less than theMaxOccupancy
value.MaxChildPayableOccupancy
: Specifies the maximum number of children that are eligible for the children rate. Additional children are charged as adults.
If you do not specify a value, the default value is set to 0 unless this value is updated in the extranet.
For more information on OTA_HotelInvNotif
endpoint, see Managing room types.
Using the OTA HotelDescriptiveInfo endpoint to retrieve property details
In line with the planned changes to OTA_HotelInvNotif
endpoint, when retrieving property details using the OTA HotelDescriptiveInfo
endpoint, the value in the MaxChildOccupancy
attribute reflects the maximum number of children that can physically fit in the room.
Examples¶
The following section shows code snippets that specify the maximum occupancy and the number of children eligible for child rates using both the existing and new implementation.
Existing behaviour¶
The following code snippet sets the maximum number of children eligible for child rates to 2.
<OTA_HotelInvNotifRQ>
<SellableProducts HotelCode="6314570">
<SellableProduct InvNotifType="Overlay" InvCode="631457019">
<GuestRoom>
<Occupancy MaxOccupancy="6" MaxAdultOccupancy="3" MaxChildOccupancy="2"/>
<Room RoomID="12345" />
<Description>
<Text>Apartment with Garden View</Text>
</Description>
</GuestRoom>
</SellableProduct>
</SellableProducts>
</OTA_HotelInvNotifRQ>
New behaviour¶
The following code snippet sets the maximum number of children that can physically fit in the room type to 3 and the maximum number of children eligible for child rates to 2.
<OTA_HotelInvNotifRQ>
<SellableProducts HotelCode="6314570">
<SellableProduct InvNotifType="Overlay" InvCode="631457019">
<GuestRoom>
<Occupancy MaxOccupancy="6" MaxAdultOccupancy="3" MaxChildOccupancy="3" />
<TPA_Extensions>
<Occupancy MaxChildPayableOccupancy="2" />
</TPA_Extensions>
<Room RoomID="12345" />
<Description>
<Text>Apartment with Garden View</Text>
</Description>
</GuestRoom>
</SellableProduct>
</SellableProducts>
</OTA_HotelInvNotifRQ>
Changes to roomrateavailability endpoint¶
We plan to roll out the improvements made to the roomrateavailability
endpoint soon.
The changes outlined in this section are applicable only when you use the test endpoint provided by your Connectivity account manager. This section covers only the changes based on the test endpoint. You can refer to the Rates & Availability documentation to know more about the existing functionalities.
Changes to the roomrateavailability
endpoint¶
This section captures the latest changes to roomrateavailability
available on the test endpoint.
For a detailed explanation of the existing endpoint, see Retrieving rate and inventory details.
Test Endpoint¶
POST
https://supply-xml.booking.com/v1-beta/hotel/roomrateavailability
What changed? | Old behaviour | New behaviour | Notes |
---|---|---|---|
Data type change for price and price1 |
integer |
double |
|
The number of rows returned when number_of_days is specified |
Returns (number_of_days + 1) rows. | Returns number_of_days rows starting from the date specified in start_date (including). |
If the start_date is not provided, then the API returns inventory information from the next day of the request till the number_of_days value. |
For example, if you specify number_of_days as 2, the API returns 3 rows starting from the date provided in the start_date . |
For example, if you specify number_of_days as 2, the API returns 2 rows starting from the date provided in the start_date . |
Request example¶
<request>
<hotel_id>8011855</hotel_id>
<room_id>801185502</room_id>
<start_date>2022-11-02</start_date>
<number_of_days>2</number_of_days>
</request>
[Old behaviour] Response example¶
<result>
<roomrate booked="2" cancelled="0" closed="0" date="2022-11-02" min_contracted_rooms="0" min_contracted_rooms_until="0" rate_id="25279855" room_id="801185502" rooms_to_sell="8"/>
<roomrate booked="2" cancelled="0" closed="0" date="2022-11-03" min_contracted_rooms="0" min_contracted_rooms_until="0" rate_id="25279855" room_id="801185502" rooms_to_sell="8"/>
<roomrate booked="2" cancelled="0" closed="0" date="2022-11-04" min_contracted_rooms="0" min_contracted_rooms_until="0" rate_id="25279855" room_id="801185502" rooms_to_sell="8"/>
</result>
[New behaviour] Response example¶
<result>
<roomrate booked="2" cancelled="0" closed="0" date="2022-11-02" min_contracted_rooms="0" min_contracted_rooms_until="0" rate_id="25279855" room_id="801185502" rooms_to_sell="8"/>
<roomrate booked="2" cancelled="0" closed="0" date="2022-11-03" min_contracted_rooms="0" min_contracted_rooms_until="0" rate_id="25279855" room_id="801185502" rooms_to_sell="8"/>
</result>
Licences¶
We plan to deprecate the old Licences API features on February 15, 2022. You can find the features we plan to deprecate next to their alternatives:
Deprecating CAPI feature | New solution or alternative |
---|---|
Retrieving licence requirements using the licenses/check_requirements endpoint] or the static licences table. |
Retrieving the up-to-date licence requirements using the licenses/rules/properties/{property_id} endpoint. Depending on the region of your properties, those requirements differ. |
Sending licence information with the LicenseInfos element using the /ota/OTA_HotelDescriptiveContentNotif and [/ota/OTA_HotelInvNotif][creating-room] endpoints. |
Sending licence information using the /licenses/data/properties/{property_id} endpoint for property-level licences and the /licenses/data/properties/{property_id}/rooms/{room_id} endpoint for room type-level licences. |
Retrieving existing licence information using the ota/OTA_HotelDescriptiveInfo endpoint. | Retrieving existing licence information per property using the /licenses/data/properties/{property_id} endpoint endpoint for property-level licence information and the /licenses/data/properties/{property_id}/rooms/{room_id} endpoint for the room type-level licence information. |
Hotelier messages¶
We plan to deprecate sending hotelier messages using the Content API on February 15, 2022. You can find the features we plan to deprecate next to their alternatives:
Deprecating CAPI feature | New solution or alternative |
---|---|
Sending a hotelier message using the OTA_HotelDescriptiveContentNotif endpoint. | Sending a hotelier message using the /properties/{property_id}/hotelier_messages endpoint. |
Retrieving hotelier messages info using the OTA_HotelDescriptiveInfo endpoint. | Retrieving hotelier messages using the /properties/{property_id}/hotelier_messages endpoint. |
Single property owner (SPO) flow¶
We plan to deprecate the SPO flow, which is creating an independent property without legal entity id, on September 15, 2021. You can find the features we plan to deprecate next to their alternatives:
Deprecating CAPI feature | New solution or alternative |
---|---|
Creating an independent property using the OTA_HotelDescriptiveContentNotif endpoint, which refers to creating a property without a legal entity id. |
Switching on the contracting feature that enables you to build a property first using [the OTA_HotelDescriptiveContentNotif endpoint][creating-independent-property] by providing a legal contact email under <ContactInfo ContactProfileType="contract"> . For more information, see the Contracting API. |
Photos through HotelDescriptiveContentNotif (HDCN)¶
We plan to deprecate sending photos using the HotelDescriptiveContentNotif endpoint on September 15, 2021. You can find the features we plan to deprecate next to their alternatives:
Deprecating CAPI feature | New solution or alternative |
---|---|
Sending and uploading photos using the MultimediaDescriptions element in the the OTA_HotelDescriptiveContentNotif endpoint. | Using the improved Photo API to manage all your photo needs. |