# Create or update inventory, rates and restrictions

Use the `availability` endpoint to:

- Set adult prices by specifying room type, rate plan and date.
- Set prices for children by specifying room type, rate plan and date. Check [flexible children rates](/connectivity/docs/flexible-children-rates/managing-flexible-children-rates#sending-and-updating-children-prices-bxml).
- Set number of rooms to sell (`roomstosell`) for a room type. Note that the number of rooms applies to all rates.
- [Close a room type on a specified date.](#closing-room-type-vs-room-and-rate-combination) Even if roomrates are open, the room type is not available for booking.
- Set restrictions by specifying room type, rate plan and date.


Booking.com supports different pricing models. Ensure you're using the correct pricing approach for your property
For more information on pricing models, see [Pricing Models](/connectivity/docs/pricing-models).

## Usage recommendations

1. **Specify availability in advance**: Provide availability for at least 12 months ahead.
2. **Use Delta Updates Only**: Send only changes using the [roomRateAvailability API](/connectivity/docs/b_xml-roomrateavailability), not full refreshes.
3. **Single Hotel Per Request**: All updates must belong to one hotel only.
4. **Monthly Batching**: Break down updates by month: one month per request.
5. **Room-Rate Grouping**: Multiple room-rates can be grouped in the same request for the same hotel and month.


## Endpoint


```
POST https://supply-xml.booking.com/hotels/xml/availability
```

## Request

### Headers

| Header | Description | Type | Required | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | Required | Supports the following values:- 1.1: Current version (default) |
| `Content-Type` | Request content type | string | Required | Must be `application/xml` |


### Request body

| Element | Attribute | Description | Type | Required | Notes |
|  --- | --- | --- | --- | --- | --- |
| `request` | . | Root element. | object | Required | - |
| **>** `room` |  | Contains details about the room. | object | Required | - |
|  | `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 | Supports dates from 1 day in the past (follows Central European Time (CET) timezone) and up to 5 years in future |
|  | `value` | Specifies a single date. | datetime | Conditional | Format: `YYYY-MM-DD`.**NOTE:** You can include multiple values (`value`) in the same `date` element. |
|  | `from` | Specifies the starting date of a date range. | datetime | Conditional | Format: `YYYY-MM-DD`. Date must be before the date you specify in `to`. |
|  | `to` | Specifies the ending date of a date range, excluding the end date. | datetime | Conditional | Format: `YYYY-MM-DD`.**NOTE:** You should interpret `date[to]` as "up to and *not including*". In other words, a request with `<date from="2026-08-27" to="2029-09-02" />` applies to all days from 27 August 2026 up to and not including 2 September 2029. |
| **>>>** `currencycode` |  | Specifies the property's local [currency code](/connectivity/docs/b_xml-countrycurrencies). | enumerated string | Required | Must match the hotel's configured currency on Booking.com |
| **>>>** `rate` |  | Contains details about the rate. | object | Conditional | Required for rate level updates (e.g., `price` or restrictions).Optional for room level updates (e.g., `roomstosell`, `closed`). |
|  | `id` | The Booking.com rate ID. | integer | Optional | Use [roomrates](/connectivity/docs/room-type-and-rate-plan-management/managing-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. The number of available rooms applies across all rates including prices set using other rates for the same room type. | integer | Optional | Maximum value: `254`**NOTE:** Use `255` to indicate unlimited rooms. Values greater than `255` are automatically reset to `254`. |
| **>>>** `min_advance_res` |  | The minimum number of days and/or hours that guests must book in advance (before the planned stay date at 24:00 in the hotel timezone). | string | Optional | Format: `XDYH` where X is the number of days and Y is the number of hours. Maximum value: 360D.Examples: `4D` = four days; `4D4H` = Guest can book this stay date at least four days and four hours before the stay date. |
| **>>>** `max_advance_res` |  | The maximum number of days and/or hours that guests may book in advance (before the planned stay date at 24:00 in the hotel timezone). | string | Optional | Format: `XDYH` where X is the number of days and Y is the number of hours. Maximum value: 360D.Examples: `4D` = four days; `4D4H` = Guest can book this stay date at most four days and four hours before the stay date. |
| **>>>** `price` |  | The price for the specified combination of room, rate and date, in the property's local currency (as defined by Booking.com). | float | Optional | Format: `###.##` (always two decimals)**NOTE:**- `0` = not available- Verify you're using the correct [pricing model](/connectivity/docs/pricing-models)- Minimum and maximum price validation applies. For setting prices for children check [flexible children rates](/connectivity/docs/flexible-children-rates/managing-flexible-children-rates) |
|  | `numberofguests` | Specifies the prices for number of occupants (adults and children that are priced as adults). | integer | Optional | Maximum value is the room maximum adult occupancy. Used only for [OBP pricing model](/connectivity/docs/pricing-models#occupancy-based-pricing-obp). Verify you're using the correct [pricing model](/connectivity/docs/pricing-models) |
| **>>>** `price1` |  | Only applicable when pricing type is `standard`. The price for one person, for the specified combination of room, rate and date, 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- `0` = not available- Verify you're using the correct [pricing model](/connectivity/docs/pricing-models)- Minimum and maximum price validation applies |
| **>>>** `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).See also [Availability restrictions](/connectivity/docs/understanding-pricing-types#availability-restrictions).Closing a room does not clear 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 | Maximum value is the [maximum allowed length of stay](/connectivity/docs/enablelongstays).**NOTE:** Value must be less than `maximumstay` and `maximumstay_arrival`. See also [Availability restrictions](/connectivity/docs/understanding-pricing-types#availability-restrictions). `0` means no restriction. |
| **>>>** `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 | Maximum value is the [maximum allowed length of stay](/connectivity/docs/enablelongstays).**NOTE:** Value must be less than `maximumstay` and `maximumstay_arrival`. See also [Availability restrictions](/connectivity/docs/understanding-pricing-types#availability-restrictions). `0` means no restriction. |
| **>>>** `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 | Maximum value is the [maximum allowed length of stay](/connectivity/docs/enablelongstays).**NOTE:** Value must be greater than `minimumstay` and `minimumstay_arrival`. See also [Availability restrictions](/connectivity/docs/understanding-pricing-types#availability-restrictions). `0` means no restriction. |
| **>>>** `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 | Maximum value is the [maximum allowed length of stay](/connectivity/docs/enablelongstays).**NOTE:** Value must be greater than `minimumstay` and `minimumstay_arrival`. See also [Availability restrictions](/connectivity/docs/understanding-pricing-types#availability-restrictions). `0` means no restriction. |
| **>>>** `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 | Maximum value is the [maximum allowed length of stay](/connectivity/docs/enablelongstays).**NOTE:** See also [Availability restrictions](/connectivity/docs/understanding-pricing-types#availability-restrictions). `0` means no restriction. |
| **>>>** `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](/connectivity/docs/understanding-pricing-types#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](/connectivity/docs/understanding-pricing-types#availability-restrictions). |


### Request example

The request below specifies the following booking conditions for room type `1000202`, with rate `12345`, on 28 August, 2023:

* 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`).



```xml
<request>
  <room id="1000202">
    <date value='2023-08-28'>
      <roomstosell>1</roomstosell>
    </date>
  </room>
  <room id="1000202">
    <date value="2023-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`.

## Response

### Response body

| Field | Attribute | Description | Type | Notes |
|  --- | --- | --- | --- | --- |
| **>** `ok` |  | Indicates a successful request. | object | Only returned if there are no `errors` elements. |
| **>** `availability` |  | Root element for error responses. | object | - |
| **>>** `errors` |  | Groups a list of individual errors. | object | - |
| **>>>** `error` |  | List details of individual errors. | object | - |
|  | `code` | Returns an error code for an error. | string | See [Troubleshooting availability error responses](/connectivity/docs/b_xml-availability-troubleshooting) |
| **>>>>** `message` |  | Returns a user-friendly error message with a possible resolution to the error. | string | - |
| **>>>>** `details` |  | Contains additional error details. | object | - |
| **>>** `warnings` |  | Groups a list of individual warnings. | object | - |
| **>>>** `warning` |  | List details of individual warnings. | object | Warnings can occur even if the response contains `ok`. |
|  | `code` | Returns a warning code. | string | See [Troubleshooting availability error responses](/connectivity/docs/b_xml-availability-troubleshooting) |
| **>>>>** `message` |  | Returns a user-friendly warning message. | string | - |
| **>>>>** `details` |  | Contains additional warning details. | object | - |


### Response examples

This section contains examples of successful and unsuccessful responses. For a detailed description of all possible errors and warnings, see [Troubleshooting B.XML availability error responses](/connectivity/docs/b_xml-availability-troubleshooting).

#### Success response


```xml
<ok></ok>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXX==] -->
```

`HTTP/1.1 200 OK` does not always mean 'success'
A request can contain more than one update. When processing a request containing multiple updates with at least one invalid update, the API returns a HTTP status 200 with error response. If all updates are invalid, then the API returns a HTTP status 400 with error response.

#### Error response (HTTP 400)


```xml
<availability>
  <errors>
    <error code="NOT_A_VALID_DATE">
      <message>Dates should be in YYYY-MM-DD format, not before '2023-01-08',
        and not be past '2033-12-31'. The data should also be valid.</message>
      <details>
        <dates>2022-12-12</dates>
      </details>
    </error>
    <error code="RATE_NOT_ACTIVE_FOR_ROOM">
      <message>Rate '1234' is not active for room '4567'</message>
      <details>
        <room_ids>4567</room_ids>
        <hotel_ids>789</hotel_ids>
        <dates>2023-05-02</dates>
        <rate_ids>1234</rate_ids>
      </details>
    </error>
  </errors>
</availability>
<!-- RUID: [UmFuZG9tSVetc] -->
```

#### Partial success response (HTTP 200)

A response with status code `HTTP/1.1 200 OK` may still have errors in the body, meaning that some updates were applied successfully while others failed:


```xml
<availability>
  <errors>
    <error code="NOT_A_VALID_DATE">
      <message>Dates should be in YYYY-MM-DD format, not before '2023-01-08',
        and not be past '2033-12-31'. The data should also be valid.</message>
      <details>
        <dates>2022-12-12</dates>
      </details>
    </error>
  </errors>
</availability>
<!-- RUID: [UmFuZG9tSVetc] -->
```

#### Success response with warnings (HTTP 200)


```xml
<availability>
  <warnings>
    <warning code="WARN_TOO_LARGE_NUMBER_ROOMS_TO_SELL">
      <details>
        <hotel_ids>1234</hotel_ids>
        <room_ids>12345</room_ids>
      </details>
      <message>Changed too large number of Rooms To Sell to 254 for: 2023-10-25</message>
    </warning>
  </warnings>
</availability>
<!-- RUID: [UmFuZG9tSVetc] -->
```

Warnings will not prevent a request from processing. They merely point out unexpected or unadvisable behaviour. We recommend that you keep the number of warnings to zero.

## Additional information

### Price limits and validation

v1.0 behavior: €50,000 maximum price
The maximum price you can set for a room is €50,000 (or equivalent) per night.

### Setting availability for child rates

While setting up availability using rate IDs that are configured as [child rates](/connectivity/docs/room-type-and-rate-plan-management/managing-rate-plans#create-a-rate-relation), make sure the request doesn't set values for fields that are [configured to inherit from the parent rate plan](/connectivity/docs/room-type-and-rate-plan-management/managing-rate-plans/#parentrate).

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](/connectivity/docs/room-type-and-rate-plan-management/managing-rate-plans/#followsrestrictions) or set `price` when [`FollowsPrice` is set](/connectivity/docs/room-type-and-rate-plan-management/managing-rate-plans/#followsprice), the API returns 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`.

The above constraint does not apply to the [`FollowsClosed` restriction](/connectivity/docs/room-type-and-rate-plan-management/managing-rate-plans/#followsclosed). 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.

### 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.