Occupancy and allocation troubleshooting

Use this guide to diagnose and resolve issues with guest allocation, occupancy limits, child rates, free stays, and booking preview warnings.

Quick triage steps

1. Reproduce the request:

• Capture request body, endpoint, and timestamp.

2. Inspect the accommodations/availability response — the authoritative source for occupancy and pricing:

   • Check maximum_occupancy fields for adults and children.
   • Verify from_age / to_age bands for children (if present)
   • Confirm free_stay flags match expectations.
   • Check price.total reflects the correct calculation.

3. Check consistency across endpoints

   • Compare results from /search and /availability.
   • Ensure allocation in the request matches the recommendation, especially for multi-room bookings.

4. Review booking previews (/orders/preview)

   • Inspect occupancy_mismatch object if returned.
   • Check policies.minimum_guest_age and other restrictions.
   • Display warnings or errors to travellers if the allocation exceeds room limits, or children are not allowed in selected products.

Common problems and resolutions

Guests treated differently than expected

Symptom: The maximum_occupancy.children field is null. Children appear in the request but are priced as adults.

Likely cause: The property does not provide specific child rates.

Resolution: Show the total price and inform users that child rates are not available for this property.

No products returned for children under a certain age

Symptom: The API returns "recommendation": null, even though the property accepts children.

Likely cause: The property enforces an age restriction for guests.

Resolution: Check the minimum_guest_age in the /accommodations/details response. Adjust the request to only include children above the allowed age.

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.

Occupancy mismatch at preview

Symptom: orders/preview returns the occupancy_mismatch object with allocated and unallocated values.

Likely cause: Requested allocation exceeds room capacity.

Resolution:

• Inspect the occupancy_mismatch object:

  • allocated — guests accommodated.
  • unallocated — guests exceeding capacity.

• Display clear warnings to users.

• Adjust allocation or allow travellers to select additional rooms or a different product.

Inconsistent occupancy interpretation

Symptom: accommodations/search shows availability, but /availability rejects the same allocation.

Likely cause: The number of children exceeds the allowed child slots, so one or more children are counted as adults.

Resolution: Cross-check maximum_occupancy rules in the accommodations/availability response. If the number of children exceeds the allowed child slots, the API may count one or more children as adults. Always confirm against /availability before confirming a booking.

Free stay not applied as expected

Symptom: free_stay: true appears in the response, but the child is still shown as charged.

Likely cause: The number of children exceeds the band’s total allowance. Extra children in the band are priced as chargeable.

Resolution: Ensure your logic assigns children to bands in order, up to the band’s total. Always display price.total from the API — do not recalculate.

Best practices for troubleshooting

✅ Capture request/response for debugging.

✅ Validate allocation against maximum_occupancy and recommendation.

✅ Handle occupancy_mismatch gracefully in your UI.

✅ Display clear messages about free stays, child rates, and allocation limits.

✅ Always cross-check multi-room allocation to prevent preview errors.