# 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 interpret room occupancy rules and manage guest allocation in Booking.com’s Demand API. It covers:

* Maximum occupancy per room (`maximum_occupancy`)
* Recommended guest allocation (`recommendation`)
* Allocation warnings (`occupancy_mismatch`)
* Best practices for multi-room and mixed-age bookings.


**This guide applies to both adults and children**, ensuring partners can handle allocation consistently. For children specific rates and policies

## Guest parameters and room allocation

When making search or availability requests, always include:

* `guest.number_of_adults` — Number of adults.
* `guest.children` — Ages of all children.
* `guest.number_of_rooms` — Number of rooms.
* `allocation` — Distribution of adults and children per room.


Example allocation for 2 rooms:


```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
  }
}
```

### Room allocation

When booking multiple rooms, use `allocation` field, to assign adults/children to each room.


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

## Maximum occupancy

Use the `maximum_occupancy` object from the availability or accommodations/details (with "rooms" in request) response to determine:

* How many guests a room can accommodate (adults + children)
* The maximum number of adults.
* Which children are eligible for child rates.


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
  }
}
```

Children must always be accompanied by at least one adult. The number of children cannot exceed total - 1.
And, if `"children": null`, children are allowed but pay adult rates.

## Recommended allocation

The recommendation object returned in the availability response provides the **best guest distribution** per room:

* Allocates adults and children efficiently across multiple rooms.
* Helps ensure that occupancy rules are respected.
* Returns `null` if no suitable products are available.


Example:


```json
{
  "recommendation": {
    "price": {...},
    "total": 2140.4,
    "products": [
      {
        "id": "1000426_95127794_3_2_0",
        "children": [2],
        "number_of_adults": 1,
        "price": {...}
      },
      {
        "id": "1000434_95127794_1_2_0",
        "children": [4],
        "number_of_adults": 1,
        "price": {...}
      }
    ]
  }
}
```

## Occupancy mismatch

The `occupancy_mismatch` object is returned by /orders/preview when the requested guest allocation exceeds the room’s capacity.

This preview warning allows you to review and adjust the booking before confirming it.

This object contains:

* `allocated` — guests that can be accommodated in the room.
* `unallocated` — guests that cannot be accommodated.


If all guests fit in the room, `occupancy_mismatch` is `null`.

Example:


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

Explanation:

* The room can host 1 adult.
* 1 adult cannot be accommodated.


If all guests fit the room capacity, `occupancy_mismatch` is returned as:

`"occupancy_mismatch": null`

The `occupancy_mismatch` is a preview warning. It does not block the request, but requires action before creating the order.
If the traveller chooses to proceed despite a mismatch, only the maximum allowed occupancy is stored in our systems. Any extra guests are the responsibility of the booker/partner.

### Recommended integration behaviour

When `occupancy_mismatch` is returned:

1. Inform the traveller that the selected room cannot accommodate all guests:


![occupancy mismatch example in frontend](/assets/occupancy-mismatch.ab6c454110f3dd2cdae03dc9e727c968eea041460f1698a66be78799ffbc181e.4302f616.png)

1. Allow them to:
  * Select additional rooms, or
  * Choose a different product.
2. Verify the room `maximum_occupancy` if needed.
3. Call orders/preview again with the updated allocation before confirming the booking.


## Best practices

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

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

✅ Use the `recommendation` object for optimal allocation.

✅ Handle `occupancy_mismatch` gracefully and provide clear warnings.

✅ Display occupancy-specific details such as cots, extra beds, and free child stays at room level.

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