Use this guide to diagnose differences in occupancy, guest allocation, child pricing, free stays, and order preview results.
- Reproduce the request. Keep the request body, endpoint, timestamp, request ID, and response together.
- Check the guest details. Confirm the adult count, each child’s actual age, number of rooms, and room-level
allocation. If comparing search and availability results, check that the dates, guest ages, room count, accommodation IDs, and allocation are the same. - Inspect the availability response for the exact request. Review the returned products,
maximum_occupancy, child age bands, and price. Availability is specific to the requested guests and dates. - Check static room and property rules. Use /accommodations/details to review
rooms[].maximum_occupancy,policies.minimum_guest_age, and cot or extra-bed options. - Validate the selected product. Call /orders/preview with the exact selected product IDs and room-level guest allocation. Check
occupancy_mismatchin each product’s response.
For request and response examples, see Occupancy and allocation use cases. For child-rate and free-stay information, see the Child policies guide.
The endpoints return occupancy information for different purposes:
| Field or response | How to use it |
|---|---|
rooms[].maximum_occupancy in /accommodations/details | Static room limits for adults and children. The details response does not provide the availability response’s age-band information. |
maximum_occupancy in /accommodations/availability | Request-specific product information. adults is the adult limit, total is the overall guest limit, and children contains age-band child-policy information or is null. |
recommendation in /accommodations/availability | Suggested product allocation for the search criteria. Each product can include its allocated adults and children. |
occupancy_mismatch in /orders/preview | A warning that identifies guests who can be accommodated and guests who remain unallocated. |
In the availability response:
maximum_occupancy.totalis the maximum number of guests for the room. It is based on guests using existing beds; cot and extra-bed options are separate.maximum_occupancy.adultsis the maximum number of adults for the room.maximum_occupancy.childrencan benullor contain age bands. Each band can includetotal,from_age,to_age, andfree_stay. The age-band count describes the child policy for that band; it does not add places beyondmaximum_occupancy.total.- Children must be accompanied by at least one adult. The number of children cannot exceed
maximum_occupancy.totalminus one. - Ages in
from_ageandto_ageare inclusive.free_stayindicates whether children in that age band stay free of charge. The returned API price already reflects free stays, so use the returned price rather than recalculating child charges.
If maximum_occupancy.children is null, children are allowed but no child-rate bands are returned. They are charged at adult rates. Check the overall total and the product returned for the requested guest group; children: null does not mean that the room has no capacity for children.
When a request includes more children than a child band covers, additional children may be counted or charged as adults. This does not increase the room’s overall total capacity.
Check the product’s adults and total values, the child age bands, and the preview result together.
Symptom: maximum_occupancy.children is null, or a child is not covered by a returned age band, and the child is priced as an adult.
Likely cause: The product has no child-rate band for the requested age, or the number of children exceeds the number covered by the applicable band.
Resolution:
- Match each child’s actual age to the returned
from_ageandto_agerange. - Check the band’s
totalto see how many children it covers. - Use the returned product price. Do not create your own child-rate calculation.
- If
childrenisnull, explain that children are allowed but are charged at adult rates.
Symptom: The availability response does not contain a suitable product or recommended allocation for the requested ages and room allocation.
Likely causes:
- The property’s minimum guest age excludes one or more travellers.
- No product is available for the requested dates, room count, ages, or allocation.
- The requested group exceeds the occupancy limits for the available products.
Resolution:
- Check
policies.minimum_guest_agein the /accommodations/details response. The value is the minimum age, inclusive, for staying at the property. A value of0allows guests of any age; a value of18means guests under 18 are not allowed. - Check the products and occupancy information returned by /accommodations/availability for the exact guest group and dates.
- If a property rule excludes a traveller, select another property that can accommodate the complete group. Do not omit a traveller or change their age to obtain a result.
- If the property age rule permits the group, check the dates, room count, allocation, and product availability before diagnosing the issue as an age restriction.
minimum_guest_age is a property-level stay restriction. Do not confuse it with minimum_checkin_age, which applies to the age required to check in.
Symptom: Search returns an accommodation, but the availability response shows a different adult or child allocation, child-rate eligibility, or price.
Likely cause: Search identifies accommodation candidates, while availability returns products for the requested dates and guest group.
In some v3.2 cases, children beyond the applicable child band may be counted or priced as adults. The child band and the room’s overall guest capacity describe different limits.
Resolution:
- Confirm that both requests use the same dates, number of rooms, guest ages, accommodation IDs, and room allocation.
- Use the availability response to inspect each returned product’s
maximum_occupancy.adults,maximum_occupancy.children, andmaximum_occupancy.total. - Treat child age-band information as child-policy information. Do not add its count to
maximum_occupancy.totalas extra capacity. - Validate the exact product and guest allocation with /orders/preview before order creation.
Symptom: A child’s age matches a band with free_stay: true, but your interface shows an additional charge.
Likely causes:
- The child’s age was matched to the wrong band.
- The number of children covered by the band’s
totalhas been exceeded. - The integration recalculates or adds a charge instead of displaying the API price.
Resolution:
- Match each child to a band using their actual age and the inclusive
from_ageandto_agevalues. - Apply the band’s
free_stayinformation only to the children covered by that band’stotal. - Display the returned price. API prices already account for free child stays;
free_stayis for explaining the policy to travellers.
Symptom: /orders/preview returns an occupancy_mismatch object with allocated and unallocated guests.
Likely cause: The selected product or room-level allocation cannot accommodate every requested guest.
Resolution:
- Review
allocatedandunallocatedto identify which guests fit and which do not. - Check the selected product’s occupancy information and the guest allocation for each room.
- Offer another product, additional rooms, or a revised allocation, as appropriate.
- Call /orders/preview again with the updated products and allocation.
occupancy_mismatch is a warning, not a blocking preview error.
- If an order is created while the 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.
- Resolve the mismatch where possible; if the partner and booker choose to proceed, clearly explain this responsibility.
When all requested guests fit, occupancy_mismatch is null.
Symptom: /orders/preview returns an error response rather than an occupancy_mismatch object.
Resolution:
- Diagnose the actual error code and message. Do not treat
occupancy_mismatchas an error; it is a response warning. - Confirm that the request uses valid product IDs and the expected request structure.
- Check the guest ages and allocation against the selected products.
- Review property-level age restrictions in /accommodations/details.
- If the error persists with a valid request, retain the request ID and response details for investigation.
Symptom: orders/preview returns an error when children are included.
Likely cause: The property is flagged as “adults only” (minimum_guest_age: 18).
Resolution: Verify if the property is flagged as "adults only" (minimum_guest_age: 18). Exclude adults-only properties when children are present in the request.
- Send every child’s actual age in search and availability requests.
- Use availability to assess products for the requested dates and guest group; do not assume search results guarantee that a specific product can accommodate the group.
- Use /accommodations/details for static room limits, minimum guest age, and cot or extra-bed options.
- Distinguish overall occupancy limits from child age-band and free-stay information.
- Use the API’s returned prices instead of recalculating child charges.
- Treat the recommendation as a suggestion for the request, and validate the exact selected products and allocation with /orders/preview.
- Review and resolve
occupancy_mismatchbefore creating an order where possible.
- See Occupancy and allocation for the v3.2 occupancy flow and response interpretation.
- See Occupancy and allocation use cases for worked examples, including children counted or priced as adults.
- See the Child policies guide for child rates, free stays, and cot and extra-bed policies.
- See the Accommodation search guide for request parameters and room allocation.