Availability (B.XML)

Use this 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.

Booking.com is working towards enabling you to retrieve Property and the Currency Code.

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 Use /xml/roomrates to retrieve a list of room types for a property.
date The date(s) to which the information in the request applies. datetime Required Format: YYYY-MM-DD.
NOTE: We recommend specifying availability at least 12 months in advance. You can specify a single date with date[@value], and a range with date[@from] and date[@to]. A request may contain multiple date elements, and each element may contain combinations of [@value], [@from], and [@to] attributes.
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 first date in a date range. datetime Required Format: YYYY-MM-DD.
date[@to] Specifies the last date in a date range. datetime Required Format: YYYY-MM-DD.
NOTE: You should interpret date[@to] as "up to and not including". In other words, a request with <date from="2019-08-27" to="2019-09-02" /> will apply to all days from 27 August 2019 to 1 September 2019.
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 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). 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. 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 out 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.

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: &quot;12345678&quot;</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: &quot;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')&quot;</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.