Occupancy and allocation use cases

Explore common guest allocation and occupancy scenarios and learn how to interpret them across the accommodation booking flow.

This guide provides practical examples for handling adults and children across different room and occupancy configurations.

Use these examples together with the Occupancy & allocation guide, which explains how occupancy information is represented across the API.

The examples cover:

• Allocating adults and children across one or more rooms.
• Selecting products for families with children.
• Interpreting child-rate information from /accommodations/availability.
• Checking room occupancy limits using /accommodations/details.
• Handling cases where no child-rate information is returned.
• Handling age restrictions and adults-only properties.
• Identifying allocation problems using occupancy_mismatch.
• Retrieving information about free stays, cots and extra beds.
• Interpreting the version 3.3 age-specific occupancy model.

Consider a family group travelling together and looking for one room in Marbella, Spain (city ID -391076):

• 3 adults and 2 children aged 2 and 10.

If you do not need to specify how guests are distributed across multiple rooms, provide the complete guest group and number_of_rooms.

{
  "booker": {
    "country": "gb",
    "platform": "desktop"
  },
  "checkin": "2026-11-13",
  "checkout": "2026-11-16",
  "city": -391076,
  "currency": "EUR",
  "guests": {
    "number_of_adults": 3,
    "children": [2, 10],
    "number_of_rooms": 1
  }
}

Suppose the traveller requests two rooms with the following distribution:

• Room 1 — 2 adults and children aged 2 and 10.
• Room 2 — 2 adults and children aged 0, 5 and 14.

Use guests.allocation in the /accommodations/search request to specify the requested distribution:

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

The complete guest group must correspond to the guests distributed through allocation.

Use the same guest composition when checking availability and when previewing the selected products.

Guest allocation determines who stays in each room. It does not guarantee that multiple rooms are physically next to each other.

If travellers want adjoining or nearby rooms, submit this as a special request when creating the order:

Example of orders/create call with "special request":

{
  "accommodation": {
    "label": "Sample label",
    "products": [...]
  },
  "remarks": {
    "estimated_arrival_time": {
      "hour": 12
    },
    "special_requests": "We would like to have the two rooms together."
  }
}

Some properties do not allow children.

Do not use maximum_occupancy.children: null to identify an adults-only property. This value alone is not sufficient to determine whether children are prohibited.

Use policies.minimum_guest_age from /accommodations/details.

For example:

{
  "policies": {
    "minimum_checkin_age": 18,
    "minimum_guest_age": 18
  }
}

Interpret minimum_guest_age as follows:

For example, if:

{
  "minimum_guest_age": 18
}

the property does not allow guests younger than 18.

If minimum_guest_age is 18 or higher and the traveller's guest group includes children aged 0–17, do not offer the property for that group.

A property does not have to be adults-only to impose an age restriction.

For example:

{
  "policies": {
    "minimum_guest_age": 6
  }
}

A child aged 2 cannot stay at this property, while a child aged 6 or older meets this property-level age restriction.

If a search or availability request contains a child who does not meet minimum_guest_age, do not infer the restriction from maximum_occupancy.children or recommendation.

Check the property policy directly using /accommodations/details.

Consider a family looking for one room for:

• 1 adult
• 2 children aged 7 and 9.

→ Call /accommodations/availability using the complete guest group.

{
  "accommodation": 9897851,
  "booker": {
    "country": "gb",
    "platform": "desktop"
  },
  "checkin": "2026-11-13",
  "checkout": "2026-11-16",
  "guests": {
    "number_of_adults": 1,
    "children": [7, 9],
    "number_of_rooms": 1
  }
}
  

When you need to determine whether a particular combination of adults and children fits a room, use the room information returned by /accommodations/details.

The structure differs between versions 3.2 and 3.3.

In version 3.2, a room can return:

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

This indicates that the room is configured for a maximum of:

• 2 adults.
• 1 child.

Version 3.2 does not expose age-specific room occupancy rules for children.

Use /orders/preview with the actual guest allocation to validate the selected product before booking.

Version 3.3 provides age-specific child occupancy rules in /accommodations/details, allowing partners to determine whether a specific combination of adults and children meets a room's occupancy limits.

Consider a room with the following occupancy limits:

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

For this room:

• Up to three guests can count towards the main occupancy limit (occupancy_total).
• All adults count towards this limit.
• Up to one child aged 0–2 can be accommodated without counting towards the main occupancy limit.
• Up to two children aged 3–17 can be accommodated, provided the main occupancy limit is not exceeded.

The following examples demonstrate how different guest combinations satisfy or exceed these limits.

When validating a guest allocation, partners must check both the main occupancy limit and the age-specific child limits.

1. Check the main occupancy limit

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

2. Check each child age bracket

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

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

For example, a room may allow up to two children aged 3–17, but this does not mean that two children can always be accommodated in addition to the requested adults. Their combined number must also remain within occupancy_total.

Conversely, children in age brackets where included_in_total is false may be accommodated in addition to the main occupancy limit, provided their age-specific limit is not exceeded.

A product returned by /accommodations/availability can contain:

{
  "maximum_occupancy": {
    "adults": 2,
    "children": null,
    "total": 4
  }
}

• Do not assume that children: null means either that children are prohibited or that they should be treated as adults.
• children: null means that no applicable child-rate information is returned for the product. This value alone does not indicate whether the requested children can be accommodated.

If you want to select a product where children is null:

1. Use the product's room ID to identify the corresponding room in /accommodations/details.
2. Check rooms[].maximum_occupancy.
3. Determine whether the requested adults and children meet the room occupancy limits.
4. Continue to /orders/preview using the children's actual ages.
5. Check occupancy_mismatch before creating the order.

For version 3.3, use the child's age to identify the applicable children entry and apply its amount and included_in_total rules.

Suppose /accommodations/availability returns several products for an accommodation.

The recommendation identifies the product or combination of products selected for the requested guest allocation.

{
  "recommendation": {
    "products": [
      {
        "id": "1000426_95127794_3_2_0",
        "number_of_adults": 1,
        "children": [2]
      },
      {
        "id": "1000434_95127794_1_2_0",
        "number_of_adults": 1,
        "children": [4]
      }
    ]
  }
}

Prefer the products returned in recommendation when they meet your integration requirements.

If your integration allows travellers to select another product from the complete products array:

1. Do not assume that the product fits the requested guests based only on maximum_occupancy returned by /accommodations/availability.
2. Use its room ID to retrieve the corresponding room from /accommodations/details.
3. Check the room occupancy limits.
4. In version 3.3, apply the occupancy_total, amount and included_in_total rules.
5. Submit the selected product and actual guest allocation to /orders/preview.
6. Check occupancy_mismatch before creating the order.

Suppose a traveller selects a product for:

• 2 adults.
• 2 children aged 5 and 12.

When you call /orders/preview using that exact allocation, the response can indicate that not all guests can be accommodated:

{
  "occupancy_mismatch": {
    "allocated": {
      "number_of_adults": 2,
      "children": [5]
    },
    "unallocated": {
      "number_of_adults": 0,
      "children": [12]
    }
  }
}

This means:

• Both adults can be accommodated.
• The child aged 5 can be accommodated.
• The child aged 12 cannot be accommodated by the selected product.

Do not convert the unallocated child to an adult.

Instead:

1. Inform the traveller that the selected product cannot accommodate the complete guest group.
2. Allow them to select another product, add another room or change the allocation where appropriate.
3. Submit the revised allocation to /orders/preview.
4. Proceed only when occupancy_mismatch is null.

Some products provide a free stay for children within a particular child-rate band.

For example, a family requests:

• 2 adults.
• 1 child aged 4.
• 1 room.

An available product can return:

{
  "maximum_occupancy": {
    "adults": 2,
    "children": [
      {
        "total": 1,
        "from_age": 0,
        "to_age": 5,
        "free_stay": true
      }
    ],
    "total": 3
  },
  "price": {
    "...": "..."
  }
}

In this example:

• The child aged 4 falls within the 0–5 child-rate band.
• Up to one child can use this child-rate rule.
• free_stay: true indicates that a child covered by this rule stays free of charge.
• The returned product price already accounts for the applicable child pricing.

Cots and extra beds are separate from the room's standard occupancy configuration.

Use /accommodations/details to retrieve both property-level policies and room-level limits.

Request the relevant additional information from /accommodations/details:

{
  "accommodations": [27635],
  "extras": [
    "policies",
    "rooms"
  ]
}

A property can return:

{
  "policies": {
    "cots_and_extra_beds": [
      {
        "age": {
          "from": 0,
          "to": 2
        },
        "mode": "per_night",
        "price": 0,
        "type": "cot"
      }
    ]
  }
}

• policies.cots_and_extra_beds provides age and pricing information.
• rooms[].cots_and_extra_beds provides room-level limits.

In this example:

• The cot applies to children aged 0–2, inclusive.
• mode: per_night means the price is applied per night.
• The cot is available at no additional charge.

The room information indicates how many cots or extra beds can be added:

{
  "rooms": [
    {
      "id": "2763504",
      "cots_and_extra_beds": {
        "are_allowed_together": false,
        "maximum_number_of_cots": 1,
        "maximum_number_of_extra_beds": 0
      }
    }
  ]
}

In this example:

• A maximum of one cot can be added.
• Extra beds cannot be added.
• are_allowed_together: false means cots and extra beds cannot be used together when both types are otherwise available.

For integrations that allow travellers to select accommodation products independently, use the following flow:

1. Send the complete guest group to /accommodations/search, including the actual ages of all children.
2. Call /accommodations/availability for the selected accommodation.
3. Prefer the products returned in recommendation when they meet your integration requirements.
4. If selecting another product:
   • Use its room ID to retrieve the corresponding room from /accommodations/details.
   • Check minimum_guest_age.
   • Check the room's maximum_occupancy.
   • In version 3.3, apply occupancy_total, amount and included_in_total.
5. Submit the selected product and exact guest allocation to /orders/preview.
6. Check occupancy_mismatch.
7. If any guests are unallocated, change the product or allocation and call /orders/preview again.
8. Create the order only after validating the final guest allocation.