X
Our new Developer Portal is here!
The latest version of our Demand API (V3.1) is now available.
Update now for improved functionality and access to newly added endpoints.
Take me there
Guide: Child policies and rates
# Overview
## Learn what's the child rates and how to use it
Families are a large guest segment on our platform. On average, they stay longer and are more likely to book than other segments like solo travelers and couples, which is why we launched a special rate called the **"child rate"**.
What's a **"child rate"**? It's a special rate that targets families that takes into account not only the group occupancy but also their age. Our Supply partners received an excellent tool to:
* Attract a more lucrative segment, as families stay 28% longer and book at a 27% higher rate than solo travelers or couples
* Maintain full flexibility, as a children's rate can be defined based on up to three age bands
* Have more control when managing inventory, as each room can now be configured for children
### **Who needs child rates?**
If you want to offer flexibility, relevant search results, and better prices for your travelers with children.
### **Child rates features**
* Child Policies
* How to search availability with children
* How to recognize and use child blocks
# Search for and render blocks with child rates
This guide explains how to use [Child blocks] in your product and how to use them best. The process follows the usual *Search -> Look -> Book* pattern that's used in other places.
## Get started
### Prerequisites
1. Register for the affiliate program
2. Get API credentials
3. Learn how to search for availability
### Step 1. Search for available hotels
**Scenario: Traveler is searching for the best accommodation for their group of two adults and one child of 6 years old.**
To search for specific groups and include children, you need to use the parameters "room1", "room2", and so on to define room allocation. Multiple rooms can be specified.
First, you need to find the best accommodation at the most attractive price. You need to use the /hotelAvailability endpoint, which returns the best possible block for given search criteria.
```bash
`curl --location --request GET 'https://distribution-xml.booking.com/2.9/json/hotelAvailability?checkin=2022-09-05&checkout=2022-09-07&hotel_ids=4462291&room1=A,A,6&guest_country=nl&extras=hotel_details,room_details&options=show_test' \
--header 'Authorization: Basic {your basic auth}'`
```
* `room1` - This argument allows us to define a search for specific groups and include children. A indicates an adult, and 6 is the age of a child. Multiple rooms can be set with the parameters "room1", "room2".
> INFO: Maximum number of rooms is 30 "room1" to "room30" can be used.
**Response example**
```json
{
"result": [{
"price": 250.0,
...
"rooms": [{
"room_type_id": 9,
"children": [
"6"
],
"adults": 2,
"block_id": "446229103_355129736_2_0_6047313952768",
"room_id": 446229103,
"room_name": "Budget Double Room",
"net_price": 240.0
}],
"hotel_id": 4462291,
"hotel_name": "Demand API Test Hotel",
...
}]
}
```
### **Step 2. Search for available blocks in the hotel**
When travelers find a good match for a hotel and price, you need to show them all available **blocks** in the hotel.
In the example, A indicates an adult, while 6 is a child age. Multiple rooms can be given.
```bash
`curl --location --request GET 'https://distribution-xml.booking.com/2.9/json/blockAvailability?checkin=2022-09-05&checkout=2022-09-07&hotel_ids=4462291&room1=A,A,6&show_test=1&guest_cc=nl&limit_incremental_prices=1&extras=max_children_free,max_children_free_age' \
--header 'Authorization: Basic {your basic auth}'`
```
* `room1` - This argument allows us to define a search for specific groups and include children. **_A_** indicates an adult and **_6_** age of a child. Multiple rooms can be set with the parameters "room1" and "room2".
**Response example**
```json
{
"result": [{
"hotel_id": 4462291,
"checkin": "2022-09-05",
"checkout": "2022-09-07",
"block": [
...
{
"max_children_free_age": 5,
"room_id": 446229103,
"max_adults": 2,
"max_occupancy": 3,
"name": "Budget Double Room - Free cancellation",
"block_id": "446229103_355129736_2_0_6047313952768",
"max_children_free": 1,
"min_price": {
"currency": "EUR",
"price": 250.0
}
}
...
]
}]
}
```
### Step 3. How to show child rates and policies
To help travelers navigate their choice, you may need to show all details about the conditions children are hosted in the accommodation. The **/hotels** endpoint has the most detailed overview of child policies for a given accommodation.
> INFO: **/hotels** is a static endpoint. We recommend to cache results of /hotels endpoint to improve the overall responsiveness of your product.
```bash
`curl --location --request GET 'https://distribution-xml.booking.com/2.9/json/hotels?hotel_ids=4462291&language=en&extras=hotel_description,hotel_policies&show_test=1' \
--header 'Authorization: Basic {your basic auth}'`
```
* `hotel_policies` - This argument indicates that extra hotel policies should be included in the response. That includes child policies (POLICY_CHILDREN).
**Response example**
```json
{
"result": [{
"hotel_id": 4462291,
"hotel_data": {
"hotel_policies": [{
{
"type": "POLICY_CHILDREN",
"name": "Children and extra bed policy",
"content": "Children of any age are allowed.\nChildren up to and including 5 years old stay for free when using an existing bed.\nChildren from 6 years old to 12 years old stay for € 20 per person per night when using an existing bed.\nNo cots are available.\nNo extra beds are available.\nSupplements are not calculated automatically in the total costs and will have to be paid for separately during your stay."
}
],
"additional_policies": {
"children_allowed": true,
"cots_and_extra_beds": [{
"rate_type": "existing_bed",
"from_age": 0,
"price_mode": "per_night",
"to_age": 5,
"price": 0.0
},
{
"from_age": 6,
"rate_type": "existing_bed",
"price": 20.0,
"price_mode": "per_night",
"to_age": 12
}
],
"child_min_age": 0
}
}
}]
}
```
* `children_allowed` - This argument indicates if children are allowed in this accomodation.
* `child_min_age` - This argument defines the minimum age (inclusive) for staying in this property. If "0", then a child of any age is allowed. Not returned unless `children_allowed=true` and the property has defined policies for children.
* `cots_and_extra_beds` - This block defines rates for cots and extra beds.
### Step 4. Book accomodation
After travelers choose the best room and the price, you need to confirm their reservation in the /processBooking endpoint. Important here is to pass:
* roomX as set in the search
* right blockId
* right incremental_price
```bash
curl --location --request POST 'https://secure-distribution-xml.booking.com/2.9/json/processBooking' \
--header 'Authorization: Basic {your basic auth}' \
--header 'Content-Type: application/json' \
--data-raw '{
"affiliate_id":956509,
"block_ids":"446229102_355129736_2_0_6047313952768",
"block_quantities":1,
"booker_country":"nl",
"booker_city":"Amsterdam",
"booker_address": "attre derrto",
"booker_firstname":"test",
"booker_lastname":"test",
"booker_telephone":"003155585555",
"checkin":"2022-09-05",
"checkout":"2022-09-07",
"hotel_id":4462291,
"incremental_prices":335.0,
"booker_email":"test@booking.com",
"show_test":1,
"test_mode":1,
"room1": "A,A,6",
"cc_expiration_date":"2022-12-30",
"cc_cardholder":"test test",
"cc_number":"4111111111111111",
"cc_type":"2",
"cc_cvc":"123",
"options":"allow_past, use_booker_country"
}'
```
# Child Policies
## Global Children policy
There are two accommodation level properties to manage global child policy:
* Are children under 18 years old allowed at property?
* At what age (and older) are children allowed?
_Policy example:_
* _Children ages 2 and older are allowed._
## Occupancy
Three configuration components (Policies, Children pricing & Occupancy) determine how accommodation and rooms are listed for families and whether a child rate is displayed.
* **Max Person** - Defines the maximum number of guests (adult and children) that can physically fit in the room.
* **Max Adults** - Defines the maximum number of adults that can physically fit in the room.
* **Max Children** - Defines the maximum number of children that can physically fit in the room.
## Children Pricing
Our accommodation partners can flexibly configure child pricing policies. Multiple configuration blocks cover most of the use cases:
* Up to which age children can stay for free
* From which and up to which age children are accommodated with discounted price
* From which age children are priced as adults
* A maximum number of children who pays the children rate (the rest pay the full adult rate)
_Policy example:_
* _Children up to and including 5 years old can stay for free._
* _Children from 6 years old to 12 years old can stay for EUR 20.00 per child per night._
* _Guests 13 years and older will be priced as adults._
## Extra Beds and Cots (Cribs)
Our accommodation partners can choose to give an option to add extra beds or cribs to a room. The configuration covers:
* Number of extra beds per room
* Number of extra cots per room
* Age limits for cots and beds.
* Price configuration per crib/bed. Can be free, paid or paid dependent on age
> **WARNING: Maximum number of extra beds can't exceed Max Person per room**
### Extra Beds and Cots Policy Example:
Cots
* Children 2 years old stay for free when using an available cot.
Extra beds
* Children from 2 years old to 12 years old stay for EUR 20.00 per person per night when using an available extra bed.
## Demand API field mapping
| Field / Endpoint | /hotels | /hotelAvailability | /blockAvailability |
|---|---|---|---|
| Occupancy | | | |
| Max Person | occupancy -> max_occupancy | | block->max_occupancy |
| Max Adults | occupancy -> max_adults | rooms->adults | block->max_adults |
| Max Children | occupancy -> max_children | rooms->children | |
| Free Child Options | | | |
| Max Children Free | | | block->max_children_free |
| Max Children Free Age | | | block->max_children_free_age |
| Extra beds and cots | | | |
| Max Extra Beds | occupancy -> max_extra_beds | | extra_bed_available->available |
| Extra Beds Price | | | extra_bed_available->price |
| Extra Beds Age Limit | | | extra_bed_available->age_limit |
| Max Cribs | occupancy -> max_cribs | | |
# FAQ
#### Q: What happens if the child's age is higher than the one allowed by the property?
A: If the customer still wants to stay at this property, the child should be treated as an adult.
#### Q: When are children not allowed for free and how to determine that in the API output?
A: Certain properties don't allow children to stay for free (in which case they're part of the room occupancy and should be treated as adults). In that case, the API returns this information in the availability response:
* **max_children_free: 0**
* **max_children_free_age: -1**
As a best practice: if you are searching for 2 adults and a child, then a suitable room needs to have max occupancy 3.
#### Q: How child policies are working together with Extra bed & cot options?
A: Child and Extra bed options are independent policies. Extra bed and cot options are provided upon availability. The guarantee if a cot or extra bed is provided on post booking using direct message to hotel partner.
The default accommodation policy around extra beds states following:
> _Any type of extra bed or child's cot/crib is upon request and needs to be confirmed by management._
> _Supplements are not calculated automatically in the total costs and will have to be paid for separately during your stay._
