Use these examples to understand how to submit guest groups, interpret room and child-policy information, and validate the products selected for an accommodation order.
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.
Occupancy information has a different purpose at each step of the accommodation flow:
| Endpoint | Use it to |
|---|---|
| /accommodations/search | Find accommodation properties for the requested guests, dates, and search criteria. |
| /accommodations/availability | Check products, prices, and request-specific occupancy information for selected properties. |
| /accommodations/details | Retrieve static room limits, property age policies, and cot or extra-bed information. |
| /orders/preview | Validate selected products with the exact guest allocation and identify any guests who remain unallocated. |
- The
maximum_occupancyfields in availability include the adult limit, the overall guest limit, and child age-band information. - The overall
totalcounts adults and children staying in existing beds; cot and extra-bed options are separate. - Children must be accompanied by at least one adult, so their number cannot exceed
totalminus one. - Child age bands describe the number of children covered by a child policy and whether they stay for free. They do not provide capacity beyond the overall
totallimit.
For a field-by-field explanation, see the Occupancy and allocation guide. For child-rate and free-stay details, see the Child policies guide.
A family travelling to Marbella, Spain, needs one room for three adults and two children aged 2 and 10. Include the complete guest group and the number of rooms in the search request:
{
"booker": {
"country": "gb",
"platform": "desktop"
},
"checkin": "2027-05-13",
"checkout": "2027-05-16",
"city": -391076,
"currency": "EUR",
"guests": {
"number_of_adults": 3,
"children": [2, 10],
"number_of_rooms": 1
}
}Because only one room is requested, you do not need to provide guests.allocation. Always submit children using their actual ages. Do not convert children to adults to make an allocation fit.
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 which guests are assigned to each room. The adults, children, and number of rooms in the allocation must match the overall guest details:
{
"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
}
} Use the same guest composition and room-level allocation when checking availability and previewing selected products.
Allocation specifies which guests are assigned to each room.
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."
}
}
Special requests are preferences and are subject to the property's confirmation. See the orders/create guide for more information.
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:
| Value | Meaning |
|---|---|
0 | Guests of any age can stay at the property. |
1 to 17 | Guests younger than the specified age cannot stay at the property. |
18 or higher | Guests younger than the specified age cannot stay. For a value of 18, children aged 0–17 are not allowed. |
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.
minimum_guest_age is different from minimum_checkin_age.
minimum_guest_age defines the minimum age of guests who may stay at the property. minimum_checkin_age defines the minimum age required to check in.
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.
Note: A request containing children must include at least one adult.
Consider a family looking for one room for:
- 1 adult
- 2 children aged 7 and 9.
→ Call /accommodations/availability using the complete guest group.
{
"accommodations": [9897851],
"booker": {
"country": "gb",
"platform": "desktop"
},
"checkin": "2027-05-13",
"checkout": "2027-05-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.
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.
The details response does not provide age-specific child limits.
Use availability for the requested dates and guests, then use /orders/preview to validate the selected product and exact allocation.
A product returned by /accommodations/availability can contain children: null:
{
"maximum_occupancy": {
"adults": 2,
"children": null,
"total": 4
}
}In this response, no child-rate bands are returned.
Children are allowed but are charged at adult rates.
The
totalfield still limits the number of guests who can stay in the room;children: nulldoes not create additional room capacity.Keep the requested children’s actual ages.
Use the product returned for the requested guest group and validate the selected product with /orders/preview.
Do not interpret
children: nullas an adults-only restriction; checkpolicies.minimum_guest_agein /accommodations/details for the property’s minimum age.
The recommendation object in the availability response contains products recommended for the search criteria. Each recommended product can include its ID, the number of adults allocated to it, and the ages of the children allocated to it:
{
"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]
}
]
}
}Use the recommended products when they meet your integration requirements. If your integration allows the traveller to select another product from products:
- Use the selected product’s
roomID to find its room in /accommodations/details. - Review the room’s static occupancy limits and relevant property policies.
- Submit the selected product and the actual guest allocation to /orders/preview.
- Check
occupancy_mismatchbefore creating the order.
Do not rely on the recommendation’s presence as a substitute for validating a different product and allocation.
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:
- Do not assume that the product fits the requested guests based only on
maximum_occupancyreturned by /accommodations/availability. - Use its
roomID to retrieve the corresponding room from /accommodations/details. - Check the room occupancy limits.
- In version 3.3, apply the
occupancy_total,amountandincluded_in_totalrules. - Submit the selected product and actual guest allocation to /orders/preview.
- Check
occupancy_mismatchbefore 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:
- Inform the traveller that the selected product cannot accommodate the complete guest group.
- Allow them to select another product, add another room or change the allocation where appropriate.
- Submit the revised allocation to /orders/preview.
- Proceed only when
occupancy_mismatchisnull.
occupancy_mismatch does not prevent /orders/preview from succeeding. Do not create the order with a known occupancy mismatch.
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
}
}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: trueindicates that a child covered by this rule stays free of charge.- The returned product price already accounts for the applicable child pricing.
free_stay describes pricing. It does not by itself indicate whether the child fits the room. Use the room occupancy information from /accommodations/details when you need to check fitting rules.
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_bedsprovides age and pricing information.rooms[].cots_and_extra_bedsprovides room-level limits.
In this example:
- The cot applies to children aged 0–2, inclusive.
mode: per_nightmeans 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: falsemeans cots and extra beds cannot be used together when both types are otherwise available.
Use policies.cots_and_extra_beds to understand the applicable age and pricing rules, and rooms[].cots_and_extra_beds to understand the room-level limits.
These fields should be interpreted together with the room's maximum_occupancy.
For integrations that allow travellers to select accommodation products independently, use the following flow:
- Send the complete guest group to /accommodations/search, including the actual ages of all children.
- Call /accommodations/availability for the selected accommodation.
- Prefer the products returned in
recommendationwhen they meet your integration requirements. - If selecting another product:
- Use its
roomID 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,amountandincluded_in_total.
- Use its
- Submit the selected product and exact guest allocation to /orders/preview.
- Check
occupancy_mismatch. - If any guests are unallocated, change the product or allocation and call /orders/preview again.
- Create the order only after validating the final guest allocation.
- See the Occupancy & allocation guide for details about occupancy fields and the recommended integration flow.
- See the Children policies guide for child rates, free stays, cots and extra beds.
- Refer to the Troubleshooting section to identify and solve possible errors.
- Check the Accommodation search guide for best practices when using /accommodations/search and /accommodations/availability.