Create or update inventory, rates and restrictions¶
Use the availability
endpoint to specify a property's availability for specific rooms, rates, and dates.
Each request can contain the following information:
- The number of available rooms for sale on specified dates.
- The price for the room, depending on the number of occupants.
- Restrictions on the length of the stay and check-in and check-out dates.
For more information on pricing models, see Pricing Models.
Specify at least 12 months of availability
You should specify the availability of your connected properties at least 12 months in advance. In other words, on 1 January 2019, you should specify availability until at least 31 December 2019.
Specify currencies with availability
As Booking.com supports more and more currencies around the world, it’s crucial that guests can see the correct prices on Booking.com. To ensure correctness, you must send us the currency code along with prices in all the R&A APIs.
In case that the "Currency Code" field does not match the default currency found in the Booking.com system, the “CURRENCY_CODE_DONT_MATCH_HOTEL_CURRENCY” error is returned.
To retrieve the property details along with the configured currency code, use the GET OTA_HotelDescriptiveInfo
endpoint.
URL¶
POST https://supply-xml.booking.com/hotels/xml/availability
Request body¶
Field | Description | Type | Required | Notes |
---|---|---|---|---|
request |
Root element. | object | Required | - |
room |
Contains details about the room. | object | Required | - |
room[@id] |
The Booking.com room ID. | integer | Required | |
date |
Specifies the date(s) (@value ), date range (@from @to ), or mix of both to which the availability applies. |
datetime | Required | Format: YYYY-MM-DD . We recommend to specify at least 12 months of availability. |
date[@value] |
Specifies a single date. | datetime | Required | Format: YYYY-MM-DD .NOTE: You may include multiple occurrences of date[@value] in the same date element. |
date[@from] |
Specifies the starting date of a date range. | datetime | Required | Format: YYYY-MM-DD . Date must be before the date you specify in @to . |
date[@to] |
Specifies the ending date of a date range. | datetime | Required | Format: YYYY-MM-DD . You can specify up to 10 years of availability from the date you make the call. NOTE: You should interpret date[@to] as "up to and not including". In other words, a request with <date from="2019-08-27" to="2029-09-02" /> applies to all days from 27 August 2019 up to 1 September 2029. |
version |
Interface specification version. | string | Optional | Default: 1.0 |
currencycode |
property's local currency code | Code | Optional | - |
rate |
Contains details about the rate. | integer | Optional | This field is optional if the property uses the "room level" inventory model. NOTE: If your request includes rate , it must not include roomstosell . |
rate[@id] |
The Booking.com rate ID. | integer | Optional | Use [/xml/roomrates][b_xml-roomrates] to retrieve a list of active rates for a property. |
roomstosell |
Specifies the number of rooms of this type that Booking.com can sell. | integer | Optional | Max. value: 254 NOTE: Setting value to 255 means "unlimited rooms available" — use other restrictions (such as closed ) to prevent overbookings. Values of 256 or higher are interpreted as 254 . |
min_advance_res |
The minimum number of days and/or hours that guests must book in advance (before the planned check-in date). The search date is counted as one of the days in the restriction length. | string | Optional | Examples: 4D = four days; 4D4H = four days and four hours.NOTE: You must include rate[@id] when updating min_advance_res . You cannot specify a negative amount of time. |
max_advance_res |
The maximum number of days and/or hours that guests may book in advance. The search date is counted as one of the days in the restriction length. | string | Optional | Examples: 4D = four days; 4D4H = four days and four hours. NOTE: You must include rate[@id] when updating max_advance_res . You cannot specify a negative amount of time. |
price |
The default price for the specified combination of room, date, and rate, in the property's local currency (as defined by Booking.com). | float | Optional | Format: ###.## (always two decimals)NOTE: What is considered the default price depends on your pricing model. You cannot remove a price after it has been set. You cannot specify a negative price. |
price1 |
The price for one person, for the specified combination of room, date, and rate, in the property's local currency (as defined by Booking.com). | float | Optional | Format: ###.## (always two decimals) NOTE: Don't use price1 for single rooms. You cannot remove price1 when roomstosell is equal to or greater than 1 . You cannot specify a negative price. |
closed |
Specifies whether the room is closed (not bookable) on the specified date, for the specified rate. | integer | Optional | Accepts: 1 (closed), 0 (open). NOTE: See also Availability restrictions. Closing a room does not affect the value of roomstosell , price , or other fields. The values are preserved. |
minimumstay |
The minimum number of days a guest must book the specified room, for the specified rate, if the stay includes the specified date. | integer | Optional | Max. value: 31 . NOTE: Value must be less than maximumstay and maximumstay_arrival . See also Availability restrictions. |
minimumstay_arrival |
The minimum number of days a guest must book the specified room, for the specified rate, if they check in on the specified date. | integer | Optional | Max.value: 31 . NOTE: Value must be less than maximumstay and maximumstay_arrival . See also Availability restrictions. |
maximumstay |
The maximum number of days a guest may book the specified room, for the specified rate, if the stay includes the specified date. | integer | Optional | Max.value: 31 . NOTE: Value must be greater than minimumstay and minimumstay_arrival . See also Availability restrictions. |
maximumstay_arrival |
The maximum number of days a guest may book the specified room, for the specified rate, if they check in on the specified date. | integer | Optional | Max.value: 31 . NOTE: Value must be greater than minimumstay and minimumstay_arrival . See also Availability restrictions. |
exactstay_arrival |
The exact number of days a guest must book the specified room, for the specified rate, if they check in on the specified date. | integer | Optional | Max.value: 31 . NOTE: See also Availability restrictions. |
closedonarrival |
Specifies if the room is unavailable to book if the guest checks in on the specified date. | integer | Optional | Accepts: 1 (closed), 0 (open). NOTE: See also Availability restrictions. |
closedondeparture |
Specifies if the room is unavailable to book if the guest checks out on the specified date. | integer | Optional | Accepts: 1 (closed), 0 (open). NOTE: See also Availability restrictions. |
Removing minimum and maximum length-of-stays¶
To remove an existing length-of-stay restriction you must send a request to update the minimumstay
or maximumstay
value to 0
. You can encounter the following scenarios:
- Update only
<minimumstay>0</minimumstay>
if you want to remove the minimum stay restriction. - Update only
<maximumstay>0</maximumstay>
if you want to remove the maximum stay restriction. - Update both if you want to remove minimum and maximum stay restrictions.
To reinstate restrictions, you must send another request with the value representing the desired amount of days for either or both length-of-stay restrictions.
Sample request¶
The request below specifies the following booking conditions for room type 1000202
, with rate 12345
, on 28 August, 2018:
- The property has
1
room of this type available for sale (roomstosell
). - The room is available to book on this date, for this rate, only if the stay is at least 2 nights, and at most 14 nights (
minimumstay
,maximumstay
). - The room costs 135 (in the property's local currency) per night for one person, or 150 per night for the maximum number of persons.
- The room is not available to book for this rate if the planned check-out date is 28 August (
closedondeparture
).
<request>
<version>1.0</version>
<room id="1000202">
<date value='2018-08-28'>
<roomstosell>1</roomstosell>
</date>
</room>
<room id="1000202">
<date value="2018-08-28">
<currencycode>EUR</currencycode>
<rate id="12345"/>
<price>150.00</price>
<price1>135.00</price1>
<closed>0</closed>
<minimumstay>2</minimumstay>
<maximumstay>14</maximumstay>
<closedonarrival>0</closedonarrival>
<closedondeparture>1</closedondeparture>
</date>
</room>
</request>
Keep roomstosell
and rate
separate
If your request includes both roomstosell
and rate
, we recommend
putting each in its own room
element. This makes it more obvious that the
value of roomstosell
applies to the room
as a whole, and not to an
individual rate
. See also Room-level inventory model.
Response body¶
Field | Description | Type | Notes |
---|---|---|---|
ok |
Indicates a successful request. | object | Only returned if there are no error or fault elements. |
availability |
Root element for error responses. | object | - |
fault |
- | object | - |
fault[@code] |
The HTTP status code for an error. | integer | - |
string |
A description of an error. | string | - |
error |
One or more error messages, separated by ; . |
string | - |
warning |
One or more warning messages, separated by ; . |
string | Warnings can occur even if the response contains ok . |
Sample responses¶
Success¶
A successful response looks like this:
<ok></ok>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXX==] -->
HTTP/1.1 200 OK
does not always mean 'success'
A response with status code 200
and <ok/>
in the body always indicates a successful request. Status code HTTP/1.1 400 Bad request
always indicates an unsuccessful request. A partially successful request gets a response with code HTTP/1.1 200 OK
and a body containing one or more error messages. Take this into consideration when handling responses.
HTTP/1.1 400 Bad request¶
<?xml version='1.0' standalone='yes'?>
<availability>
<fault code="400">
<string>no hotels found for provided room ids: "12345678"</string>
</fault>
</availability>
<!-- RUID: [UmFuZG9tSVetc] -->
Partly successful request¶
A response with status code HTTP/1.1 200 OK
may still have errors in the body:
<error>errors filtered and not done: "room/rate combination is not active ( room id : '2006637', rate id : '1705072', first date : '2018-06-11', last date : '2018-06-12'); room/rate combination is not active ( room id : '2006638', rate id : '129008', first date : '2018-05-13', last date : '2018-05-14')"</error>
<!-- RUID: [UmFuZG9tSVetc] -->
Successful request with warnings¶
A response with status code HTTP/1.1 200 OK
may contain warnings:
<warning>Rate for 'Economy Single Room' (12345678) for 'Messerate 30 Tage CXL exkl Frühstück' (7684792) for date '2018-10-17' with price '59.0' might be too low, please check</warning>
<!-- RUID: [UmFuZG9tSVetc] -->
Warnings will not prevent a request from processing. They merely point out unexpected or unadvisable behaviour. We recommend doing whatever you can to reduce the number of warnings to zero.