Skip to content
Last updated

Occupancy and allocation troubleshooting v3.2

Use this guide to diagnose differences in occupancy, guest allocation, child pricing, free stays, and order preview results.


Quick triage

  1. Reproduce the request. Keep the request body, endpoint, timestamp, request ID, and response together.
  2. 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.
  3. 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.
  4. Check static room and property rules. Use /accommodations/details to review rooms[].maximum_occupancy, policies.minimum_guest_age, and cot or extra-bed options.
  5. Validate the selected product. Call /orders/preview with the exact selected product IDs and room-level guest allocation. Check occupancy_mismatch in 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.

Understand the occupancy fields

The endpoints return occupancy information for different purposes:

Field or responseHow to use it
rooms[].maximum_occupancy in /accommodations/detailsStatic room limits for adults and children. The details response does not provide the availability response’s age-band information.
maximum_occupancy in /accommodations/availabilityRequest-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/availabilitySuggested product allocation for the search criteria. Each product can include its allocated adults and children.
occupancy_mismatch in /orders/previewA warning that identifies guests who can be accommodated and guests who remain unallocated.

In the availability response:

  • maximum_occupancy.total is 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.adults is the maximum number of adults for the room.
  • maximum_occupancy.children can be null or contain age bands. Each band can include total, from_age, to_age, and free_stay. The age-band count describes the child policy for that band; it does not add places beyond maximum_occupancy.total.
  • Children must be accompanied by at least one adult. The number of children cannot exceed maximum_occupancy.total minus one.
  • Ages in from_age and to_age are inclusive. free_stay indicates 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.


Common problems and resolutions

Children are priced as adults

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_age and to_age range.
  • Check the band’s total to see how many children it covers.
  • Use the returned product price. Do not create your own child-rate calculation.
  • If children is null, explain that children are allowed but are charged at adult rates.

No suitable product is returned for the requested guest group

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:

  1. Check policies.minimum_guest_age in the /accommodations/details response. The value is the minimum age, inclusive, for staying at the property. A value of 0 allows guests of any age; a value of 18 means guests under 18 are not allowed.
  2. Check the products and occupancy information returned by /accommodations/availability for the exact guest group and dates.
  3. 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.
  4. 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.

Search and availability appear to interpret children differently

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:

  1. Confirm that both requests use the same dates, number of rooms, guest ages, accommodation IDs, and room allocation.
  2. Use the availability response to inspect each returned product’s maximum_occupancy.adults, maximum_occupancy.children, and maximum_occupancy.total.
  3. Treat child age-band information as child-policy information. Do not add its count to maximum_occupancy.total as extra capacity.
  4. Validate the exact product and guest allocation with /orders/preview before order creation.

A free stay is not displayed as free

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 total has 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_age and to_age values.
  • Apply the band’s free_stay information only to the children covered by that band’s total.
  • Display the returned price. API prices already account for free child stays; free_stay is for explaining the policy to travellers.

occupancy_mismatch is returned by order preview

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:

  1. Review allocated and unallocated to identify which guests fit and which do not.
  2. Check the selected product’s occupancy information and the guest allocation for each room.
  3. Offer another product, additional rooms, or a revised allocation, as appropriate.
  4. 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.

Order preview returns an API error

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_mismatch as 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.

Booking attempt blocked at preview

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.


Best practices

  • 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_mismatch before creating an order where possible.

References