Learn how to interpret room occupancy rules, allocate adults and children, and validate a guest allocation 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
recommendationreturned by /accommodations/availability. - Validate the selected allocation using
occupancy_mismatchin /orders/preview.
Occupancy information serves different purposes across the API flow.
| Endpoint | Usage |
|---|---|
| /accommodations/details | Returns static information about a room, including its maximum numbers of adults and children. |
| /accommodations/availability | Checks the guests and dates in the request and returns available products with occupancy information for those results. |
| /orders/preview | Validates the exact selected products and guest allocation and reports any guests the product cannot accommodate. |
An availability response is specific to the request. Do not use it to infer whether a different guest group, or children of different ages, would fit.
For child rates and display guidance, see the Child policies guide. For worked occupancy examples, see Occupancy and allocation use cases.
In /accommodations/search and /accommodations/availability requests, provide guest details in the guests object:
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. Submit each child’s actual age; do not recategorise children as adults to work around an occupancy result.number_of_rooms— Number of rooms required.allocation— Distribution of adults and children across the requested rooms. Provide this when you want to specify which guests are assigned to each room.
For a request for two rooms, this allocation assigns two adults and two children to each room:
{
"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 room-level allocations must match the overall adult count and children’s ages in the request.
See the Search guide for more information about guest details and room allocation.
The maximum_occupancy object has different meanings depending on which endpoint returns it.
Request the rooms extra to retrieve static occupancy information for each room. A room’s maximum_occupancy object includes:
adults— Maximum number of adults for the room.children— Maximum number of children for the room.
For example:
{
"rooms": [
{
"id": "1000420",
"maximum_occupancy": {
"adults": 2,
"children": 1
}
}
]
}These values describe the room’s configured limits. They do not confirm availability for the requested dates or that every combination within the limits can be accommodated. Use /accommodations/availability for the requested guests and dates, then use /orders/preview to validate the selected product and allocation.
The maximum_occupancy object is returned for an available product. It can include:
adults— Maximum number of adults for the product.children— Child occupancy information, including allowed age ranges and the maximum number of children in each range. The child information can benull.total— Maximum number of guests for the product.
Each child age-band entry can include:
total— Maximum number of children in that age band.from_ageandto_age— The youngest and oldest ages in that band. Both ages are inclusive.free_stay— Whether children in that age band stay for free. When it isfalse, the child’s cost is already included in the returned price.
For example:
{
"maximum_occupancy": {
"adults": 2,
"children": [
{
"total": 1,
"from_age": 0,
"to_age": 5,
"free_stay": false
}
],
"total": 2
}
}In this example, maximum_occupancy.total is the overall maximum of two guests. The child entry describes the applicable child policy for its age band; it does not add a place beyond the overall guest limit. Use the product returned for the exact request and /orders/preview to confirm that the complete guest allocation fits.
The total inside a child entry is the maximum number of children covered by that age-band policy. free_stay is pricing information. The API price already reflects the child policy, so do not recalculate or add a separate child charge based only on this field.
If children is null, there are no child age-band details in the response. Children are allowed and are charged at adult rates. The response for the exact guest group and /orders/preview remain the checks for the selected product and allocation.
The adults, children, and total values describe different limits and policy information. Do not add the adult maximum and child-band counts together to calculate capacity beyond total.
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:
- Match the product's room ID with the corresponding room returned by /accommodations/details.
- Check
rooms[].maximum_occupancyto determine whether the requested children can be accommodated. - If the requested children can be accommodated, continue to /orders/preview using their actual ages.
- Check
occupancy_mismatchbefore creating the order - If the room cannot accommodate the requested guests, do not offer that product for the requested allocation. - 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.
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.
Use the recommendation when it meets your integration requirements. If you select a different product or change the guest allocation, check availability for the revised request and validate the selected allocation with /orders/preview.
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.
Before creating an accommodation order, call /orders/preview with the selected products and the exact adults and children you intend to place in each room.
Check occupancy_mismatch in the response:
allocated— Guests from the request that the product can accommodate.unallocated— Guests from the request that the product cannot accommodate.null— The complete requested allocation can be accommodated.
For example, this response shows one adult allocated and one adult unallocated:
{
"occupancy_mismatch": {
"allocated": {
"number_of_adults": 1,
"children": null
},
"unallocated": {
"number_of_adults": 1,
"children": null
}
}
}When the full allocation can be accommodated, occupancy_mismatch is null.
The occupancy_mismatch is a warning and it does not prevent /orders/preview from succeeding or block order creation.
- If an order is created while a mismatch remains, only the maximum allowed occupancy is stored in Booking.com’s systems.
- The partner or booker is responsible for handling guests who are not included in that occupancy.
When occupancy_mismatch is not null:
- Tell the traveller that the selected product cannot accommodate the full guest group.
- Let them select another product, add rooms, or revise the allocation as appropriate.
- Preview the revised order again.
- Resolve the mismatch before creating the order. If the partner and booker choose to proceed while guests remain unallocated, make clear that those guests are not included in the occupancy stored by Booking.com and are their responsibility.

- Send the complete guest group, including children’s actual ages, to /accommodations/search or /accommodations/availability.
- Use /accommodations/details when you need static room occupancy limits or cot and extra-bed information.
- Interpret availability only for the guests and dates in that request. Do not infer that additional children or children of different ages would fit.
- Use the returned
recommendationwhen it meets your integration requirements. - Submit the selected products and exact guest allocation to /orders/preview.
- If
occupancy_mismatchis notnull, revise the product or allocation and preview the order again. - Resolve any mismatch before creating the order, or ensure the partner and booker understand their responsibility for guests not included in the stored occupancy.
✅ Include children’s actual ages in search and availability requests.
✅ Use /accommodations/details for static room limits and /accommodations/availability for results tailored to the requested guests and dates.
✅ Use the recommendation object for optimal allocation for the requested guest group.
✅ Interpret child occupancy and pricing information separately.
✅ Do not infer capacity for unrequested children or different child ages from one availability response.
✅ Do not proceed with a booking when occupancy_mismatch identifies unallocated guests.
- See the Child policies guide for child rates, free stays, and cot and extra-bed policies.
- See Occupancy and allocation use cases for worked examples with different guest groups.
- Check the Occupancy Troubleshooting for learn how to resolve occupancy errors.
- See the Accommodation search guide for search requests and room allocation.