{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-demand/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","tabs","tab"]},"type":"markdown"},"seo":{"title":"Occupancy and allocation use cases v3.2","siteUrl":"https://developers.booking.com"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"occupancy-and-allocation-use-cases-v32","__idx":0},"children":["Occupancy and allocation use cases ",{"$$mdtype":"Tag","name":"span","attributes":{"style":{"backgroundColor":"#0070C9","color":"white","fontSize":"0.8rem","padding":"0.2rem 0.5rem","borderRadius":"4px"}},"children":["v3.2"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use these examples to understand how to submit guest groups, interpret room and child-policy information, and validate the products selected for an accommodation order."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide provides practical examples for handling adults and children across different room and occupancy configurations."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use these examples together with the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/demand/docs/accommodations/v3.2/occupancy-allocation"},"children":["Occupancy & allocation guide"]},", which explains how occupancy information is represented across the API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The examples cover:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Allocating adults and children across one or more rooms."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Selecting products for families with children."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Interpreting child-rate information from /accommodations/availability."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Checking room occupancy limits using /accommodations/details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handling cases where no child-rate information is returned."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handling age restrictions and adults-only properties."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Identifying allocation problems using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occupancy_mismatch"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retrieving information about free stays, cots and extra beds."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"differences-between-endpoints","__idx":2},"children":["Differences between endpoints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Occupancy information has a different purpose at each step of the accommodation flow:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use it to"},"children":["Use it to"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/accommodations/search"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Find accommodation properties for the requested guests, dates, and search criteria."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/accommodations/availability"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check products, prices, and request-specific occupancy information for selected properties."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/accommodations/details"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retrieve static room limits, property age policies, and cot or extra-bed information."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/orders/preview"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validate selected products with the exact guest allocation and identify any guests who remain unallocated."]}]}]}]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maximum_occupancy"]}," fields in availability include the adult limit, the overall guest limit, and child age-band information."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The overall ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," counts adults and children staying in existing beds; cot and extra-bed options are separate."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Children must be accompanied by at least one adult, so their number cannot exceed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," minus one."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Child age bands describe the number of children covered by a child policy and whether they stay for free. They do not provide capacity beyond the overall ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," limit."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a field-by-field explanation, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/demand/docs/accommodations/v3.2/occupancy-allocation"},"children":["Occupancy and allocation guide"]},". For child-rate and free-stay details, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/demand/docs/accommodations/child-policies"},"children":["Child policies guide"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"allocate-guests-to-rooms","__idx":3},"children":["Allocate guests to rooms"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"search-for-one-room-for-a-mixed-group","__idx":4},"children":["Search for one room for a mixed group"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A family travelling to Marbella, Spain, needs one room for three adults and two children aged 2 and 10. Include the complete guest group and the number of rooms in the search request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"booker\": {\n    \"country\": \"gb\",\n    \"platform\": \"desktop\"\n  },\n  \"checkin\": \"2027-05-13\",\n  \"checkout\": \"2027-05-16\",\n  \"city\": -391076,\n  \"currency\": \"EUR\",\n  \"guests\": {\n    \"number_of_adults\": 3,\n    \"children\": [2, 10],\n    \"number_of_rooms\": 1\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because only one room is requested, you do not need to provide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guests.allocation"]},"."," ","Always submit children using their actual ages. Do not convert children to adults to make an allocation fit."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"allocate-guests-across-multiple-rooms","__idx":5},"children":["Allocate guests across multiple rooms"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Suppose the traveller requests two rooms with the following distribution:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Room 1 — 2 adults and children aged 2 and 10."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Room 2 — 2 adults and children aged 0, 5 and 14."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guests.allocation"]}," in the /accommodations/search request to specify which guests are assigned to each room. The adults, children, and number of rooms in the allocation must match the overall guest details:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"guests\": {\n    \"allocation\": [\n      {\n        \"number_of_adults\": 2,\n        \"children\": [2, 10]\n      },\n      {\n        \"number_of_adults\": 2,\n        \"children\": [0, 5, 14]\n      }\n    ],\n    \"number_of_adults\": 4,\n    \"children\": [0, 2, 5, 10, 14],\n    \"number_of_rooms\": 2\n  }\n}  \n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the same guest composition and room-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allocation"]}," when checking availability and previewing selected products."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Allocation specifies which guests are assigned to each room."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-rooms-close-together","__idx":6},"children":["Request rooms close together"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Guest allocation determines who stays in each room. It does not guarantee that multiple rooms are physically next to each other."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If travellers want adjoining or nearby rooms, submit this as a special request when creating the order:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of orders/create call with \"special request\":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"accommodation\": {\n    \"label\": \"Sample label\",\n    \"products\": [...]\n  },\n  \"remarks\": {\n    \"estimated_arrival_time\": {\n      \"hour\": 12\n    },\n    \"special_requests\": \"We would like to have the two rooms together.\"\n  }\n}\n\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Special requests are preferences and are subject to the property's confirmation. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/demand/docs/orders-api/order-preview-create#2.-/orders/create"},"children":["orders/create guide"]}," for more information."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-adults-only-properties","__idx":7},"children":["Handle adults-only properties"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some properties do not allow children."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maximum_occupancy.children: null"]}," to identify an adults-only property. This value alone is not sufficient to determine whether children are prohibited."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["policies.minimum_guest_age"]}," from /accommodations/details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"policies\": {\n    \"minimum_checkin_age\": 18,\n    \"minimum_guest_age\": 18\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Interpret ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimum_guest_age"]}," as follows:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Guests of any age can stay at the property."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["17"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Guests younger than the specified age cannot stay at the property."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["18"]}," or higher"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Guests younger than the specified age cannot stay. For a value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["18"]},", children aged 0–17 are not allowed."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, if:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"minimum_guest_age\": 18\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["the property does not allow guests younger than 18."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimum_guest_age"]}," is 18 or higher and the traveller's guest group includes children aged 0–17, do not offer the property for that group."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimum_guest_age"]}," is different from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimum_checkin_age"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimum_guest_age"]}," defines the minimum age of guests who may stay at the property. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimum_checkin_age"]}," defines the minimum age required to check in."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"property-with-another-minimum-guest-age","__idx":8},"children":["Property with another minimum guest age"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A property does not have to be adults-only to impose an age restriction."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"policies\": {\n    \"minimum_guest_age\": 6\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A child aged 2 cannot stay at this property, while a child aged 6 or older meets this property-level age restriction."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a search or availability request contains a child who does not meet ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimum_guest_age"]},", do not infer the restriction from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maximum_occupancy.children"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommendation"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the property policy directly using /accommodations/details."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"interpret-child-rate-information","__idx":9},"children":["Interpret child-rate information"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note: A request containing children must include at least one adult."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"product-with-child-rates","__idx":10},"children":["Product with child rates"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consider a family looking for one room for:"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["1 adult"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["2 children aged 7 and 9."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["→ Call /accommodations/availability using the complete guest group."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Accommodation availability request","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"accommodations\": [9897851],\n  \"booker\": {\n    \"country\": \"gb\",\n    \"platform\": \"desktop\"\n  },\n  \"checkin\": \"2027-05-13\",\n  \"checkout\": \"2027-05-16\",\n  \"guests\": {\n    \"number_of_adults\": 1,\n    \"children\": [7, 9],\n    \"number_of_rooms\": 1\n  }\n}\n  \n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Response","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A product may return child age-band information like this:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"1000420_358188572_2_0_0\",\n  \"room\": \"1000420\",\n  \"maximum_occupancy\": {\n    \"adults\": 2,\n    \"children\": [\n      {\n        \"total\": 2,\n        \"from_age\": 2,\n        \"to_age\": 11,\n        \"free_stay\": false\n      }\n    ],\n    \"total\": 4\n  }\n}      \n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This response indicates that:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The child policy applies to children aged 2–11, inclusive."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The age band covers up to two children."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["free_stay: false"]}," means the children do not stay for free; their cost is already included in the returned price."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The product’s overall maximum occupancy is four guests. The child band does not add places beyond ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both children in this request fall within the age band. Use the returned product price; do not calculate child charges separately."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the number of children exceeds the count covered by a child band, additional children may be counted or charged as adults. Keep their actual ages in the request and use the product’s ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adults"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," limits, the response to the exact guest request, and order preview to assess the allocation."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"check-static-room-occupancy-limits","__idx":11},"children":["Check static room occupancy limits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you need to determine whether a particular combination of adults and children fits a room, use the room information returned by /accommodations/details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In version 3.2, a room can return:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"1000420\",\n  \"maximum_occupancy\": {\n    \"adults\": 2,\n    \"children\": 1\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This indicates that the room is configured for a maximum of:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["2 adults."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["1 child."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The details response does not provide age-specific child limits."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use availability for the requested dates and guests, then use /orders/preview to validate the selected product and exact allocation."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-children-null","__idx":12},"children":["Handle ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["children: null"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A product returned by /accommodations/availability can contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["children: null"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"maximum_occupancy\": {\n    \"adults\": 2,\n    \"children\": null,\n    \"total\": 4\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this response, no child-rate bands are returned."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Children are allowed but are charged at adult rates."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," field still limits the number of guests who can stay in the room; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["children: null"]}," does not create additional room capacity."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the requested children’s actual ages."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the product returned for the requested guest group and validate the selected product with /orders/preview."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not interpret ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["children: null"]}," as an adults-only restriction; check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["policies.minimum_guest_age"]}," in /accommodations/details for the property’s minimum age."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-the-recommended-allocation","__idx":13},"children":["Use the recommended allocation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommendation"]}," object in the availability response contains products recommended for the search criteria. Each recommended product can include its ID, the number of adults allocated to it, and the ages of the children allocated to it:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"recommendation\": {\n    \"products\": [\n      {\n        \"id\": \"1000426_95127794_3_2_0\",\n        \"number_of_adults\": 1,\n        \"children\": [2]\n      },\n      {\n        \"id\": \"1000434_95127794_1_2_0\",\n        \"number_of_adults\": 1,\n        \"children\": [4]\n      }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the recommended products when they meet your integration requirements. If your integration allows the traveller to select another product from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["products"]},":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the selected product’s ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["room"]}," ID to find its room in /accommodations/details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Review the room’s static occupancy limits and relevant property policies."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit the selected product and the actual guest allocation to /orders/preview."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occupancy_mismatch"]}," before creating the order."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not rely on the recommendation’s presence as a substitute for validating a different product and allocation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-a-product-outside-recommendation","__idx":14},"children":["Handle a product outside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommendation"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Suppose /accommodations/availability returns several products for an accommodation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommendation"]}," identifies the product or combination of products selected for the requested guest allocation."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"recommendation\": {\n    \"products\": [\n      {\n        \"id\": \"1000426_95127794_3_2_0\",\n        \"number_of_adults\": 1,\n        \"children\": [2]\n      },\n      {\n        \"id\": \"1000434_95127794_1_2_0\",\n        \"number_of_adults\": 1,\n        \"children\": [4]\n      }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Prefer the products returned in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommendation"]}," when they meet your integration requirements."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your integration allows travellers to select another product from the complete ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["products"]}," array:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not assume that the product fits the requested guests based only on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maximum_occupancy"]}," returned by /accommodations/availability."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["room"]}," ID to retrieve the corresponding room from /accommodations/details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check the room occupancy limits."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In version 3.3, apply the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occupancy_total"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["included_in_total"]}," rules."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit the selected product and actual guest allocation to /orders/preview."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occupancy_mismatch"]}," before creating the order."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-an-occupancy-mismatch","__idx":15},"children":["Handle an occupancy mismatch"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Suppose a traveller selects a product for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["2 adults."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["2 children aged 5 and 12."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you call /orders/preview using that exact allocation, the response can indicate that not all guests can be accommodated:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"occupancy_mismatch\": {\n    \"allocated\": {\n      \"number_of_adults\": 2,\n      \"children\": [5]\n    },\n    \"unallocated\": {\n      \"number_of_adults\": 0,\n      \"children\": [12]\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This means:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Both adults can be accommodated."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The child aged 5 can be accommodated."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The child aged 12 cannot be accommodated by the selected product."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not convert the unallocated child to an adult."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instead:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Inform the traveller that the selected product cannot accommodate the complete guest group."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Allow them to select another product, add another room or change the allocation where appropriate."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit the revised allocation to /orders/preview."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Proceed only when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occupancy_mismatch"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occupancy_mismatch"]}," does not prevent /orders/preview from succeeding. Do not create the order with a known occupancy mismatch."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-a-free-child-stay","__idx":16},"children":["Handle a free child stay"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some products provide a free stay for children within a particular child-rate band."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, a family requests:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["2 adults."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["1 child aged 4."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["1 room."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An available product can return:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"maximum_occupancy\": {\n    \"adults\": 2,\n    \"children\": [\n      {\n        \"total\": 1,\n        \"from_age\": 0,\n        \"to_age\": 5,\n        \"free_stay\": true\n      }\n    ],\n    \"total\": 3\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The child aged 4 falls within the 0–5 child-rate band."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Up to one child can use this child-rate rule."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["free_stay: true"]}," indicates that a child covered by this rule stays free of charge."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The returned product price already accounts for the applicable child pricing."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["free_stay"]}," describes pricing. It does not by itself indicate whether the child fits the room. Use the room occupancy information from /accommodations/details when you need to check fitting rules."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-cots-and-extra-beds","__idx":17},"children":["Handle cots and extra beds"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cots and extra beds are separate from the room's standard occupancy configuration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use /accommodations/details to retrieve both property-level policies and room-level limits."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"check-cot-and-extra-bed-policies","__idx":18},"children":["Check cot and extra-bed policies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Request the relevant additional information from /accommodations/details:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"accommodations\": [27635],\n  \"extras\": [\n    \"policies\",\n    \"rooms\"\n  ]\n}\n\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A property can return:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"policies\": {\n    \"cots_and_extra_beds\": [\n      {\n        \"age\": {\n          \"from\": 0,\n          \"to\": 2\n        },\n        \"mode\": \"per_night\",\n        \"price\": 0,\n        \"type\": \"cot\"\n      }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["policies.cots_and_extra_beds"]}," provides age and pricing information."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rooms[].cots_and_extra_beds"]}," provides room-level limits."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The cot applies to children aged 0–2, inclusive."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mode: per_night"]}," means the price is applied per night."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The cot is available at no additional charge."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"check-room-level-limits","__idx":19},"children":["Check room-level limits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The room information indicates how many cots or extra beds can be added:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"rooms\": [\n    {\n      \"id\": \"2763504\",\n      \"cots_and_extra_beds\": {\n        \"are_allowed_together\": false,\n        \"maximum_number_of_cots\": 1,\n        \"maximum_number_of_extra_beds\": 0\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A maximum of one cot can be added."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Extra beds cannot be added."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["are_allowed_together: false"]}," means cots and extra beds cannot be used together when both types are otherwise available."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["policies.cots_and_extra_beds"]}," to understand the applicable age and pricing rules, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rooms[].cots_and_extra_beds"]}," to understand the room-level limits."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These fields should be interpreted together with the room's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maximum_occupancy"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recommended-flow-for-family-requests","__idx":20},"children":["Recommended flow for family requests"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For integrations that allow travellers to select accommodation products independently, use the following flow:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Send the complete guest group to /accommodations/search, including the actual ages of all children."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Call /accommodations/availability for the selected accommodation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Prefer the products returned in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommendation"]}," when they meet your integration requirements."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If selecting another product:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["room"]}," ID to retrieve the corresponding room from /accommodations/details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimum_guest_age"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check the room's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maximum_occupancy"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In version 3.3, apply ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occupancy_total"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["included_in_total"]},"."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit the selected product and exact guest allocation to /orders/preview."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occupancy_mismatch"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If any guests are unallocated, change the product or allocation and call /orders/preview again."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create the order only after validating the final guest allocation."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"references","__idx":21},"children":["References"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/demand/docs/accommodations/v3.2/occupancy-allocation"},"children":["Occupancy & allocation guide"]}," for details about occupancy fields and the recommended integration flow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/demand/docs/accommodations/child-policies"},"children":["Children policies guide"]}," for child rates, free stays, cots and extra beds."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/demand/docs/accommodations/v3.2/occupancy-troubleshooting"},"children":["Troubleshooting section"]}," to identify and solve possible errors."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/demand/docs/accommodations/search-for-available-properties"},"children":["Accommodation search guide"]}," for best practices when using /accommodations/search and /accommodations/availability."]}]}]}]},"headings":[{"value":"Occupancy and allocation use cases v3.2","id":"occupancy-and-allocation-use-cases-v32","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Differences between endpoints","id":"differences-between-endpoints","depth":3},{"value":"Allocate guests to rooms","id":"allocate-guests-to-rooms","depth":2},{"value":"Search for one room for a mixed group","id":"search-for-one-room-for-a-mixed-group","depth":3},{"value":"Allocate guests across multiple rooms","id":"allocate-guests-across-multiple-rooms","depth":3},{"value":"Request rooms close together","id":"request-rooms-close-together","depth":4},{"value":"Handle adults-only properties","id":"handle-adults-only-properties","depth":2},{"value":"Property with another minimum guest age","id":"property-with-another-minimum-guest-age","depth":3},{"value":"Interpret child-rate information","id":"interpret-child-rate-information","depth":2},{"value":"Product with child rates","id":"product-with-child-rates","depth":3},{"value":"Check static room occupancy limits","id":"check-static-room-occupancy-limits","depth":2},{"value":"Handle children: null","id":"handle-children-null","depth":2},{"value":"Use the recommended allocation","id":"use-the-recommended-allocation","depth":2},{"value":"Handle a product outside recommendation","id":"handle-a-product-outside-recommendation","depth":2},{"value":"Handle an occupancy mismatch","id":"handle-an-occupancy-mismatch","depth":2},{"value":"Handle a free child stay","id":"handle-a-free-child-stay","depth":2},{"value":"Handle cots and extra beds","id":"handle-cots-and-extra-beds","depth":2},{"value":"Check cot and extra-bed policies","id":"check-cot-and-extra-bed-policies","depth":3},{"value":"Check room-level limits","id":"check-room-level-limits","depth":3},{"value":"Recommended flow for family requests","id":"recommended-flow-for-family-requests","depth":2},{"value":"References","id":"references","depth":2}],"frontmatter":{"title":"Occupancy and allocation use cases","description":"Explore v3.2 examples for guest allocation, room occupancy, child policies, age restrictions, and occupancy validation in the Demand API.","tags":["demand-api","accommodations","occupancy","allocation","child-policies","multi-room","booking-validation"],"api":["/accommodations/search","/accommodations/availability","/accommodations/details","/orders/preview","/orders/create"],"keywords":["occupancy rules Booking.com","guest allocation Demand API","maximum occupancy API response","child rates and free stays","adults and children allocation","occupancy mismatch","accommodation age restrictions","multi-room accommodation allocation"],"x-redocly":{"seo":{"title":"Occupancy and allocation use cases in the Demand API","description":"Work through v3.2 examples for guest allocation, child policies, room occupancy, age restrictions, and order preview validation."},"audience":["developer","partners"]},"apiVersion":"v3.2","product":"accommodation","seo":{"title":"Occupancy and allocation use cases v3.2"}},"lastModified":"2026-11-18T15:29:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/demand/docs/accommodations/v3.2/occupancy-use-cases","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}