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.
Introducing Payments Clarity Package V2¶
We are rolling out changes to the way the Reservations API calculates and displays the breakdown of the total price for each reservation booking using a new feature: Payments Clarity Package V2 (payment_clarity_package_v2
).
Payments Clarity Package V2 is a new and improved version of the Payments Clarity Package feature with significant changes to the response elements. We will switch on the new feature for all providers by Apr 01, 2024.
This feature is relevant only when used along with the Reservations API. If you have been using the Include Price Details (include_price_details
) or the existing Payments Clarity Package (vcc_payment_v2
) feature, post April 01, 2024, you will only receive data from the Payments Clarity Package V2 (payment_clarity_package_v2
) feature.
Important
If you have been validating whether fees, taxes or charges are included in the price when recalculating the reservation prices (with the Include Price Details (include_price_details
) or the Payments Clarity Package (vcc_payment_v2
) feature turned on), then you must revisit the price calculation as the relevant flags and amounts will change once the new Payments Clarity Package V2 (payment_clarity_package_v2
) feature is enabled.
Doing this can avoid showing incorrect reservation prices.
By enabling the feature you can expect the following changed behaviour when using the Reservations API:
- For B.XML endpoints:
guest > extracomponent > included: yes/no
: [For bookings where Booking.com handles payments] Indicates whether Booking.com collected the specified amount from the guest.hotel > extracomponent > included: yes/no
: [For bookings where Booking.com handles payments] Indicates whether Booking.com includes the specified amount in the total as owed to the property.- In addition to the extra fields returned by the existing
vcc_payment_v2
feature, you get an additional attribute in theextracomponent
field that specifies whether Booking.com has withheld tax for a reservation.
- For OTA endpoints: To support showing the pricing breakup between the guest (what was collected or owed by the guest) and the property (what is owed to the property), we have encapsulated the pricing details within the
GuestView
andHotelView
in the response details:PriceDetails > GuestView > Taxes > Tax > Type: Inclusive/Exclusive
: [For bookings where Booking.com handles payments] Indicates whether Booking.com collected the specified amount from the guest.PriceDetails > HotelView > Taxes > Tax > Type: Inclusive/Exclusive
: [For bookings where Booking.com handles payments] Indicates whether Booking.com includes the specified amount in the total as owed to the property.RoomStay
><Total AmountAfterTax="000000">
is now changed to show total for both the guest and the property as follows:PriceDetails
>GuestView
><Total Amount="00000">
PriceDetails
>HotelView
><Total Amount="00000">
- In addition, you also get an additional attribute in the
Tax
field that specifies whether Booking.com has withheld tax for a reservation. For more information, see Payments Clarity Package V2.
The inclusion of the additional attribute in the response is only applicable if the property:
- Is located in a region where Booking.com is obligated to withhold and remit taxes on behalf of the property.
- Is in the US and has chosen the
Payments by Booking.com
as the payment method. For other geographies, Booking.com remits taxes for bank transfer and agency reservations also.
For Reservations API response examples, see:
B.XML endpoint examples¶
The following sections show the current and the new B.XML reservation response snippets to help you compare the difference in behaviour. The responses are applicable provided the following price configuration are set for the property.
The price of the room $100 includes:
- VAT of 18.00% is included
And the price excludes:
- City tax of 12.50% isn't included
- Bed linens fee of € 16 per stay isn't included
- Cleaning fee of € 18 per stay isn't included
B.XML response current behaviour¶
The following reservation response snippet shows details where Booking.com handles collecting payments from the guest. Also, either the Payments Clarity Package, or the Include Price Details feature is turned on.
<reservations>
<reservation>
<customer>
...
<cc_activation_date>2021-08-12</cc_activation_date>
<cc_current_balance>105.99</cc_current_balance>
...
<vcc_expiration_date>2029-03-09</vcc_expiration_date>
...
</customer>
...
<room>
...
<price date="2024-01-16"
genius_rate="no"
rate_id="31282145"
rewritten_from_id="0"
rewritten_from_name="">100</price>
<price_details>
<guest>
<extracomponent amount="16"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="18"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Gas fee" />
<extracomponent amount="15.25"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="10.59"
currency="US"
included="yes"
per_night="no"
per_person="no"
percentage="12.5%"
text="City tax" />
<total>144.59</total>
</guest>
<hotel>
<extracomponent amount="16"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="18"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="no"
text="Gas fee" />
<extracomponent amount="15.25"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="10.59"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="12.5%"
text="City tax" />
<total>100</total>
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>4667482365</roomreservation_id>
<smoking>0</smoking>
<totalprice>100</totalprice>
...
</room>
...
</reservation>
</reservations>
B.XML response new behaviour¶
The responses are applicable provided the Payments Clarity Package V2 is turned on for the property.
Scenario | Guest View | Property View | Description |
---|---|---|---|
1 | Excluded | Excluded | - Fees/tax was not collected during the book process. - Fees/tax will not be paid out to the property. - Fees/tax will be collected from guests by the property at the time of check-in. |
2 | Excluded | Included | - Fees/tax was not collected from the guest during booking. - Fees/tax cost will be borne by Booking and paid out to the property as a benefit. |
3 | Included | Excluded | - Fees/tax was collected from the guest during booking. - Fees/tax is withheld and will be paid directly to the authorities and not to property. |
4 | Included | Included | - Fees/tax was collected from the guest during booking. - Fees/tax will be paid out to property. |
<reservations>
<reservation>
<customer>
...
<cc_activation_date>2021-08-12</cc_activation_date>
<cc_current_balance>144.59</cc_current_balance>
...
<vcc_expiration_date>2029-03-09</vcc_expiration_date>
...
</customer>
...
<room>
...
<price date="2024-01-16"
genius_rate="no"
rate_id="31282145"
rewritten_from_id="0"
rewritten_from_name="">100</price>
<price_details>
<guest>
<extracomponent amount="16"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="18"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Gas fee" />
<extracomponent amount="15.25"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="10.59"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="12.5%"
text="City tax" />
<extracomponent amount="10.00"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="10.0%"
text="Indirect Tax (Withheld Tax)" />
<total>154.59</total> # Indicates the amount Booking.com collected from the guest during booking process
</guest>
<hotel>
<extracomponent amount="16"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="18"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Gas fee" />
<extracomponent amount="15.25"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="10.59"
currency="USD"
included="yes"
per_night="no"
per_person="no"
percentage="12.5%"
text="City tax" />
<extracomponent amount="10.00"
currency="USD"
included="no"
per_night="no"
per_person="no"
percentage="10%"
text="Indirect Tax (Withheld Tax)" /> # Only applicable for properties located in a region where Booking.com is obligated
# to withhold and remit taxes on behalf of the property.
# Or located in the US and has chosen the Payments by Booking.com as the payment
# method.
<total>144.59</total> # Indicates the total amount Booking.com owes the property
</hotel>
</price_details>
...
</room>
...
</reservation>
</reservations>
OTA endpoint examples¶
The following sections show the current and the new OTA reservation response snippets to help you compare the difference in behaviour. The responses are applicable provided the following price configurations are set for the property.
The price of the room $100 includes:
- VAT of 18.00%
And the price excludes:
- City tax of 12.50%
- Bed linens fee of € 16 per stay
- Cleaning fee of € 18 per stay
OTA response current behaviour¶
The following reservation response snippet shows details where Booking.com handles collecting payments from the guest. Also, either the Payments Clarity Package or the Include Price Details feature is turned on.
<HotelReservations>
<HotelReservation>
<RoomStays>
<RoomStay>
...
<PaymentCard CardCode="VI" CardNumber="1234567890123456" SeriesCode="123" ExpireDate="0321"
CurrentBalance="10599" VCCExpirationDate="2024-03-09" EffectiveDate="2019-08-12">
<CardHolderName>test</CardHolderName>
</PaymentCard>
<Total AmountAfterTax="10000" CurrencyCode="USD" DecimalPlaces="2">
<Taxes Amount="5984" CurrencyCode="USD" DecimalPlaces="2">
<Tax Amount="1600" ChargeFrequency="12" Code="14" CurrencyCode="USD" DecimalPlaces="2" Type="Exclusive">
<TaxDescription>
<Text>Bed linens fee</Text>
</TaxDescription>
</Tax>
<Tax Amount="1800" ChargeFrequency="12" Code="14" CurrencyCode="USD" DecimalPlaces="2" Type="Exclusive">
<TaxDescription>
<Text>Gas fee</Text>
</TaxDescription>
</Tax>
<Tax Amount="1525" ChargeFrequency="12" Code="19" CurrencyCode="USD" DecimalPlaces="2" Type="Inclusive">
<TaxDescription>
<Text>VAT (18%)</Text>
</TaxDescription>
</Tax>
<Tax Amount="1059" ChargeFrequency="12" Code="3" CurrencyCode="USD" DecimalPlaces="2" Type="Exclusive">
<TaxDescription>
<Text>City tax (12.5%)</Text>
</TaxDescription>
</Tax>
</Taxes>
</Total>
...
</RoomStay>
</RoomStays>
</HotelReservation>
</HotelReservations>
OTA response new behaviour¶
The following response is applicable provided the Payments Clarity Package V2 feature is turned on.
Scenario | Guest View | Property View | Description |
---|---|---|---|
1 | Excluded | Excluded | - Fees/tax was not collected during the book process. - Fees/tax will not be paid out to the property. - Fees/tax will be collected from guests by the property at the time of check-in. |
2 | Excluded | Included | - Fees/tax was not collected from the guest during booking. - Fees/tax cost will be borne by Booking and paid out to the property as a benefit. |
3 | Included | Excluded | - Fees/tax was collected from the guest during booking. - Fees/tax is withheld and will be paid directly to the authorities and not to property. |
4 | Included | Included | - Fees/tax was collected from the guest during booking. - Fees/tax will be paid out to property. |
<HotelReservations>
<HotelReservation>
<RoomStays>
<RoomStay>
...
<PaymentCard CardCode="VI" CardNumber="1234567890123456" SeriesCode="123" ExpireDate="0321"
CurrentBalance="14459" VCCExpirationDate="2024-03-09" EffectiveDate="2019-08-12">
<CardHolderName>test</CardHolderName>
</PaymentCard>
<PriceDetails>
<GuestView>
<Taxes>
<Tax Amount="1600" ChargeFrequency="12" Code="14" CurrencyCode="USD" DecimalPlaces="2" Type="Inclusive">
<TaxDescription>
<Text>Bed linens fee</Text>
</TaxDescription>
</Tax>
<Tax Amount="1800" ChargeFrequency="12" Code="14" CurrencyCode="USD" DecimalPlaces="2" Type="Inclusive">
<TaxDescription>
<Text>Gas fee</Text>
</TaxDescription>
</Tax>
<Tax Amount="1525" ChargeFrequency="12" Code="19" CurrencyCode="USD" DecimalPlaces="2" Type="Inclusive">
<TaxDescription>
<Text>VAT (18%)</Text>
</TaxDescription>
</Tax>
<Tax Amount="1059" ChargeFrequency="12" Code="3" CurrencyCode="USD" DecimalPlaces="2" Type="Inclusive">
<TaxDescription>
<Text>City tax (12.5%)</Text>
</TaxDescription>
</Tax>
<Tax Amount="1000" ChargeFrequency="21" Code="3" CurrencyCode="USD" DecimalPlaces="2" Type="Inclusive">
<TaxDescription>
<Text>Indirect Tax (Withheld Tax)</Text>
</TaxDescription>
</Tax>
</Taxes>
<Total Amount="15459" DecimalPlaces="2"/> # Indicates the amount Booking.com collected from the guest during booking process
</GuestView>
<HotelView>
<Taxes>
<Tax Amount="1600" ChargeFrequency="12" Code="14" CurrencyCode="USD" DecimalPlaces="2" Type="Inclusive">
<TaxDescription>
<Text>Bed linens fee</Text>
</TaxDescription>
</Tax>
<Tax Amount="1800" ChargeFrequency="12" Code="14" CurrencyCode="USD" DecimalPlaces="2" Type="Inclusive">
<TaxDescription>
<Text>Gas fee</Text>
</TaxDescription>
</Tax>
<Tax Amount="1525" ChargeFrequency="12" Code="19" CurrencyCode="USD" DecimalPlaces="2" Type="Inclusive">
<TaxDescription>
<Text>VAT (18%)</Text>
</TaxDescription>
</Tax>
<Tax Amount="1059" ChargeFrequency="12" Code="3" CurrencyCode="USD" DecimalPlaces="2" Type="Inclusive">
<TaxDescription>
<Text>City tax (12.5%)</Text>
</TaxDescription>
</Tax>
<Tax Amount="1000" ChargeFrequency="21" Code="3" CurrencyCode="USD" DecimalPlaces="2" Type="Exclusive"> # Only applicable for properties located in a region where Booking.com is obligated
# to withhold and remit taxes on behalf of the property.
# Or located in the US and has chosen the Payments by Booking.com as the payment
# method.
<TaxDescription>
<Text>Indirect Tax (Withheld Tax)</Text>
</TaxDescription>
</Tax>
</Taxes>
<Total Amount="14459" DecimalPlaces="2"/> # Indicates the total amount Booking.com owes the property
</HotelView>
</PriceDetails>
...
</RoomStay>
</RoomStays>
</HotelReservation>
</HotelReservations>
Changes to the Market insights API error handling¶
We are changing how we return error code responses in the Market insights API. To follow the new Online Travel Agency(OTA) standards in processing error codes, the Market Insights API will return OTA error codes in place of error strings.
Instead of a string value in the [Old] Error Code
column, the API returns a numeric value as specified in the [New] OTA Error Code
column.
The API returns the old message
values in the Description
field.
HTTP Error Code | [Old] Error Code | [New] OTA Error Code | Message | Description | Reason and Possible Fix |
---|---|---|---|---|---|
HTTP 400 Bad Request | FORBIDDEN | 450 | Unable to process. | Can be one of the following: - The property is not eligible for retrieving demand data - The provider is not eligible for retrieving demand data - This account doesn't have access to this property |
Can occur due to one of the following reasons: - Incorrect endpoint URL/HTTP method or invalid JSON body. Make sure to use the correct endpoint URL/HTTP method or check if the request has a valid JSON body. |
For more information on the Market insights API, see Analysing Booking.com guests' demand data.
Changes to the LOS pricing endpoint¶
The following improvements are rolled out to the /hotels/csv/los_pricing
endpoint v1.1.
We plan to deprecate v1.0 of the hotels/csv/los_pricing
endpoint. For the deprecation and sunset timeline, see the Deprecation and sunsetting topic.
The changes outlined in this section are applicable only when using the hotels/csv/los_pricing
endpoint with a special header parameter.
The following section covers only the changes available in v1.1. For a detailed explanation of the hotels/csv/los_pricing
endpoint, see Create or update LOS pricing rates.
The following are the changes implemented in the v1.1 hotels/csv/los_pricing
endpoint:
- If the specified price per night exceeds the maximum price (€50000 or equivalent), then the API rejects the price update request. This differs from the previous behaviour: where the API sets the price to 0 and automatically closes the room.
- While setting up pricing for an inventory using rate IDs that are configured as child rates, make sure the request doesn't set values for fields that are configured to inherit from the parent rate plan. For example, if you try to set a price for a child rate while the child rate is configured to follow price, the API returns a partial success response with an error message.
To resolve the error, specify a rate plan ID that is either configured as a parent rate, or a child rate that does not have the
FollowsPrice
restriction set. - Accepts past date updates up to 1 day in the past (follows Central European Time (CET) timezone). Updates more than 1 day in the past returns a
NOT_A_VALID_DATE
error. - Some existing error messages were improved for better clarity. For a list of all the error message changes see changes to existing error messages.
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/csv/los_pricing' \
--header 'Accept-Version: 1.1' \
--header 'Authorization: Basic THVjLVNhbXVlbMblmRAdlOCghQ29qaU9pNmxlWSpIWXU9OigvS2meQpQ12puj' \
--header 'Content-Type: application/csv'
HTTP error code behaviour on v1.1 los_pricing¶
With the v1.1 of the los_pricing
endpoint, we have standardised the treatment of the 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 |
Changes to existing behaviour¶
When you migrate to v1.1 of the los_pricing
endpoint, you can see the following change in the API behaviour:
Existing API behaviour (v1.0) | New API behaviour (v1.1) |
---|---|
Accepts update for child rates. | While setting up availability using rate IDs that are configured as child rates, make sure the request doesn't set values for fields that are configured to inherit from the parent rate plan. For example, if you try to set a value for MinAdvancedBookingOffset restrictions for a child rate while the child rate is configured to follow restrictions, the API returns a partial success response with an error message. To resolve the error, specify a rate plan ID that is either configured as a parent rate, or a child rate that does not have the following restrictions: FollowsPrice , or FollowsRestrictions . Similar to the v1.0 behaviour, the above constraint does not apply to the FollowsClosed restriction. While creating availability using a child rate ID, you can update the status of the room type to open or close, irrespective of the value set in FollowsClosed . However, if an availability is set using a parent rate along with open/close information, then the room type status for the associated child rate is also updated. To reiterate, there is no change to the FollowsClosed restriction behaviour. |
Accepts past date updates. | Accepts past date updates up to 1 day in the past (follows Central European Time (CET) timezone). Updates more than 1 day in the past returns a NOT_A_VALID_DATE error. |
Accepts duplicate date updates. | Does not accept duplicate date updates. The API now returns WARN_DUPLICATE_DATES warning. |
On authorisation errors, the API returns HOTEL_NOT_ALLOWED_FOR_CONNECTION_TYPE error. |
On authorisation errors, the API now returns HOTEL_ACCESS_DENIED error. |
Changes to the OTA_HotelRateAmountNotif endpoint¶
The following improvements are rolled out to the OTA_HotelRateAmountNotif
endpoint. We plan to deprecate v1.0 of the OTA_HotelRateAmountNotif
endpoint by 31 January 2024 11:00 am CEST
with a planned sunset date of February 14, 2024. For more information on the deprecation timeline, see the Deprecation and sunsetting topic.
The changes outlined in this section are applicable only when using the OTA_HotelRateAmountNotif
endpoint with a special header parameter.
The following section covers only the changes available in v1.1.
For a detailed explanation of the OTA_HotelRateAmountNotif
endpoint, see Create or update rates.
When migrating to the v1.1 OTA_HotelRateAmountNotif
endpoint, you get:
- Improved API behaviour.
- 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/ota/OTA_HotelRateAmountNotif' \
--header 'Accept-Version: 1.1' \
--header 'Authorization: Basic THVjLVNhbXVlbMblhWTdlOCghQ29qaU9pNmxlWSpIWXU9OigvS2meQpQ12puj' \
--header 'Content-Type: application/xml'
Sample request¶
The following example is to set price per rate/room/date for a property using Occupancy based pricing type.
Note: If only a few weekdays are marked as true
then the API marks the other days as false
.
However, if some weekdays are marked as false
, then the API considers this as sending none as true
and therefore marks all weekdays as true
.
<OTA_HotelRateAmountNotifRQ>
<RateAmountMessages>
<RateAmountMessage LocatorID="1">
<StatusApplicationControl Sat="true" Sun="true" Start="2023-11-19" End="2023-12-20" RatePlanCode="25278032" InvTypeCode="801185512" />
<Rates>
<Rate MinLOS="1" MaxLOS="1" RateTimeUnit="Day" UnitMultiplier="1" MinGuestApplicable="1" MaxGuestApplicable="4">
<BaseByGuestAmts>
<BaseByGuestAmt AmountBeforeTax="3800" DecimalPlaces="2" NumberOfGuests="4" CurrencyCode="EUR" />
</BaseByGuestAmts>
<AdditionalGuestAmounts>
<AdditionalGuestAmount AgeBucketID="1" AdditionalGuestNumber="1" Amount="0.01" DecimalPlaces="0" AgeQualifyingCode="8" />
<AdditionalGuestAmount MinAge="2" MaxAge="5" AdditionalGuestNumber="1" Percent="5" DecimalPlaces="0" AgeQualifyingCode="8" />
</AdditionalGuestAmounts>
</Rate>
</Rates>
</RateAmountMessage>
</RateAmountMessages>
</OTA_HotelRateAmountNotifRQ>
Sample response¶
<OTA_HotelRateAmountNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelRateAmountNotifRS.xsd" TimeStamp="2023-10-12T11:34:06-00:00" Target="Production" Version="1.006">
<Success />
</OTA_HotelRateAmountNotifRS>
Sample error response¶
<OTA_HotelRateAmountNotifRS>
<Errors>
<Error Code="RATE_NOT_ACTIVE_FOR_ROOM" ShortText="Rate '18858134' is not active for room '28301'" Details="rate_ids: 18134; dates: 2024-04-11,2024-04-12; hotel_ids: 2783; room_ids: 28301;"/>
</Errors>
</OTA_HotelRateAmountNotifRS>
Changes to the OTA_HotelRateAmountNotif behaviour¶
The following are the changes implemented in the v1.1 OTA_HotelRateAmountNotif
endpoint:
- If the specified price per night exceeds the maximum price (€50000 or equivalent), then the API rejects the price update request. This differs from the previous behaviour: where the API sets the price to 0 and automatically closes the room.
- While setting up price per rate, room and date combination using rate IDs that are configured as child rates, make sure the request doesn't set values for fields that are configured to inherit from the parent rate plan. For example, if you try to set a price for a child rate while the child rate is configured to follow price, the API returns a partial success response with an error message.
To resolve the error, specify a rate plan ID that is either configured as a parent rate, or a child rate that does not have the
FollowsPrice
restriction set. - When setting decimal prices, you must use the period decimal separator and not the comma separator. For example, 75.50 is a valid price definition whereas 75,50 returns an HTTP 400 status error.
- Accepts past date updates up to 1 day in the past (follows Central European Time (CET) timezone). Updates more than 1 day in the past returns a
NOT_A_VALID_DATE
error. - It is recommended to use the
NumberOfGuests
attribute instead of theMinGuestApplicable
andMaxGuestApplicable
attributes.
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/ota/OTA_HotelRateAmountNotif' \
--header 'Accept-Version: 1.1' \
--header 'Authorization: Basic THVjLVNhbXVlbMblmRAdlOCghQ29qaU9pNmxlWSpIWXU9OigvS2meQpQ12puj' \
--header 'Content-Type: application/xml'
HTTP error code behaviour on v1.1 OTA_HotelRateAmountNotif¶
With the v1.1 of the OTA_HotelRateAmountNotif
endpoint, we have standardised the treatment of the 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 |
New warnings on v1.1¶
The following table summarises the new warnings for the OTA_HotelRateAmountNotif
endpoint.
New error code | Error message | Notes |
---|---|---|
WARN_UNPROCESSED_ADDITIONAL_GUEST | Additional guest updates weren't processed. Please try again later. | |
WARN_DUPLICATE_DATES | Request contains duplicate dates, we have applied only the first occurrence. |
New error codes on v1.1¶
The following table summarises the new error codes for the OTA_HotelRateAmountNotif
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 in 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 . Or, the supplied date is more than 1 day in the past. |
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. |
DATE_ELEMENT_MISSING | Date is missing | Date is required for this request. |
RATE_ID_REQUIRED | Rate Id is required | Rate id is required for this request. |
OBP_PRICING_PASSED_FOR_RLO_RATE | OBP format sent for RLO room-rate | Room-rate is on RLO pricing model while request is trying to set OBP prices for it. |
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. |
RATE_IS_A_SLAVE_RATE | You cannot set $attribute for a child rate $rate_id, since they are automatically set based on Rate Relations | Cannot update a child rate. |
CURRENCY_SWITCH_IN_PROGRESS | There is a hotel currency switch currently in progress | You need to wait until hotel switch currency. |
EXCEEDS_MAX_RELATIVE_RELEASE_TIME | Relative release time | You are setting release time that exceeds the maximum allowed value. |
NUMBER_OF_NIGHTS_EXCEEDS_MAX_FOR_LINES | The update has too many nights and only the first 90 nights were considered | You cannot set more than 90 nights. |
OCCUPANCY_EXCEEDS_MAX_PERSONS | Room '%s' has a maximum occupancy of '%s'. You cannot set price for higher occupancy for rate '%s' | Cannot set pricing for occupancy that is higher than the maximum occupancy. |
AUTHENTICATION_FAILURE | Authentication failed for the request | The credentials provided in the request was not sufficient for a successful authentication check. To fix a failed authentication request, see the Authentication page. |
INTERNAL_SERVER_ERROR | Internal server error | Booking.com service failed. |
Changes to the roomrateavailability endpoint¶
The following updates are available to the roomrateavailability
endpoint with the version 1.1.
Difference between roomrateavailability endpoint v1.0 and v1.1¶
You can use the roomrateavailability
endpoint in two versions.
In addition to the functionality available in v1.0, when migrating to the v1.1 roomrateavailability
endpoint, you can view whether a room type is closed.
For more information on the existing functionality, see Retrieve inventory and rate details.
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/roomrateavailability' \
--header 'Accept-Version: 1.1' \
--header 'Authorization: Basic THVjLVNhbXVlbMblmRAdlOCghQ29qaU9pNmxlWSpIWXU9OigvS2meQpQ12puj' \
--header 'Content-Type: application/xml'
Response parameters¶
Field | Description | Type | Required | Notes |
---|---|---|---|---|
> date |
Contains availability information for specified date. | object | The API returns this element only if the value of room_level in the request is 0 . |
|
closed |
Specifies whether all rooms of a room type are closed (not bookable) on the specified date. | boolean | Possible values are: 1 (closed), 0 (open). Once you close a room, make sure to open it before setting availability for it. |
Changes to the OTA_HotelAvailNotif endpoint¶
The following improvements are rolled out to the OTA_HotelAvailNotif
endpoint.
The changes outlined in this section are applicable only when using the OTA_HotelAvailNotif
endpoint with a special header parameter.
The following section covers only the changes available in v1.1.
For a detailed explanation of the OTA_HotelAvailNotif
endpoint, see Create or update inventory, restrictions.
When migrating to the v1.1 OTA_HotelAvailNotif
endpoint, you get:
- To close a room type on a specified date. Even if roomrates are open, the room type is not available for booking.
- Set past date updates up to 1 day in the past (follows Central European Time (CET) timezone). Updates more than 1 day in the past, return a
NOT_A_VALID_DATE
error. - Improved API behaviour.
- 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/ota/OTA_HotelAvailNotif' \
--header 'Accept-Version: 1.1' \
--header 'Authorization: Basic THVjLVNhbXVlbMblhWTdlOCghQ29qaU9pNmxlWSpIWXU9OigvS2meQpQ12puj' \
--header 'Content-Type: application/xml'
Closing room type vs. room and rate combination¶
You can close availability at the:
- room type level: Useful when removing availability for all rooms of a room type that has multiple rate combinations.
- room type and rate combination level: Useful when removing availability for a room type satisfying a specific rate combination.
Consider the following inventory:
Room type | Rate | Price | Date period | Rooms to sell |
---|---|---|---|---|
Villa | Summer rate | 110 | Jul 15 - Aug 31 | 10 |
Villa | Peak season rate | 120 | Aug 05 - Aug 20 | 10 |
Villa | Off season rate | 90 | Nov 01 - Dec 10 | 10 |
Closing room type and rate combination¶
To close the availability of the Villa so that guests don't see availability from Nov 01 - Dec 10, you must
close the room type (Villa) and rate combination (Off season rate) by providing the following parameters: room
, date
, rate
, closed
Closing a room type¶
To close the availability of a specific room type, say Villa, so that guests don't see availability for a specific period, you must
close the room type (Villa) by providing the following parameters: room
, date
, closed
.
Once a room is closed you must open it before creating availability
Before creating availability for a room that is closed, you must use the OTA_HotelAvailNotif
endpoint to open the room.
Otherwise, the request to create availability completes successfully. But guests will not be able to see the availability as the room is still closed.
Request body¶
For a complete list of request parameters available for this endpoint, see the documentation on the availability
endpoint.
Element | Attribute | Description | Type | Required | Notes |
---|---|---|---|---|---|
>>> RestrictionStatus |
Specifies whether all rooms of a room type are closed (not bookable) or only the specified room type and rate combination on the specified date depending on whether the rate ID is provided. | integer | optional | ||
Status |
Specifies whether all rooms of a room type are closed (not bookable) or only the specified room type and rate combination on the specified date depending on whether the StatusApplicationControl.RatePlanCode is provided. |
string | enumerated string | Accepts: close , or open . |
Changes to existing behaviour¶
When you migrate to v1.1 of the OTA_HotelAvailNotif
endpoint, you can see the following change in the API behaviour:
Existing API behaviour (v1.0) | New API behaviour (v1.1) |
---|---|
Accepts update for child rates. | While setting up availability using rate IDs that are configured as child rates, make sure the request doesn't set values for fields that are configured to inherit from the parent rate plan. For example, if you try to set a value for MinAdvancedBookingOffset restrictions for a child rate while the child rate is configured to follow restrictions, the API returns a partial success response with an error message. To resolve the error, specify a rate plan ID that is either configured as a parent rate, or a child rate that does not have the following restrictions: FollowsPrice , or FollowsRestrictions . Similar to the v1.0 behaviour, the above constraint does not apply to the FollowsClosed restriction. While creating availability using a child rate ID, you can update the status of the room type to open or close, irrespective of the value set in FollowsClosed . However, if an availability is set using a parent rate along with open/close information, then the room type status for the associated child rate is also updated. To reiterate, there is no change to the FollowsClosed restriction behaviour. |
Accepts past date updates. | Accepts past date updates up to 1 day in the past (follows Central European Time (CET) timezone). Updates more than 1 day in the past returns a NOT_A_VALID_DATE error. |
Accepts duplicate date updates. | Does not accept duplicate date updates. The API now returns WARN_DUPLICATE_DATES warning. |
On authorisation errors, the API returns HOTEL_NOT_ALLOWED_FOR_CONNECTION_TYPE error. |
On authorisation errors, the API now returns HOTEL_ACCESS_DENIED error. |
Accepts Content-Type: application/x-www-form-urlencoded and the body of the request is encoded. |
Only supports Content-Type: application/xml or text/xml , as per documentation. |
Property ID is validated. | Property ID is not required and is not validated. |
Setting the MinAdvancedBookingOffset or MaxAdvancedBookingOffset value beyond 360 days 360D does not return an error. |
Setting the MinAdvancedBookingOffset or MaxAdvancedBookingOffset value beyond 360 days 360D returns an error. |
HTTP error code behaviour on v1.1¶
With the v1.1 of the OTA_HotelAvailNotif
endpoint, we have standardised the treatment of the 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 |
New error codes on v1.1¶
The following table summarises the new error codes for the OTA_HotelAvailNotif
endpoint.
Error code | Error message | Notes |
---|---|---|
AUTHENTICATION_FAILURE | Authentication failed for the request | The credentials provided in the request was not sufficient for a successful authentication check. To fix a failed authentication request, see the Authentication page. |
CURRENCY_SWITCH_IN_PROGRESS | There is a hotel currency switch currently in progress | You need to wait until hotel switch currency. |
DATE_ELEMENT_MISSING | Date is missing | Date is required for this request. |
EXCEEDS_MAX_RELATIVE_RELEASE_TIME | Relative release time | You are setting release time that exceeds the maximum allowed value. |
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. |
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. |
HOTEL_HAS_MISCONFIGURED_UFI | The timezone value is missing for the Ufi associated with hotel ID $hotel_id | Check the property's UFI configuration. |
INTERNAL_SERVER_ERROR | Internal server error | Booking.com service failed. |
NOT_A_VALID_DATE | INVALID_DATE | The supplied date format is invalid. The valid format is yyyy-mm-dd . Or, the supplied date is more than 1 day in the past. |
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. |
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. |
RATE_ID_REQUIRED | Rate Id is required | Rate id is required for this request. |
RATE_IS_A_SLAVE_RATE | You cannot set $attribute for a child rate $rate_id, since they are automatically set based on Rate Relations | Cannot update a child rate. |
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. |
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. |
ROOM_ELEMENT_REQUIRED | Room is missing | The request contains an empty request body. |
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_ID_MISSING | Room ID is missing | Room ID is required for the request. |
TYPE_VIOLATION | Generic error when provided data type is different than specified. |
Changes to the availability endpoint¶
We have rolled out few improvements to the B.XML availability
endpoint.
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:
- To close a room type on a specified date. Even if roomrates are open, the room type is not available for booking.
- To update for periods in the future and up to one day in the past, in the Central European Time (CET) timezone.
- Accepts past date updates up to 1 day in the past (follows Central European Time (CET) timezone). Updates more than 1 day in the past returns a
NOT_A_VALID_DATE
error. - Improved error handling and error description.
- Improved latency.
New behaviour¶
While setting up availability using rate IDs that are configured as child rates, make sure the request doesn't set values for fields that are configured to inherit from the parent rate plan.
For example, if you try to set a value for min_advance_res
restrictions for a child rate while the child rate is configured to follow restrictions or set price
when FollowsPrice
is set, the API returns a partial success response with an error.
To resolve the error, specify a rate plan ID that is either configured as a parent rate, or a child rate that does not have the following restrictions: FollowsPrice
, or FollowsRestrictions
.
Similar to the v1.0 behaviour, the above constraint does not apply to the FollowsClosed
restriction.
While creating availability using a child rate ID, you can update the status of the room type to open or close, irrespective of the value set in FollowsClosed
.
However, if an availability is set using a parent rate along with open/close information, then the room type status for the associated child rate is also updated. To reiterate, there is no change to the FollowsClosed
restriction behaviour.
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'
Closing room type vs. room and rate combination¶
You can close availability at the:
- room type level: Useful when removing availability for all rooms of a room type that has multiple rate combinations.
- room type and rate combination level: Useful when removing availability for a room type satisfying a specific rate combination.
Consider the following inventory:
Room type | Rate | Price | Date period | Rooms to sell |
---|---|---|---|---|
Villa | Summer rate | 110 | Jul 15 - Aug 31 | 10 |
Villa | Peak season rate | 120 | Aug 05 - Aug 20 | 10 |
Villa | Off season rate | 90 | Nov 01 - Dec 10 | 10 |
Closing room type and rate combination¶
To close the availability of the Villa so that guests don't see availability from Nov 01 - Dec 10, you must
close the room type (Villa) and rate combination (Off season rate) by providing the following parameters: room
, date
, rate
, closed
Closing a room type¶
To close the availability of a specific room type, say Villa, so that guests don't see availability for a specific period, you must
close the room type (Villa) by providing the following parameters: room
, date
, closed
.
Once a room is closed you must open it before creating availability
Before creating availability for a room that is closed, you must use the availability
endpoint to open the room.
Otherwise, the request to create availability completes successfully. But guests will not be able to see the availability as the room is still closed.
Request body¶
For a complete list of request parameters available for this endpoint, see the documentation on the availability
endpoint.
Element | Attribute | Description | Type | Required | Notes |
---|---|---|---|---|---|
>>> closed |
Specifies whether all rooms of a room type are closed (not bookable) or only the specified room type and rate combination on the specified date depending on whether the rate ID is provided. | integer | optional | Accepts: 1 (closed), 0 (open). NOTE: See also Availability restrictions. Closing a room does not clear the value of roomstosell , price , or other fields. The values are preserved. Once you close a room, make sure to open it before setting availability for it. |
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 warnings on v1.1¶
The following table summarises the new warnings for the B.XML availability
endpoint.
New error code | Error message | Notes |
---|---|---|
WARN_UNPROCESSED_ADDITIONAL_GUEST | Additional guest updates weren't processed. Please try again later. | |
WARN_DUPLICATE_DATES | Request contains duplicate dates, we have applied only the first occurrence. |
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 . Or, the supplied date is more than 1 day in the past. |
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. |
DATE_ELEMENT_MISSING | Date is missing | Date is required for this request. |
RATE_ID_REQUIRED | Rate Id is required | Rate id is required for this request. |
OBP_PRICING_PASSED_FOR_RLO_RATE | OBP format sent for RLO room-rate | Room-rate is on RLO pricing model while request is trying to set OBP prices for it. |
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. |
RATE_IS_A_SLAVE_RATE | You cannot set $attribute for a child rate $rate_id, since they are automatically set based on Rate Relations | Cannot update a child rate. |
CURRENCY_SWITCH_IN_PROGRESS | There is a hotel currency switch currently in progress | You need to wait until hotel switch currency. |
EXCEEDS_MAX_RELATIVE_RELEASE_TIME | Relative release time | You are setting release time that exceeds the maximum allowed value. |
OCCUPANCY_EXCEEDS_MAX_PERSONS | Room '%s' has a maximum occupancy of '%s'. You cannot set price for higher occupancy for rate '%s' | Cannot set pricing for occupancy that is higher than the maximum occupancy. |
AUTHENTICATION_FAILURE | Authentication failed for the request | The credentials provided in the request was not sufficient for a successful authentication check. To fix a failed authentication request, see the Authentication page. |
INTERNAL_SERVER_ERROR | Internal server error | Booking.com service failed. |
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:
- To resolve security issues and non-standard system behavior, the v1.1
roomrates
endpoint supports the UTF-16 encoding algorithm. - 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>
<rooms>
<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>
</rooms>
</roomrates>
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. |