Occupancy & allocation

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

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.

Occupancy information serves different purposes across the API flow.

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.

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:

{
  "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
  }
}

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

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:

{
  "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: 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.

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.

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:

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

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

For example:

{
  "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:

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.

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:

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

Each child age bracket must also satisfy:

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.

For worked examples of valid and invalid 3.3 guest combinations, see Check whether children fit the room.

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.

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.

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:

{
  "occupancy_mismatch": null
}

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

When occupancy_mismatch is not null:

1. Inform the traveller that the selected product cannot accommodate the complete guest group.
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:

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

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.

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