# Occupancy and allocation use cases **This guide presents scenarios for group guest allocation, occupancy, and related policies, explaining how to retrieve, display, and interpret these use cases through our Demand API.** ## Overview The examples below cover common accommodation scenarios with different group sizes, age distributions, and room allocations. Each use case includes: * A request and response sample. * Explanations and best practices. These help you implement correct allocation, pricing, and occupancy handling. ## Allocation - use cases ### Single room for mixed group > Two family groups are planning a holiday in Marbella, Spain (city id -391076). They would need 1 room, for: * 2 parents with 2 children (ages 2 and 10). * 2 parents with 3 children (ages 0, 5 and 14). In this case, the travellers do not allocate guests to specific rooms but specify the need for 1 room in the `guest.number_of_rooms` field. Request Call the search endpoint including in request: - `guests.number_of_adults` - 4 - `guests.children` - specify full children ages array. - `guest.number_of_rooms` - set to 1. ```json { "booker": { ... }, "cancellation_type": "free_cancellation", "checkin": "2025-02-13", "checkout": "2025-02-16", "city": -391076, "currency": "EUR", "extras": [ "extra_charges", "products" // pass this extra, so child policy is returned in response. ], "guests": { "number_of_adults": 4, "children": [ // This is the full children ages array. 0, 2, 5, 10, 14 ], "number_of_rooms": 1 } } ``` Because no per-room allocation is provided, the `guests.allocation` field is not included in the request. Response The response will return a list of products that meet the search criteria, offering only 1 room for 4 adults and 5 children. ```json { "request_id": "01j9ntbypgq36g36k9nj6ky5na", "data": [ { "id": 14047, "currency": "EUR", "deep_link_url": "...", "price": { ... }, "products": [ { "id": "1404715_355229959_10_1_0", "children": [ 0, 2, 5, 10, 14 ], "deal": null, "number_of_adults": 4, "policies": { ... }, "price": { ... }, "total": 7160.00 } ], "room": 1404715, "third_party_inventory": false, "url": "https://www.booking.com/hotel/es/puente-romano-marbella.html?aid=xxxx&checkin=2025-02-13&checkout=2025-02-16&no_rooms=1&group_adults=4&group_children=5&age=0&age=2&age=5&age=10&age=14&selected_currency=EUR&mcid=10" } ] } ``` Show the returned `price.total` and the `maximum_occupancy` bands so users can confirm capacity and allocation rules. ### Multi-room allocation (use `allocation`) > Same group now requests multiple rooms: * Room A 2 adults + 2 children (2,10) * Room B for 2 adults and 3 children (0,5,14). Use the `guests.allocation` in accommodations/search request to specify which guests go to which room. ```json { "guests": { "allocation": [ { "number_of_adults": 2, // This is room A "children": [2, 10] }, { "number_of_adults": 2, // This is room B "children": [0, 5, 14] } ], "number_of_adults": 4, "children": [0, 2, 5, 10, 14], "number_of_rooms": 2 } } ``` #### Special requests If guests want contiguous rooms, suggest using the `special_request` field when creating the order. This allows guests to communicate with the property about their preference for room proximity. Example of order/create call with "special request": ```json { "accommodation": { "label": "Sample label", "products": [...] }, "remarks": { "estimated_arrival_time": { "hour": 12 }, "special_requests": "We would like to have the two rooms together." } } ``` For more details about special requests, see the [orders/create guide](/demand/docs/orders-api/order-preview-create#2.-/orders/create). ## Occupancy - use cases ### Single adult with children > A single-parent family with multiple children is seeking availability in a family hotel (Hotel id: 9897851) in Spain: * 1 adult + 2 children (aged 7 and 9). * 1 room. * Checkin: 2026-02-13 * Checkout: 2026-02-14 Important Ensure at least 1 adult accompanies children. Show an error if 0 adults are submitted. → Use the accommodation availability endpoint to get real-time occupancy, pricing, and allocation for the selected accommodation. Request To meet these requirements: - Include the selected `accommodation` ID to return actual availability and prices. - Specify the `guest.number_of_rooms` parameter (in this case, 1 room). - Set the `guests.number_of_adults` to include the total number of adults (in this example 1). - Use `guests.children` to list the ages of the children (7 and 9). ```json { "accommodation": 9897851, "booker": { ... }, "checkin": "2026-02-13", "checkout": "2026-02-16", "guests": { "number_of_adults": 1, "children": [7, 9], "number_of_rooms": 1 } } ``` Response The response includes the product `maximum_occupancy`: ```json { "request_id": "01j9nq390pnkt6xwbrybe23ykk", "data": { "id": 9897851, "currency": "EUR", "deep_link_url": "booking://hotel/9897851?affiliate_id=xxxx&checkin=2026-02-13&checkout=2026-02-16", "products": [ { "id": "989785112", "deal": null, "maximum_occupancy": { "adults": 2, "children": [ { "from_age": 2, "to_age": 11, "total": 2 } ], "total": 4 }, "number_available_at_this_price": 10, "policies": { ... }, "price": { ... }, "total": 280.80, "room": 989785112, "third_party_inventory": false } ] } } ``` In this example, for the product id: "989785112" the response indicates: - A maximum of 2 adults is allowed. - A maximum of 2 children, aged between 2 and 11 years (inclusive) are eligible for a child rate. - The `maximum_occupancy.total` field indicates the total number of guests allowed per product, in this case 4. This means this product is child-friendly and offers child rates for two children, if they fall within the age range (2-11). As the request included 2 children aged 7 and 9, they will be charged the child rate. For some products, the `maximum occupancy.children` field may be `null`. This indicates, the absence of child rates. ### Guest counted differently due to capacity limits **Scenario:** For the following family group: > * 2 children (4 and 8 year old). * 2 adults. * And 2 rooms. **Steps:** 1. Call the accommodations/search with guest details. Request ```json { "accommodations": [430741], "booker": { ... }, "checkin": "2025-07-27", "checkout": "2025-07-29", "guests": { "number_of_adults": 2, "children": [4, 8], "number_of_rooms": 2 } } ``` Response Among all the retrieved product ids, the one with "id": "8860603_388331868" appears to be the most suitable for the group. ```json { "request_id": "01jdhdkffff2213gf62vqraxwn", "data": [ { "products": [ { "id": "8860603_388331868", "children": [4, 8], "deal": null, "number_of_adults": 2, "policies": { ... }, "payment": { ... }, "price": { ... }, "total": 642.00, "room": 8860603, } ], "url": "https://www.booking.com/hotel/it/igea-padova.html?aid=xxxx&checkin=2025-07-27&checkout=2025-07-29&no_rooms=3&group_adults=5&group_children=3&age=1&age=4&age=8&selected_currency=EUR&mcid=10" } ] } ``` 1. Call the accommodations/availability endpoint with `guests.allocation`: Request ```json { "guests": { "allocation": [ { "number_of_adults": 1, "children": [4] }, { "number_of_adults": 1, "children": [8] } ], "number_of_adults": 2, "number_of_rooms": 2, "children": [4, 8] } } ``` Response When looking at this property's availability, for the same family group, and including allocation in the request, the response is different: For the same product block (id: 8860603_388331868): * The maximum occupancy is 3 Adults. * And only 1 child can be accommodated under the child rate (`children.total: 1`). ```json { "id": "8860603_388331868", "deal": null, "maximum_occupancy": { "adults": 3, "children": [ { "from_age": 0, "to_age": 17, "total": 1 } ], "total": 4 } } ``` If `maximum_occupancy.children[].total` is less than the number of children in your request, expect one or more children to be charged as adults (and `price.total` will reflect that). * The accommodations/search response suggests that the room can accommodate: * 2 adults + 2 children (total occupancy: 4), with a maximum of 3 adults. * However, the accommodations/availability response provides a different interpretation: * The maximum occupancy for adults is 3 + for children is 1 (total occupancy remains 4). Both endpoints apply the same restrictions on adult and child occupancy. * However, because the /search request includes 2 adults + 2 children (exceeding the maximum number of children allowed), the response adjusts by **counting 1 child as an adult** to fit the accommodation’s limitations. * It provides the result as if the total number of people is 3 adults (with 1 child counted as an adult) and 1 child in the room. > ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) **Tip:** Surface a specific message in your UI such as: “Only 1 child eligible for child rate; 1 child will be charged as an adult.” ### Maximum adults < total capacity For a group of 2 adults + 3 children, the accommodations/availability response shows: * A maximum of 4 adults + total room's maximum occupancy of 5 (Maximum occupancy > Maximum Adults). * That means the extra slot may be used by a child. * However, up to 3 children could potentially fit in this room, as long as the total occupancy limit of 5 is not exceeded. ```json { "products": [ { "id": "43074105_397810739_0_0_0", "commission": { ... }, "deal": { ... }, "maximum_occupancy": { "adults": 4, "children": [ { "total": 1, "from_age": 0, "to_age": 5, "free_stay": false } ], "total": 5 }, "number_available": 1, "policies": { ... } } ] } ``` In terms of pricing, since the `maximum_occupancy.children` is set to 1: * Only 1 child will be charged at the child rate. * The remaining 2 children will be charged as adults. > ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) **Tip:** Show both adults, children bands and total so the user understands capacity versus pricing eligibility. ### Occupancy mismatch Multi-room allocation exceeding capacity triggers occupancy_mismatch. Example of orders/preview response: ```json { "occupancy_mismatch": { "allocated": [{"room_id":123, "adults":2, "children":1}], "unallocated": [{"adults":0,"children":1}] } } ``` * Allocate guests according to maximum_occupancy to avoid preview errors. * Always reconcile /search vs /availability. ### Maximum children equal to maximum occupancy In this example: - The maximum number of adults is 4. - The `maximum_occupancy.total` is set to 5. - And the `maximum_occupancy.children` is also 5. ```json { "products": [ { "id": "43074105_397810739_0_0_0", "commission": { ... }, "deal": { ... }, "maximum_occupancy": { "adults": 4, "children": [ { "total": 5, "from_age": 0, "to_age": 12, "free_stay": false } ], "total": 5 }, "number_available": 1, "policies": { ... }, "price": { ... }, "room": 43074105, } ] } ``` Under this configuration all children will be charged child rates, as the `maximum_occupancy.children` matches the `maximum_occupancy.total`, allowing the full capacity of children to stay at the property at a special rate. ## No child rates - use cases ### Children allowed but no child rates ("children": null) When querying the [accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) endpoint for a selected accommodation, and including children in the request, the response may return products where the `maximum_occupancy.children` field is `null`. * If `maximum_occupancy.children` is `null` the **property does not expose child bands**, treat children as adults for pricing. Example of response: ```json { "id": "989785107_371605558_2_1_0", "deal": null, "maximum_occupancy": { "adults": 2, "children": null, "total": 4 } } ``` > ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) **Tip:** Make sure you indicate in your UI that children are allowed but are charged at adult price. ### "Adults-only" properties Some properties may restrict stays to adults. > When checking [availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) in an "adults only" accommodation, with children included in the guest list: - Hotel ID: 91556 - 2 adults + 2 children, aged 8 and 10 - 1 room, with no allocation. Example request: ```json { "accommodation": 91556, "booker": { ... }, "checkin": "2026-02-20", "checkout": "2026-02-25", "guests": { "number_of_rooms": 1, "number_of_adults": 2, "children": [8, 10] } } ``` Availability response may might hint that children are not accommodated, for example returning `maximum_occupancy.children: null` or/and `recommendation: null`, but these **are not guaranteed indicators** of an adults-only hotel. Important **The only reliable source of truth** that a property is adults-only is the `minimum_guest_age` field returned by the [/accommodations/details endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/details). If the `minimum_guest_age ≥ 18` the property is adults-only. Example availability response: ```json { "request_id": "01j9nns58j6mxc0htwj5wcpd3q", "data": { "id": 91556, "currency": "EUR", "deep_link_url": "booking://hotel/91556?affiliate_id=xxxx&checkin=2026-02-13&checkout=2025-02-14", "products": [ { "deal": null, "maximum_occupancy": { "adults": 3, "children": null, "total": 3 }, "number_available_at_this_price": 2, "policies": { ... }, "price": { ... }, "total": 120.00, "room": 9155610 }, { "id": "9155610_88154438_0_0_0", "commission": { ... }, "deal": null, "maximum_occupancy": { "adults": 3, ``` #### Best practices for handling adults-only properties When looking for family- friendly accommodation, and wishing to exclude "adults only" properties from your results, we recommend the following steps: 1. Call the [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) endpoint. 2. Check the `minimum_guest_age` field within the `policies` object: * This field indicates the minimum age required for to stay at the property. 3. Verify whether the minimum allowed age is 18 (children are considered to be by default between the ages of 0 and 17, inclusive). * `minimum_guest_age ≥ 18` → property is adults-only. * `minimum_guest_age < 18` → children below this age are not allowed, but the property is not classified as adults-only. * `minimum_guest_age = 0 `→ guests of any age are allowed; property is not adults-only. For example, if a property has `minimum_guest_age: 17`, you should exclude it from searches involving children: ```json { "policies": { "cots_and_extra_beds": [...], "damage": { ... }, "maximum_checkin_age": null, "minimum_checkin_age": 17, "minimum_guest_age": 17, "pets": {...} } } ``` If the `minimum_age` is set to "0", guests of any age are allowed in the property, and **the property is not classified as "adults only"**. #### Booking an "Adults-only" with children Using the [orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) endpoint to book an "Adults-only" accommodation with children included in the guest list, [returns an error](/demand/docs/support/error-handling/about-errors#children-in-adults-only-properties) indicating that children are not allowed at the property. > ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) **Tip:** To prevent such errors, filter out adults-only properties when the search includes children. ### Child age restrictions Some properties set specific age restrictions for children. For instance, a property may have a `minimum_guest_age` policy that limits the age of children allowed to stay. Example: > A family group is looking availability in an already known property in Madrid that is children-friendly. The [accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) request includes: - Accommodation id: 430741. - 2 adults. - A 2 years old child. - They need 1 room. Request Include the guests information in the request: ```json { "accommodations": [430741], "booker": { ... }, "checkin": "2025-08-27", "checkout": "2025-08-28", "guests": { "number_of_adults": 2, "children": [2], "number_of_rooms": 1 } } ``` Response Despite the property being child-friendly, the response returns: - The `maximum_occupancy.children` field as "null" in all the products - indicating no child rates are available. - And the `recommendation` field is also "null" - pointing that no suitable products match the request. ```json { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "id": 10004, "currency": "EUR", "deep_link_url": "booking://hotel/10004?affiliate_id=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!", "products": [ { "id": "43074102_88500264_0_0_0", "deal": null, "maximum_occupancy": { "adults": 2, "children": null, "total": 2 }, "number_available_at_this_price": 1, "policies": { ... }, "price": { ... } }, { "id": "43074101_403964222_0_0_0", "deal": null, "maximum_occupancy": { "adults": 2, "children": null, "total": 2 }, "number_available_at_this_price": 7, "policies": { ... }, "price": { ... } } ], "recommendation": null, "url": "https://www.booking.com/hotel/es/hostal-main-street-madrid.html?aid=956509&checkin=2025-08-27&checkout=2025-08-28&no_rooms=1&group_adults=2&group_children=1&age=2" } } ``` The reason why there are no recommendations is due to the age restrictions set by the property. ![age-restrictions](/assets/children-null.27ce64b1e5fccbdfa508f47ed214342f7de9fc9e865a945c993124e06e24c436.4302f616.png) In order to verify the applicable age restrictions set by the property: 1. Call the [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) endpoint using the same guests information and accommodation id (430741) 2. Under the `policies` object, check the `minimum_age` field in the response. ```json { "policies": { "maximum_checkin_age": null, "minimum_checkin_age": 18, "minimum_guest_age": 6, "pets": { ... } } } ``` * In this example, the minimum_age has been set to 6, therefore the 2 years old child is not allowed to stay in this property. 1. Repeat again the [accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) call for the same number of guests and accommodation but changing the children age to 6 years old. Once the child’s age is adjusted to 6, the property returns valid results with child rates (if available) and the recommendation field with the best possible options for the family group, including children. ## Free stay - use case Some properties allow children to stay free of charge. This is indicated by the `free_stay` boolean field under the policies object in the accommodations/availability response. > *A family with 2 adults and 1 child (aged 4) checks availability. The room has a child band (0-5) and free_stay:true.* Request ```json { "accommodation": 27635, "booker": { "country": "nl", "platform": "desktop" }, "checkin": "2025-09-10", "checkout": "2025-09-12", "guests": { "number_of_adults": 2, "children": [4], "number_of_rooms": 1 } } ``` Response ```json { "request_id": "01abcxyz...", "data": { "id": 27635, "currency": "EUR", "products": [ { "id": "2763504_400123456_0_0_0", "maximum_occupancy": { "adults": 2, "children": [ { "total": 1, "from_age": 0, "to_age": 5, "free_stay": true } ], "total": 3 }, "price": { "book": 320.00, "total": 320.00 } } ] } } ``` In this case: * The product exposes the child band under `products[].maximum_occupancy.children[]` with `free_stay: true`. * The child aged 4 falls into the 0–5 band and up to `total: 1` child in that band is eligible for free stay. * The `price.total` already reflects the free stay. ## Cots and extra beds To retrieve information about cots and extra beds, you should call the [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) endpoint and specify the `extras` parameter with the rooms option. Cribs and extra bed deprecated The "cribs and extra beds" option is deprecated. Use "cots_and_extra_beds" instead. Request Use the following filters in your request: - Accommodation id - Extra parameter: "rooms" to retrieve the room details. ```json { "accommodations": [27635], "extras": ["rooms"], "languages": ["en-gb"] } ``` Response The response will include details about the availability of cots and extra beds under the `policies` object, including: * The age range to which cots and extra beds are available (The interval is inclusive). * "Mode" indicates whether the extra cost is per night or per stay. * The "Price" that applies to the selected type (cot and/or extra bed). ```json { "policies": { "cots_and_extra_beds": [ { "age": { "from": 0, "to": 2 }, "mode": "per_night", "price": 0, "type": "cot" } ] } } ``` In this example, a cot is available for children aged from 0 to 2 at no extra charge. * Under the `rooms` object, you can also see the cots and extra beds availability per room: ```json { "rooms": [ { "id": 2763504, "name": { "en-gb": "Superior Queen Room" }, "attributes": [ ... ], "bed_options": [ ... ], "cots_and_extra_beds": { "are_allowed_together": false, "maximum_number_of_cots": 1, "maximum_number_of_extra_beds": 0 }, "maximum_occupancy": { "adults": 2, "children": 1, "total_guests": 3 }, "number_of_rooms": { ... }, "room_type": 9, "size": 19 } ] } ``` ## Best practices for occupancy and allocation ✅ Always capture request/response for debugging. ✅ Verify allocation vs `maximum_occupancy` for adults and children. ✅ Handle `occupancy_mismatch` gracefully. ✅ Show clear pricing messages when guests exceed allowed slots. ✅ Cross-check /search vs /availability before confirming bookings. * See the [child policies](/demand/docs/accommodations/occupancy-use-cases) section - For detailed information on occupancy, allocation for child rate policies. * Refer to the [Troubleshooting section](/demand/docs/accommodations/occupancy-troubleshooting) - To identify and solve possible errors. * Check the [Accommodation search guide](/demand/docs/accommodations/search-for-available-properties) - For best practices on using the accommodation search and availability endpoints.