Child policies - use cases

This guide presents various scenarios for family group allocation, occupancy, and related policies, explaining how to retrieve, display, and interpret these use cases through our Demand API.

Overview

The following examples cover common scenarios for family accommodation searches, with varying group structures and room allocations.

Each use case includes a request and response sample, alongside explanations and best practices to help you implement them effectively.

Allocation - use cases

Family group in 1 room

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.

{
  "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
  }
}

Family group with multiple rooms (use allocation)

The same family group from the previous example is now looking for multiple rooms:

• Room A for 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 pin which children go to which room.

{
  "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 orders (via order/create).

This allows guests to communicate with the property about their preference for room proximity.

Example of order/create call with "special request":

{
  "accommodation": {
    "label": "Sample label",
    "products": [...]
  },
  "remarks": {
    "estimated_arrival_time": {
      "hour": 12
    },
    "special_requests": "We would like to have the two rooms together."
  }
}

Occupancy - use cases

Single-parent family

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: 2025-02-13
• Checkout: 2025-02-14

→ Use the accommodation availability endpoint to retrieve real-time information about the availability, pricing and occupancy for the selected accommodation.

{
  "accommodation": 9897851,
  "booker": { ... },
  "checkin": "2025-02-13",
  "checkout": "2025-02-16",
  "extras": [ ... ],
  "guests": {
    "number_of_adults": 1,
    "children": [7, 9],
    "number_of_rooms": 1
  }
}
  

One child counted as adult

Search may suggest a match, but /availability can show fewer child slots than requested. In such situations the service may count extra children as adults to respect capacity.

What to check:

• Compare /search results with /availability — availability definitively enforces maximum_occupancy.
• 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).

Scenario: For the following family group:

• 2 children (4 and 8 year old).
• 2 adults.
• And 2 rooms.

Steps:

1. Use the Accommodations/search endpoint:

{
  "accommodations": [430741],
  "booker": { ... },
  "checkin": "2025-07-27",
  "checkout": "2025-07-29",
  "guests": {
    "number_of_adults": 2,
    "children": [4, 8],
    "number_of_rooms": 2
  }
}

2. Call the accommodations/availability endpoint:

{
  "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]
  }
}

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

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

{
  "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.

Tip: Show both adults, children bands and total so the user understands capacity versus pricing eligibility.

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.

{
  "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 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:

{
  "id": "989785107_371605558_2_1_0",
  "deal": null,
  "maximum_occupancy": {
    "adults": 2,
    "children": null,
    "total": 4
  }
}

Tip: Make sure you indicate in your UI that children are allowed but are charged at adult price.

"Adults only" properties

In certain cases, properties may specify that they are "adults only".

When checking availability in an "adults only" accommodation, with the following information in the request:

• Hotel ID: 91556
• 2 adults + 2 children, aged 8 and 10
• 1 room, with no allocation.

{
  "accommodation": 91556,
  "booker": { ... },
  "checkin": "2025-02-20",
  "checkout": "2025-02-25",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2,
    "children": [8, 10]
  }
}

Tip: To prevent such errors, exclude such properties when the search includes children.

Best practices for "adults only"

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

2. In the response, check the minimum_guest_age field within the policies object:

• This field indicates the minimum age required for a guest 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).

• If the minimum age is 18 (or higher) that means that this property is "adults only".
• If the minimum age is for example 8, then all children below this age are not permitted (but the property is not classified as "adults only").

For example, if a property has minimum_guest_age: 17, you can exclude it from searches involving children:

{
  "policies": {
    "cots_and_extra_beds": [...],
    "damage": { ... },
    "maximum_checkin_age": null,
    "minimum_checkin_age": 17,
    "minimum_guest_age": 0,
    "pets": {...}
  }
}

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 request includes:

• Accommodation id: 430741.
• 2 adults.
• A 2 years old child.
• They need 1 room.

{
  "accommodations": [430741],
  "booker": { ... },
  "checkin": "2025-08-27",
  "checkout": "2025-08-28",
  "guests": {
    "number_of_adults": 2,
    "children": [2],
    "number_of_rooms": 1
  }
}
  

The reason why there are no recommendations is due to the age restrictions set by the property.

In order to verify the applicable age restrictions set by the property:

1. Call the /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.

{
  "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.

3. Repeat again the 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.

{
  "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
  }
}

Cots and extra beds

To retrieve information about cots and extra beds, you should call the /accommodations/details endpoint and specify the extras parameter with the rooms option.

{
  "accommodations": [27635],
  "extras": ["rooms"],
  "languages": ["en-gb"]
}

Troubleshooting

When working with child policies, you may encounter unexpected behaviours. Here are the most common issues and how to resolve them:

Children treated as adults

Symptom: The maximum_occupancy.children field is null, and children are priced as adults.

Resolution: Inform users that the property does not offer child rates. Always show the total price to avoid confusion.

No products returned for children under a certain age

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

Resolution: Check the minimum_guest_age in the /accommodations/details response. Adjust the request to reflect allowed ages.

Booking attempt blocked at preview

Symptom: [orders/preview] returns an error when children are included.

Resolution: Verify if the property is flagged as "adults only" (minimum_guest_age: 18). Exclude such properties when children are present in the request.

Inconsistent occupancy interpretation

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

Resolution: Cross-check maximum_occupancy rules. 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.