# Occupancy & allocation

**Learn how to handle guest allocation, room occupancy, and potential allocation issues using the Accommodation API collection.**

## Overview

This guide explains how to manage adults and children across the accommodation booking flow, including how to:

* Specify the requested guest group and room allocation.
* Interpret occupancy and child-rate information returned by /accommodations/availability.
* Check room occupancy configuration using /accommodations/details.
* Use the `recommendation` returned by /accommodations/availability.
* Validate the selected allocation using `occupancy_mismatch` in /orders/preview.


For practical examples covering different family groups, age ranges and occupancy configurations, see the [Occupancy and allocation use cases](/demand/docs/accommodations/occupancy-use-cases).

### Occupancy information per endpoint

Occupancy information serves different purposes across the API flow.

| Endpoint | Usage |
|  --- | --- |
| /accommodations/availability | Returns available products, pricing and child-rate information, and a recommended allocation for the requested guests. |
| /accommodations/details | Returns static room information, including the configured occupancy limits and child occupancy rules. |
| /orders/preview | Validates the exact guest allocation for the selected product before booking. |


Do not use `products[].maximum_occupancy.children` from /accommodations/availability alone to determine whether a specific group of adults and children can fit in a room.

## Guest parameters and room allocation

When calling /accommodations/search or /accommodations/availability, provide the guest information using the `guests` object.

Use:

* `number_of_adults` — Total number of adults in the request.
* `children` — Ages of all children in the request. Children are guests aged from 0 to 17.
* `number_of_rooms` — Number of rooms required.
* `allocation` — Requested distribution of adults and children across the rooms.


### Allocate guests to rooms

When requesting multiple rooms, use `allocation` to specify which adults and children you want to assign to each room.

* The totals in `allocation` should correspond to the guest group specified by `number_of_adults` and `children`.
* Always provide `children` using their actual ages. Do not convert children to adults to work around missing child-rate information.


Example of room allocation request:

```json
{
  "guests": {
    "allocation": [
      {
        "number_of_adults": 2,
        "children": [2, 10]
      },
      {
        "number_of_adults": 2,
        "children": [0, 5]
      }
    ],
    "number_of_adults": 4,
    "children": [0, 2, 5, 10],
    "number_of_rooms": 2
  }
}
```

See [Search guide](/demand/docs/accommodations/search-for-available-properties#4.-input-guest-details-and-room-allocation) for more details about specifying guests and room allocation.
For worked single-room and multi-room examples, see the [Occupancy and allocation use cases](/demand/docs/accommodations/occupancy-use-cases).

## Understand maximum occupancy

The meaning and structure of `maximum_occupancy` depends on the endpoint that returns it.

Do not treat `maximum_occupancy` from /accommodations/availability and `rooms[].maximum_occupancy` from /accommodations/details as equivalent.

### Maximum occupancy in /accommodations/availability

Each product returned by /accommodations/availability can contain `maximum_occupancy`.

This object provides **occupancy and child-rate information** associated with the available product.

The `children` entries describe the child-rate rules returned for that product, including:

* `from_age` — Youngest child age to which the rule applies.
* `to_age` — Oldest child age to which the rule applies.
* `total` — Maximum number of children to which the child-rate rule applies.
* `free_stay` — Whether children covered by this rule stay for free. If `false`, their cost is already included in the returned price.


The children entries **do not**, by themselves, define whether a particular adult and child combination can physically be accommodated in the room.

Example:

```json
{
  "maximum_occupancy": {
    "adults": 2,
    "children": [
      {
        "total": 1,
        "from_age": 0,
        "to_age": 5,
        "free_stay": true
      },
      {
        "total": 1,
        "from_age": 6,
        "to_age": 12,
        "free_stay": false
      }
    ],
    "total": 4
  }
}
```

Do not determine whether a specific guest allocation fits a room solely from `products[].maximum_occupancy.children`.

Use the `recommendation` when possible.  If you select another product, check its room occupancy limits using /accommodations/details and validate the final allocation with /orders/preview.

#### When children is null

`children: null` in /accommodations/availability is not sufficient to determine whether children are allowed in the room.

It can occur when:

* The room allows children but no applicable child-rate rule is returned for the product.
* The room does not allow children of the requested age.


If you need to select a product where `children` is `null`:

1. Match the product's room ID with the corresponding room returned by /accommodations/details.
2. Check `rooms[].maximum_occupancy` to determine whether the requested children can be accommodated.
3. If the requested children can be accommodated, continue to /orders/preview using their actual ages.
4. Check `occupancy_mismatch` before creating the order - If the room cannot accommodate the requested guests, do not offer that product for the requested allocation.
5. Use /orders/preview to validate the final allocation before creating the order.


Do not replace children with adults when `children` is `null`. Always preserve the actual guest composition and children's ages.

For practical examples, see [Handle children: null use case](/demand/docs/accommodations/occupancy-use-cases#handle-children-null).

### Check room occupancy limits

Request rooms in /accommodations/details to retrieve the static occupancy configuration for each room.

The structure of `rooms[].maximum_occupancy` differs between API versions 3.2 and 3.3.

#### Version 3.2

In version 3.2, `maximum_occupancy` provides separate maximum values for adults and children:

* `adults` — Maximum number of adults configured for the room.
* `children` — Maximum number of children configured for the room.


This information describes the room configuration rather than a particular available product or child-rate rule.

Example:

```json
{
  "rooms": [
    {
      "id": "1000420",
      "maximum_occupancy": {
        "adults": 2,
        "children": 1
      }
    }
  ]
}
```

The version 3.2 room occupancy structure does not expose age-specific occupancy rules for children. Always use /orders/preview to validate the exact adult and child allocation before booking.

#### Version 3.3

In version 3.3, `rooms[].maximum_occupancy` provides the room's main occupancy limit together with age-specific occupancy limits for children.

For example:

```json
{
  "rooms": [
    {
      "id": "1000420",
      "maximum_occupancy": {
        "occupancy_total": 3,
        "children": [
          {
            "from_age": 0,
            "to_age": 2,
            "amount": 1,
            "included_in_total": false
          },
          {
            "from_age": 3,
            "to_age": 17,
            "amount": 2,
            "included_in_total": true
          }
        ]
      }
    }
  ]
}
```

The object contains:

| Field | Usage |
|  --- | --- |
| `occupancy_total` | Maximum number of guests that count towards the room's main occupancy limit. This includes all adults and children from age brackets where `included_in_total` is `true`. |
| `children` | Age-specific occupancy limits for children. |
| `from_age` | Youngest age, inclusive, to which the occupancy rule applies. |
| `to_age` | Oldest age, inclusive, to which the occupancy rule applies. |
| `amount` | Maximum number of children within the age bracket that can be accommodated, subject to the room's main occupancy limit when `included_in_total` is `true`. |
| `included_in_total` | Whether children within the age bracket count towards `occupancy_total`. |


The `amount` field defines the maximum number of children permitted within an age bracket, not an additional allowance on top of `occupancy_total`.

* When `included_in_total` is `true`, children within that age bracket count towards `occupancy_total`. Both the age-specific limit and the main occupancy limit must be satisfied.
* When `included_in_total` is `false`, children within that age bracket do not count towards `occupancy_total`, but their number must still not exceed `amount`.


##### Interpret the 3.3 occupancy limits

To determine whether a guest allocation meets the room's occupancy limits:

1. Count all adults towards `occupancy_total`.
2. For each child, use their age to identify the applicable entry in `children`.
3. Check that the number of children within each age bracket does not exceed its `amount`.
4. For age brackets where `included_in_total` is `true`, also count those children towards `occupancy_total`.
5. Check that the number of adults plus all children who count towards `occupancy_total` does not exceed `occupancy_total`.


The main occupancy rule is:

```text
number of adults
+ number of children in age brackets where included_in_total = true
<= occupancy_total
```

Each child age bracket must also satisfy:

```text
number of children in each age bracket
<= amount for that age bracket
```

Both conditions must be satisfied for a guest allocation to meet the room's occupancy limits.

For example, a room with `occupancy_total: 3` can accommodate one adult and two children aged 3–17, provided the age-specific limits are satisfied. Children in age brackets where `included_in_total` is `false` may be accommodated in addition to the main occupancy limit, subject to their own age-specific limits.

* The child occupancy information returned by /accommodations/details describes whether children of particular ages can be accommodated in the room.
* It is different from `products[].maximum_occupancy.children` returned by /accommodations/availability, which contains child-rate information for an available product.


For worked examples of valid and invalid 3.3 guest combinations, see [Check whether children fit the room](/demand/docs/accommodations/occupancy-use-cases#check-whether-children-fit-the-room).

## Use the recommended allocation

The `recommendation` object returned in the /accommodations/availability contains the product or combination of products recommended for the guest group provided in the request.

For each recommended product:

* `number_of_adults` - Indicates the adults allocated to that product.
* `children` - Contains the ages of the children allocated to that product.


When possible, use `recommendation.products` instead of independently selecting products from the full products array.

Do not assume that every product returned in products can accommodate the requested guest group based only on its `maximum_occupancy` information.

If you select a product outside `recommendation`, check its room occupancy limits using /accommodations/details and validate the intended allocation with /orders/preview.

For an example of selecting a product outside recommendation, see the [Occupancy and allocation use cases](/demand/docs/accommodations/occupancy-use-cases).

## Validate the allocation with /orders/preview

Before creating an accommodation order, call /orders/preview with the selected product and the exact adults and children that you intend to book.

The response can include `occupancy_mismatch`, which indicates whether the requested allocation can be accommodated by the selected product.

### Occupancy mismatch

When one or more guests cannot be accommodated, `occupancy_mismatch` contains:

* `allocated` — Guests from the request that can be accommodated.
* `unallocated` — Guests from the request that cannot be accommodated.


If the complete guest allocation can be accommodated:

```json
{
  "occupancy_mismatch": null
}
```

When children cannot be accommodated, their actual ages can be returned in `unallocated.children`.

The `occupancy_mismatch` is a warning and does not prevent /orders/preview from succeeding.

**Do not create the order with a known occupancy mismatch**. Adjust the selected product or guest allocation and call /orders/preview again before proceeding.

#### Handle an occupancy mismatch

When `occupancy_mismatch` is not null:

1. Inform the traveller that the selected product cannot accommodate the complete guest group.
![occupancy mismatch example in frontend](/assets/occupancy-mismatch.ab6c454110f3dd2cdae03dc9e727c968eea041460f1698a66be78799ffbc181e.4302f616.png)
2. Allow the traveller to select another product, select additional rooms or change the room allocation where appropriate.
3. If necessary, retrieve the room occupancy limits from /accommodations/details.
4. Submit the revised allocation to /orders/preview.
5. Proceed with the booking only when `occupancy_mismatch` is null.


For example:

```json

{
  "occupancy_mismatch": {
    "allocated": {
      "number_of_adults": 1,
      "children": null
    },
    "unallocated": {
      "number_of_adults": 1,
      "children": null
    }
  }
}
```

For a worked example containing allocated and unallocated children, see [Handle an occupancy mismatch use case](/demand/docs/accommodations/occupancy-use-cases#handle-an-occupancy-mismatch).

## Recommended booking flow

For integrations that allow travellers to select products independently rather than using the recommended products, use the following flow:

1. Send the complete guest group, including children's actual ages, to /accommodations/search or /accommodations/availability.
2. Prefer the products returned in `recommendation` when they meet your integration requirements.
3. If selecting another product:
  - Do not infer child fitting rules solely from `maximum_occupancy.children` returned by /accommodations/availability.
  - Use the product's `room` ID to retrieve the corresponding room information from /accommodations/details when you need to verify its occupancy limits.
  - In version 3.3, use each child's age to identify the applicable child occupancy rule.
  - Check that the number of children in each age bracket does not exceed `amount`.
  - Count children from brackets where `included_in_total` is `true` towards `occupancy_total`.
  - Check that the adults and children who count towards `occupancy_total` do not exceed that limit.
4. Submit the selected product and exact guest allocation to /orders/preview.
5. Check `occupancy_mismatch`.
6. If `occupancy_mismatch` is not `null`, change the product or allocation and preview the order again.
7. Create the order only after validating the final guest allocation.


## Best practices

✅ Always include children’s ages in search, availability and preview requests.

✅ Respect the `maximum_occupancy` limits for adults and children.

✅ Use the `recommendation` object for optimal allocation for the requested guest group.

✅ Do not use `/accommodations/availability.products[].maximum_occupancy.children` alone to determine whether children physically fit in the room.

✅ Use /accommodations/details when you need the room's configured occupancy limits.

✅ Do not proceed with a booking when `occupancy_mismatch` identifies unallocated guests.

✅ Display relevant child policies, free stays, cots and extra-bed information when applicable.

✅ In version 3.3, check both the `amount` for each applicable child age bracket and whether those children count towards `occupancy_total`.

## References

* See [Children policies guide](/demand/docs/accommodations/child-policies) for child rates, free stays, and cots/extra beds.
* Check the different [Use cases](/demand/docs/accommodations/occupancy-use-cases) for a better understanding on how to set requests and interpret responses for family groups.
* Refer to the [Accommodation search guide](/demand/docs/accommodations/search-for-available-properties) for instructions and best practices using the accommodations/search endpoint.