Despegar.com - Hotels, flights, packages, cars, and more!

## Update Availability and Restrictions

**URL**: ```/v1/hotels/availability/update```

### Goals

To update in the extranet and in the website the availability and restrictions for the room/rate plan requested of a specific property in a set period of time.

### Notes

#### Allotment or Restrictions

Since allotment is defined at the room-level while restrictions are defined
at the room-rate plan-level, an `AvailStatusMessage` element may indicate either 
allotment or restrictions, exclusively.

For allotment, the `AvailStatusMessage` element will include `@BookingLimit` and 
`@BookingLimitMessageType` attributes, and contain a `StatusApplicationControl` element
without `@RatePlanCode` attribute.

```xml
<OTA_HotelAvailNotifRQ xmlns="http://www.despegar.com/hotels/ota/v1/" Version="1.0">
    <AvailStatusMessages HotelCode="282445">
        <AvailStatusMessage BookingLimit="10" BookingLimitMessageType="SetLimit">
            <StatusApplicationControl Start="2020-01-01" End="2020-01-02" InvCode="74959" />
        </AvailStatusMessage>
    </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>
```

For restrictions, the `AvailStatusMessage` element will contain a 
`StatusApplicationControl` element including `@Start`, `@End`, `@RatePlanCode`, 
and `@InvCode` attributes. The `AvailStatusMessage` element will also include 
`LengthsOfStay` and/or `RestrictionStatus` elements.

#### Meaning of the @BookingLimit Attribute

The value of the `@BookingLimit` attribute represents the total flexible allotment for a 
room, which is not the same as the inventory available to sell.

Please refer to [Get Inventory](/portal/documentation/get-inventory) for details on how to compute this value.

#### <a name="interpretation"></a>Interpretation of <abbr title="Close to Arrival">CTA</abbr> / <abbr title="Close to Departure">CTD</abbr> / Stop-Sell

Due to the way the OTA specification is modeled, there is a particular interpretation 
of the values in the `RestrictionStatus` element that needs to be performed by 
the client.
 
When setting restrictions, the `RestrictionStatus` element can define only one of
CTA, CTD, or stop-sell, and there can only be one `RestrictionStatus` element within
a `AvailStatusMessage` element. If the channel needs to define several restrictions, it will
have to repeat the `AvailStatusMessage` element. The extra elements must not repeat
all the values, but just include `StatusApplicationControl` and `RestrictionStatus`.

Mind that the `@Restriction` and `@Status` attributes work together for CTA 
and CTD. **The semantic when reading restrictions is [different](/portal/documentation/get-avail-restr#interpretation)**.

##### Examples

All the examples set <abbr title="Length of Stay">LOS</abbr> to show how other restrictions work together.

* Set CTA.

* Set CTA, CTD, and stop-sell.

```xml
<OTA_HotelAvailNotifRQ xmlns="http://www.despegar.com/hotels/ota/v1/" Version="1.0">
    <AvailStatusMessages HotelCode="282445">
        <AvailStatusMessage>
            <StatusApplicationControl Start="2020-01-01" End="2020-01-02" RatePlanCode="27" InvCode="74959" />
            <LengthsOfStay>
                <LengthOfStay Time="3" TimeUnit="Day" MinMaxMessageType="MinLOS" />
                <LengthOfStay Time="60" TimeUnit="Day" MinMaxMessageType="MaxLOS" />
            </LengthsOfStay>
            <RestrictionStatus Restriction="Arrival" Status="Close" />
        </AvailStatusMessage>
        <AvailStatusMessage>
            <StatusApplicationControl Start="2020-01-02" End="2020-01-03" RatePlanCode="27" InvCode="74959" />
            <RestrictionStatus Restriction="Departure" Status="Close" />
        </AvailStatusMessage>
        <AvailStatusMessage>
            <StatusApplicationControl Start="2020-01-02" End="2020-01-03" RatePlanCode="27" InvCode="74959" />
            <RestrictionStatus Status="Close" />
        </AvailStatusMessage>
    </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>
```

* Remove CTA and stop-sell restrictions. Set CTD.

```xml
<OTA_HotelAvailNotifRQ xmlns="http://www.despegar.com/hotels/ota/v1/" Version="1.0">
    <AvailStatusMessages HotelCode="282445">
        <AvailStatusMessage>
            <StatusApplicationControl Start="2020-01-01" End="2020-01-02" RatePlanCode="27" InvCode="74959" />
            <LengthsOfStay>
                <LengthOfStay Time="3" TimeUnit="Day" MinMaxMessageType="MinLOS" />
                <LengthOfStay Time="60" TimeUnit="Day" MinMaxMessageType="MaxLOS" />
            </LengthsOfStay>
            <RestrictionStatus Restriction="Arrival" Status="Open" />
        </AvailStatusMessage>
        <AvailStatusMessage>
            <StatusApplicationControl Start="2020-01-02" End="2020-01-03" RatePlanCode="27" InvCode="74959" />
            <RestrictionStatus Restriction="Departure" Status="Close" />
        </AvailStatusMessage>
        <AvailStatusMessage>
            <StatusApplicationControl Start="2020-01-02" End="2020-01-03" RatePlanCode="27" InvCode="74959" />
            <RestrictionStatus Status="Open" />
        </AvailStatusMessage>
    </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>
```

### Message Detail

#### Input: OTA_HotelAvailNotifRQ

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| OTA_HotelAvailNotifRQ                         |   1    | Root element |
| OTA_HotelAvailNotifRQ / AvailStatusMessages   |   1    | Contains the availability and restriction messages |
| @HotelCode                                    |   1    | The code for the hotel whose availability is being updated|
| AvailStatusMessages / AvailStatusMessage      |  1..n  | Each AvailabilityStatusMessage contains the information regarding the units and type of update (status, number of units, available units) in a date range. |
| @BookingLimit                                 |  0..1  | Flexible allotment. This value is the number of rooms available to sell plus the booking count. Refer to [Get Inventory](/portal/documentation/get-inventory) to find out more on how to compute this value. |
| @BookingLimitMessageType                      |  0..1  | Possible values: <ul><li> AdjustLimit: Adjusts flexible allotment by `BookingLimit`. A positive number will add, while a negative will subtract. </li><li> SetLimit: Sets flexible allotment to `BookingLimit`. </li></ul> |
| AvailStatusMessage / StatusApplicationControl |   1    | Contains specific information regarding room availability |
| @RatePlanCode                                 |  0..1  | Identifier code of the rate plan. Mandatory for restrictions. Must be clear for allotment. |
| @InvCode                                      |   1    | Room identifier code. |
| @Start                                        |   1    | Data request start date (inclusive).|
| @End                                          |   1    | Data request end date (exclusive).|
| LengthsOfStay / LengthOfStay                  | 0..1   | Used to inform the length of stay. |
| @MinMaxMessageType                            |   1    | Used to indicate the minimum and maximum LOS that applies. Possible values: <ul><li> SetMinLOS: Define the minimum length of stay. </li><li> Define the maximum length of stay. </li></ul>|
| @TimeUnit                                     |   1    | Time unit used to apply this status message to other inventory. Values: year, month, week, day, hour, minute, second. We only use day.|
| AvailStatusMessages / RestrictionStatus       | 0..1   | Indicates restrictions like stop sell, CTA and CTD |
| @Status                                       |   1    | Possible values: <ul><li> Close: Inventory not available for sale. </li><li> Open: Inventory available for sale. </li><li> The "Status" attribute alone, without the "Restriction" attribute defined, operates as a restriction for the room and defines if a room can be booked or not. (If its opened or closed) </li></ul>|
| @Restriction                                  | 0..1   | Possible values: <ul><li> Arrival - Applies only for the day of arrival </li><li> Departure - Applies only for the day of departure </li></ul>|

#### Output: OTA_HotelAvailNotifRS

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| OTA_HotelAvailNotifRS                         |   1    | Root element |
| @Version                                      |   1    | Service version |
| OTA_HotelAvailNotifRS / Success               |  0..1  | It is present if the request has been processed successfully. The error node is not present if this node appears. |
| OTA_HotelAvailNotifRS / Errors                |  0..1  | Contains an error list in case the request was not processed correctly. |
| Errors / Error                                |  1..n  | If there is an error node then there has to exist at least one error node. The element will contain the error text. |
| @Type                                         |   1    | Error type |
| @Code                                         |  0..1  | Error code |
| OTA_HotelAvailNotifRS / Warnings              |  0..1  | Contains a warning list in case the request was processed partially. |
| Warnings / Warning                            |  1..n  | If there is a warnings node then there has to exist at least one warning node. The element will contain the warning text. |
| @Type                                         |   1    | Warning type |
| @Code                                         |  0..1  | Warning code |