# 4.1 FreeRooms: Room Availability Notifications

When `action=OTA_HotelInvCountNotif:FreeRooms`, the client sends room availability updates to the server. Servers must support at least one capability: `OTA_HotelInvCountNotif_accept_rooms` (distinct rooms) or `OTA_HotelInvCountNotif_accept_categories` (room categories); they may support both.

## 4.1.1 Client Request (`OTA_HotelInvCountNotifRQ`)

- The payload is a single `OTA_HotelInvCountNotifRQ` with exactly one `Inventories` element, so only one hotel is covered per request. `HotelCode` is mandatory; `HotelName` is optional.
- Example (outer structure):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelInvCountNotifRQ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xmlns="http://www.opentravel.org/OTA/2003/05"
                          Version="4"
                          xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelInvCountNotifRQ.xsd">
  <UniqueID Type="16" ID="1" Instance="CompleteSet"/>
  <Inventories HotelCode="123" HotelName="Frangart Inn">
    <!-- ... Inventory elements ... -->
  </Inventories>
</OTA_HotelInvCountNotifRQ>
```

- `Inventories` contains one or more `Inventory` elements, each for a distinct period/room or period/category. Example inner portion:

```xml
<Inventory>
  <StatusApplicationControl Start="2022-08-01" End="2022-08-10" InvTypeCode="DOUBLE" />
  <InvCounts>
    <InvCount CountType="2" Count="3" />
  </InvCounts>
</Inventory>
<Inventory>
  <StatusApplicationControl Start="2022-08-11" End="2022-08-20" InvTypeCode="DOUBLE" />
</Inventory>
<Inventory>
  <StatusApplicationControl Start="2022-08-21" End="2022-08-30" InvTypeCode="DOUBLE" />
  <InvCounts>
    <InvCount CountType="2" Count="1" />
  </InvCounts>
</Inventory>
```

- Missing `InvCode` means the availability refers to a room category (`InvTypeCode`). Using both `InvTypeCode` and `InvCode` targets a specific room. Matching is case-sensitive. Mixing rooms and categories in one request is not allowed.
- `InvCounts` may contain up to three `InvCount` entries (all absolute, not deltas):
  - `CountType=2`: bookable rooms (must be supported).
  - `CountType=6`: out of order rooms (requires `OTA_HotelInvCountNotif_accept_out_of_order`).
  - `CountType=9`: available but not bookable rooms (requires `OTA_HotelInvCountNotif_accept_out_of_market`).
- Omitted `InvCount` entries imply `Count=0`. If `InvCounts` is omitted, the room/room category is considered fully booked for the period. `Count` is non-negative; for specific rooms it should be `1`. Sum of counts cannot exceed the total rooms; overbooking is not allowed.
- Date ranges are inclusive of the start and end nights (checkout is the morning after `End`). Inventory periods must not overlap for the same room or room category; servers may reject overlaps.

### CompleteSet

- Purpose: replace all server-held availability for the hotel with the provided data (e.g., first sync or resync after issues).
- Server capability required: `OTA_HotelInvCountNotif_accept_complete_set`.
- Indicate a complete set with `UniqueID Instance="CompleteSet" Type="16"` (the `ID` value is ignored). `Type="35"` is also accepted and can be used to hint that data was purged by business rules.
- A CompleteSet must list every managed room/room category for all periods the client has on record. Even fully booked periods must be present (with `InvCounts` showing zero or omitted entirely).
- To fully reset availability, a CompleteSet may contain a single empty `Inventory` element with no attributes (needed for OTA validation).
- Do not include periods for which the client has no data source.

### Deltas

- If `UniqueID` is missing, the message is a delta: the server updates only what is present and leaves all other stored data untouched.
- Server capability required: `OTA_HotelInvCountNotif_accept_deltas`.
- If a delta explicitly covers an entire period, it overwrites the prior state for that period.
- AlpineBits recommends periodic full CompleteSet syncs when both sides support them. A server should expose at least one of the delta or complete-set capabilities; without CompleteSet support, obsolete data might require manual cleanup.

### Closing Seasons

- Indicates periods when the hotel is closed (distinct from fully booked). Requires both parties to expose `OTA_HotelInvCountNotif_accept_closing_seasons`.
- Can only appear as the first `Inventory` elements in a CompleteSet.
- Structure: one `StatusApplicationControl` with mandatory `Start`, `End`, and `AllInvCode="true"`; no `InvCounts` allowed. Multiple closing periods are allowed if they do not overlap with each other or with availability periods.
- Delta messages supersede earlier closed periods; best practice is to avoid such overlaps or follow deltas with a CompleteSet to restate closures explicitly.

## 4.1.2 Server Response (`OTA_HotelInvCountNotifRS`)

- Responses return one of the four AlpineBits outcomes (success, advisory, warning, error). The payload is `OTA_HotelInvCountNotifRS`. See section 2.3 for outcome semantics.

## 4.1.3 Implementation Tips and Best Practice

- Support for FreeRooms was mandatory in version 2011-11 but is optional now.
- Delta updates were added in 2013-04.
- The action was completely rewritten in 2020-10.
- Forwarders (e.g., channel managers) must not add data beyond what the source provided; do not extend time frames beyond the most future date received.
- For CompleteSet requests, servers are encouraged to delete and reinsert all backend availability rather than perform partial updates.
- The `End` date is the last night of stay; departure is the morning after `End`.
- Length-of-stay and day-of-arrival restrictions were removed from FreeRooms in 2014-04 (they belong in RatePlans).

## 4.1.4 Tabular Representation of `OTA_HotelInvCountNotifRQ`

| Level | Element/Attribute | Type | Cardinality |
| --- | --- | --- | --- |
| OTA_HotelInvCountNotifRQ | element |  | 1 |
| OTA_HotelInvCountNotifRQ | Version |  | 1 |
| OTA_HotelInvCountNotifRQ | UniqueID | element | 0-1 |
| UniqueID | Type | enum (16 \| 35) | 1 |
| UniqueID | ID |  | 1 |
| UniqueID | Instance | enum (CompleteSet) | 1 |
| OTA_HotelInvCountNotifRQ | Inventories | element | 1 |
| Inventories | HotelCode | string(1-16) | 1 |
| Inventories | HotelName | string(1-128) | 0-1 |
| Inventories | Inventory | element | 1..∞ |
| Inventory | StatusApplicationControl | element | 0-1 |
| StatusApplicationControl | Start | date (\\S+) | 1 |
| StatusApplicationControl | End | date (\\S+) | 1 |
| StatusApplicationControl | InvTypeCode | string(1-8) | 0-1 |
| StatusApplicationControl | InvCode | string(1-16) | 0-1 |
| StatusApplicationControl | AllInvCode | boolean (\\S+) | 0-1 |
| Inventory | InvCounts | element | 0-1 |
| InvCounts | InvCount | element | 1-3 |
| InvCount | CountType | enum (2 \| 6 \| 9) | 1 |
| InvCount | Count | integer ([0-9]+) | 1 |

## 4.1.5 Tabular Representation of `OTA_HotelInvCountNotifRS`

| Level | Element/Attribute | Type | Cardinality |
| --- | --- | --- | --- |
| OTA_HotelInvCountNotifRS | element |  | 1 |
| OTA_HotelInvCountNotifRS | Version |  | 1 |
| OTA_HotelInvCountNotifRS | TimeStamp |  | 0-1 |
| OTA_HotelInvCountNotifRS | Success | element (choice start) | 1 |
| OTA_HotelInvCountNotifRS | Warnings | element (choice start) | 0-1 |
| Warnings | Warning | element | 1..∞ |
| Warning | Type | integer ([0-9]+) | 1 |
| Warning | RecordID | string(1-64) | 0-1 |
| Warning | Status | enum (ALPINEBITS_SEND_HANDSHAKE \| ALPINEBITS_SEND_FREEROOMS \| ALPINEBITS_SEND_RATEPLANS \| ALPINEBITS_SEND_INVENTORY) | 0-1 |
| OTA_HotelInvCountNotifRS | Errors | element (choice end) | 1 |
| Errors | Error | element | 1..∞ |
| Error | Type | enum (11 \| 13) | 1 |
| Error | Code | integer ([0-9]+) | 0-1 |
| Error | Status | enum (ALPINEBITS_SEND_HANDSHAKE \| ALPINEBITS_SEND_FREEROOMS \| ALPINEBITS_SEND_RATEPLANS \| ALPINEBITS_SEND_INVENTORY) | 0-1 |