# 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.


1. **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.
2. **Check consistency across endpoints**
  * Compare results from /search and /availability.
  * Ensure `allocation` in the request matches the recommendation, especially for multi-room bookings.
3. **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.


See [Use cases](/demand/docs/accommodations/occupancy-use-cases) for more details.

## 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.

* See the [child policies](/demand/docs/accommodations/occupancy-use-cases) section - For detailed information on occupancy, allocation, and child rate policies.
* Check the [Accommodation search guide](/demand/docs/accommodations/search-for-available-properties) - For best practices on using the accommodation search and availability endpoints.