Note: In March 2021 Hilton will introduce support of child-based pricing through DirectConnect APIs
Consumers of the API will have the optional ability to pass in child ages on both shop and book request so that returned rates will then reflect appropriate child charges at the hotel.
Participating hotels can choose to set up child rates and manage up to six different price tiers each with its own age range. Hilton’s API supports this child-based pricing for shopping and booking, and allows you to pass in child ages and receive rates that include the appropriate child charges.
Here is a high-level example of how a property can define child pricing:
| Child Age Range | Child Rate |
|---|---|
| 0-5 years old | $0 |
| 6-14 years old | $60 |
| 15-17 years old | $70 |
| Adult Age=18+ years old | |
If a shop request includes an 11-year-old child and a 17-year-old child then the 11-year old will be $60 and the 17-year old will be charged at a $70 nightly rate.
If the shop request contains child counts but does not include the child age, Hilton will default the children be the adult age -1. In above scenario adult age is defined as 18, so if the ages were not included in the request both the 11-year-old and 17-year old children would default to 17 years old, and each would be charged at the $70 rate. Thus, consumers who do not pass in ages may not receive the most competitive rate.
The tutorial below covers the following two business scenarios. The first shows example from a hotel that has child-based pricing enabled and the second example shows a hotel that hhappens to have a flat child fee included in the product.
- Scenario #1: Mark wishes to stay in January 2021 at Hilton Rose Hall property in Jamaica with his two children, ages 11 and 17. These are the tasks performed:
- A single property shop is sent which includes 1 adult and two children with child ages included (Single property shop)
- The details received in the single property shop response are used to reserve a room (Create reservation)
- Scenario #2: Jane wishes to stay in March 2021 at San Francisco Hilton property with her one child, age 11. The hotel is not child-based pricing enabled. These are the tasks performed:
- A single property shop is sent which includes 1 adult and one child with child age included (Single property shop)
- The details received in the single property shop response are used to reserve a room (Create reservation)
These samples begin after the Access Token has been received. See the Authenticate Your App page for this sample.
Scenario #1: Single Property Shop
A single property shop is sent which includes 1 adult and two children with child ages included
POST https://kapip-s.hilton.io/hospitality-partner/v2/dcshop/props/MBJRH
Content-Type: application/json
accept: application/json
Authorization: "Basic YOUR_BASE64_ENCODED_CLIENTID:CLIENTSECRET"
Request Body:
{
"arrivalDate": "2021-01-15",
"departureDate": "2021-01-16",
"numAdults": "1",
"numChildren": "2",
"childAges": [
11,
17
]
}
{
"adultAge": 18,
"ageBasedPricing": true,
"statusCode": 0,
"propCode": "MBJRH",
"propName": "ROSE HALL HILTON RESORT SPA",
"brandCode": "HF",
"currencyCode": "USD",
"arrivalDate": "2021-01-15",
"departureDate": "2021-01-16",
"lengthOfStay": 1,
"numAdults": 1,
"numChildren": 2,
"ageBasedPricing": true,
"adultAge": 18,
"childAgeRanges": [
{
"startChildAge": 0,
"endChildAge": 5
},
{
"startChildAge": 6,
"endChildAge": 14
},
{
"startChildAge": 15,
"endChildAge": 17
}
],
"childAges": [
11,
17
],
"highRate": 368.0,
"lowRate": 368.0,
"taxPeriods": [
{
"effectiveDate": "2021-01-15"
}
],
"ratePlans": {
"LV8": {
"ratePlanCode": "LV8",
"ratePlanDesc": [
"BEST AVAILABLE RATE"
],
"ratePlanOrder": 1,
"ratePlanCategory": "rack",
"highRate": 368.0,
"lowRate": 368.0,
"commissionable": true,
"commissionAmount": 10.0,
"commissionType": "percent",
"currencyCode": "USD",
"displayCurrency": "USD",
"clientIdRequired": false,
"serviceChargesAndTaxesIncluded": true,
"cxlPolicyCode": "CX14",
"cxlPolicyDesc": "CXL 14 DAYS PRIOR TO ARRIVAL",
"cxlPolicyDeadline": "2023-10-19T05:00:00Z",
"cxlPolicyLocalDeadline": "2023-10-06T23:59",
"guarPolicyCode": "CCD",
"guarPolicyDesc": "CREDIT CARD DEPOSIT",
"depositDesc": "100.00 PERCENT OF FULL STAY",
"guaranteeMethods": [
"CD",
"FP"
]
}
},
"roomTypes": {
"K1RP": {
"roomTypeCode": "K1RP",
"roomTypeDesc": [
"PARTIAL OCEAN VIEW 1 KING BED - ALL INCLUSIVE",
"CHILDREN 5 AND UNDER STAY AND EAT FOR FREE",
"PRIVATE BALCONY - MINI FRIDGE - WIFI AVAIL\t"
],
"roomOccupancy": 4,
"numBeds": 1,
"bedType": "king",
"roomDisplayOrder": 15,
"adaAccessibleRoom": false,
"extraBedPermitted": false,
"extraPersonsAllowed": false,
"smokingRoom": false
}
},
"roomRates": [
{
"ratePlanCode": "LV8",
"roomTypeCode": "K1RP",
"numRoomsAvail": 9,
"rateAmount": 368.0,
"amountBeforeTax": 368.0,
"amountAfterTax": 368.0,
"rateChangeIndicator": false,
"rollawayRate": 25.0,
"cribRate": 0.0,
"depositAmount": 368.0,
"totalServiceCharges": 0.0,
"totalTaxes": 0.0,
"meals": {
"mealPlan": "N"
},
"rateDetails": [
{
"effectiveDate": "2021-01-15",
"extraChildRate": 65.0,
"extraPersonRate": 0.0,
"rate1Person": 238.0,
"rate2Person": 289.0,
"rate3Person": 379.0,
"rate4Person": 469.0,
"rollawayRate": 25.0,
"cribRate": 0.0,
"childRates": [
0.0,
60.0,
70.0
]
}
]
}
]
}
Scenario #1: Create Reservation
The below example request and response are for a one room reservation for Mark and his two children, ages 11 and 17 years old.
POST https://kapip-s.hilton.io/hospitality-partner/v2/dcres
Content-Type: application/json
accept: application/json
Authorization: "Basic YOUR_BASE64_ENCODED_CLIENTID:CLIENTSECRET"
Request Body:
{
"propCode": "MBJRH",
"guest": {
"name": {
"firstName": "Mark",
"lastName": "Test",
"title": "Mr"
},
"addresses": [
{
"addressType": "home",
"addressLine1": "123 Main St",
"city": "Lexington",
"state": "KY",
"country": "US",
"postalCode": "40515"
}
]
},
"roomStays": [
{
"arrivalDate": "2021-01-15",
"departureDate": "2021-01-16",
"numAdults": "1",
"numChildren": "2",
"childAges": [
11,
17
],
"ratePlanCode": "LV8",
"roomTypeCode": "K1RP"
}
],
"guarantee": {
"guarMethodCode": "CD",
"paymentCard": {
"cardHolderName": "Mark Test",
"cardNumber": "5123451806614240",
"cardCode": "MC",
"cardExpireDate": "0321"
}
},
"comments": [
"Away from elevator please"
],
"externalResId": "123ABC456"
}
[
{
"adultAge": 18,
"ageBasedPricing": true,
"arrivalDate": "2021-01-15",
"confNumber": "3124193855",
"departureDate": "2021-01-16",
"externalResId": "123ABC456",
"gnrNumber": 127813875,
"numAdults": 1,
"numChildren": 2,
"adultAge": 18,
"ageBasedPricing": true,
"numRooms": 1,
"propCode": "MBJRH",
"resCreateDate": "2021-01-22T18:59:12Z",
"cost": {
"amountAfterTax": 368.0,
"amountBeforeTax": 368.0,
"currencyCode": "USD",
"serviceChargesInTaxCalc": false,
"totalServiceCharges": 0.0,
"totalTaxes": 0.0,
"meals": {
"mealPlan": "N",
"mealPlanDesc": "None"
},
"rateDetails": [
{
"cribRate": 0.0,
"effectiveDate": "2021-01-15",
"extraChildRate": 65.0,
"extraPersonRate": 0.0,
"rate1Person": 238.0,
"rate2Person": 289.0,
"rate3Person": 379.0,
"rate4Person": 469.0,
"rollawayRate": 25.0,
"roomRate": 368.0,
"childRates": [
0.0,
60.0,
70.0
]
}
]
},
"guarantee": {
"cxlPolicyCode": "CX14",
"cxlPolicyDesc": "CXL 14 DAYS PRIOR TO ARRIVAL",
"guarMethodCode": "CD",
"guarMethodDesc": "CREDIT CARD DEPOSIT",
"guarPolicyCode": "CCD",
"guarPolicyDesc": "CREDIT CARD DEPOSIT",
"paymentCard": {
"cardCode": "MC",
"cardExpireDate": "0321",
"cardNumber": "8058307809654240"
}
},
"guest": {
"name": {
"firstName": "Mark",
"lastName": "Test",
"title": "Mr"
},
"addresses": [
{
"addressLine1": "123 Main St",
"city": "Lexington",
"country": "US",
"postalCode": "40515",
"state": "KY",
"addressType": "home"
}
]
},
"ratePlan": {
"advancePurchase": false,
"ratePlanCode": "LV8",
"ratePlanName": "BEST AVAILABLE RATE",
"serviceChargesAndTaxesIncluded": true
},
"roomType": {
"extraBedPermitted": false,
"roomOccupancy": 4,
"roomTypeCode": "K1RP",
"smokingRoom": true,
"roomTypeDesc": [
"PARTIAL OCEAN VIEW 1 KING"
]
},
"childAges": [
11,
17
],
"comments": [
"Away from elevator please"
],
"bookingMessages": [
{
"endDate": "2173-10-14",
"message": "ADV ALL: PLEASE VERIFY AGES OF CHILDREN BEFORE QUOTING RATE",
"startDate": "2013-05-08"
}
]
}
]
Interpreting child pricing within the shop and book responses
Hilton’s shop and book responses will include several fields that detail if and how the property supports child pricing – and what child ages were used in pricing based off ages provided in the request or set to default age if not passed:
At the main object level the response will present information around age ranges at the property. The below fields found within PropDcShop object (DCShop) and DcReservationStay object (DCRes):
- adultAge = Indicates the guest age the property defines as an adult
- ageBasedPricing = Indicates if property supports child-based pricing. If true then you can expect to see child ranges and associated child rates for the ranges returned.
- childAgeRanges object = Array detailing the age ranges defined by the property. Up to 6 ranges can be returned
- childAges = Array detailing the child ages that were used to determine rates. If ages were passed on the request then they will be shown in list. If no ages were passed then default ages will be shown (Calculated as adultAge -1)
Rate information based on the children’s ages will be found within the roomRate object (DCShop) and Cost object (DCRes):
- extraChildRate = Displays the average nightly rate of the combined children. If an 11-year-old is charged at $60, and a 17 year old is $70, then the extraChildRate would show as $65. Note- Some properties/rate plans may not use child-based pricing but can have extraChildRates return an amount due to Hilton CRS ability to set up extra child fees within the rate plan. This functionality has been in place for many years and will be overridden by child-based pricing if both methods are set up.
- childRates = Displays the rates for each of the age ranges. Used in combination with childAgeRanges object that notes the ranges.
- rateAmount = Displays the nightly rate including all adults and children. For most partners this is configured to show the average rate, for some partners it is configured to show the highest nightly rate during the stay.
- amountBeforeTax = Displays the total cost of the entire stay which includes adults and child costs.
- rate1Person = Displays the nightly rate for one adult, rate2Person shows the nightly rate for two adults, etc.
Note: You have to combine the childRates object with the childAgeRanges object to determine the rate for each age range, if needed.
Child fees outside of child-based pricing functionality
Hilton properties which are not yet configured to use the new child-based pricing functionality will continue to use the existing extraChildRate field when appropriate.
Hilton already has the ability to increase room rate based on child occupancy, but this is currently a flat fee not altered by age. In the below example any children added to an availability search will increase the rate by $12, shown in the “extraChildRate” field. This is automatically included in the rate amount, in this case one child at $12 was added to $310 for rate1Person so that $322 nightly rate amount returned. Including child ages on the request had no effect as the property was not set up to use child-based pricing therefore the child ages did not impact the rates, only the flat child fee of $12 was included. Notice that ageBasedPricing flag returned as false and no child age/rate objects were returned.
Scenario #2: Single Property Shop
A single property shop is sent which includes 1 adult and one child with child age included
POST https://kapip-s.hilton.io/hospitality-partner/v2/dcshop/props/SFOSF
Content-Type: application/json
accept: application/json
Authorization: "Basic YOUR_BASE64_ENCODED_CLIENTID:CLIENTSECRET"
Request Body:
{
"arrivalDate": "2021-03-06",
"departureDate": "2021-03-07",
"numAdults": "1",
"numChildren": "1",
"childAges": [
11
]
}
{
"adultAge": 18,
"ageBasedPricing": true,
"statusCode": 0,
"propCode": "SFOSF",
"propName": "PARC 55 SAN FRANCISCO HILTON",
"brandCode": "HH",
"currencyCode": "USD",
"arrivalDate": "2021-03-06",
"departureDate": "2021-03-07",
"lengthOfStay": 1,
"numAdults": 1,
"numChildren": 2,
"ageBasedPricing": false,
"highRate": 322.0,
"lowRate": 322.0,
"taxPeriods": [
{
"effectiveDate": "2021-03-06"
}
],
"ratePlans": {
"LV8": {
"ratePlanCode": "LV8",
"ratePlanDesc": [
"BEST AVAILABLE RATE"
],
"ratePlanOrder": 1,
"ratePlanCategory": "rack",
"highRate": 322.0,
"lowRate": 322.0,
"commissionable": true,
"commissionAmount": 10.0,
"commissionType": "percent",
"currencyCode": "USD",
"displayCurrency": "USD",
"clientIdRequired": false,
"serviceChargesAndTaxesIncluded": true,
"cxlPolicyCode": "CX14",
"cxlPolicyDesc": "CXL 14 DAYS PRIOR TO ARRIVAL",
"cxlPolicyDeadline": "2023-10-19T05:00:00Z",
"cxlPolicyLocalDeadline": "2023-10-06T23:59",
"guarPolicyCode": "CCD",
"guarPolicyDesc": "CREDIT CARD DEPOSIT",
"depositDesc": "100.00 PERCENT OF FULL STAY",
"guaranteeMethods": [
"CD",
"FP"
]
}
},
"roomTypes": {
"K1RP": {
"roomTypeCode": "K1RP",
"roomTypeDesc": [
"PARTIAL OCEAN VIEW 1 KING BED - ALL INCLUSIVE",
"CHILDREN 5 AND UNDER STAY AND EAT FOR FREE",
"PRIVATE BALCONY - MINI FRIDGE - WIFI AVAIL\t"
],
"roomOccupancy": 4,
"numBeds": 1,
"bedType": "king",
"roomDisplayOrder": 15,
"adaAccessibleRoom": false,
"extraBedPermitted": false,
"extraPersonsAllowed": false,
"smokingRoom": false
}
},
"roomRates": [
{
"ratePlanCode": "LV8",
"roomTypeCode": "K1RP",
"numRoomsAvail": 9,
"rateAmount": 322.0,
"amountBeforeTax": 322.0,
"amountAfterTax": 322.0,
"rateChangeIndicator": false,
"rollawayRate": 20.0,
"cribRate": 0.0,
"depositAmount": 322.0,
"totalServiceCharges": 0.0,
"totalTaxes": 0.0,
"meals": {
"mealPlan": "I"
},
"rateDetails": [
{
"effectiveDate": "2021-03-06",
"extraChildRate": 12.0,
"extraPersonRate": 0.0,
"rate1Person": 310.0,
"rate2Person": 329.0,
"rate3Person": 379.0,
"rate4Person": 419.0,
"rollawayRate": 20.0,
"cribRate": 0.0
}
]
}
]
}
Scenario #2: Create Reservation
The below example request and response are for a one room reservation for Jane and her one child, age 11.
POST https://kapip-s.hilton.io/hospitality-partner/v2/dcres
Content-Type: application/json
accept: application/json
Authorization: "Basic YOUR_BASE64_ENCODED_CLIENTID:CLIENTSECRET"
Request Body:
{
"propCode": "SFOSF",
"guest": {
"name": {
"firstName": "Jane",
"lastName": "Test",
"title": "Mrs"
},
"addresses": [
{
"addressType": "home",
"addressLine1": "123 Main St",
"city": "Lexington",
"state": "KY",
"country": "US",
"postalCode": "40515"
}
]
},
"roomStays": [
{
"arrivalDate": "2021-03-06",
"departureDate": "2021-03-07",
"numAdults": "1",
"numChildren": "1",
"childAges": [
11
],
"ratePlanCode": "LV8",
"roomTypeCode": "K1RP"
}
],
"guarantee": {
"guarMethodCode": "CD",
"paymentCard": {
"cardHolderName": "Jane Test",
"cardNumber": "5123451806614240",
"cardCode": "MC",
"cardExpireDate": "0321"
}
},
"comments": [
"Away from elevator please"
],
"externalResId": "123ABC456"
}
[
{
"adultAge": 18,
"ageBasedPricing": true,
"arrivalDate": "2021-03-06",
"confNumber": "3124193859",
"departureDate": "2021-03-07",
"externalResId": "123ABC456",
"gnrNumber": 127813875,
"numAdults": 1,
"numChildren": 1,
"ageBasedPricing": false,
"numRooms": 1,
"propCode": "SFOSF",
"resCreateDate": "2021-01-22T19:22:12Z",
"cost": {
"amountAfterTax": 322.0,
"amountBeforeTax": 322.0,
"currencyCode": "USD",
"serviceChargesInTaxCalc": false,
"totalServiceCharges": 0.0,
"totalTaxes": 0.0,
"meals": {
"mealPlan": "N",
"mealPlanDesc": "None"
},
"rateDetails": [
{
"cribRate": 0.0,
"effectiveDate": "2021-03-06",
"extraChildRate": 12.0,
"extraPersonRate": 0.0,
"rate1Person": 310.0,
"rate2Person": 329.0,
"rate3Person": 379.0,
"rate4Person": 419.0,
"rollawayRate": 20.0,
"roomRate": 322.0
}
]
},
"guarantee": {
"cxlPolicyCode": "CX14",
"cxlPolicyDesc": "CXL 14 DAYS PRIOR TO ARRIVAL",
"guarMethodCode": "CD",
"guarMethodDesc": "CREDIT CARD DEPOSIT",
"guarPolicyCode": "CCD",
"guarPolicyDesc": "CREDIT CARD DEPOSIT",
"paymentCard": {
"cardCode": "MC",
"cardExpireDate": "0321",
"cardNumber": "8058307809654240"
}
},
"guest": {
"name": {
"firstName": "Jane",
"lastName": "Test",
"title": "Mr"
},
"addresses": [
{
"addressLine1": "123 Main St",
"city": "Lexington",
"country": "US",
"postalCode": "40515",
"state": "KY",
"addressType": "home"
}
]
},
"ratePlan": {
"advancePurchase": false,
"ratePlanCode": "LV8",
"ratePlanName": "BEST AVAILABLE RATE",
"serviceChargesAndTaxesIncluded": true
},
"roomType": {
"extraBedPermitted": false,
"roomOccupancy": 4,
"roomTypeCode": "K1RP",
"smokingRoom": true,
"roomTypeDesc": [
"PARTIAL OCEAN VIEW 1 KING"
]
},
"comments": [
"Away from elevator please"
],
"bookingMessages": [
{
"endDate": "2173-10-14",
"message": "ADV ALL: PLEASE VERIFY AGES OF CHILDREN BEFORE QUOTING RATE",
"startDate": "2013-05-08"
}
]
}
]
Frequently Asked Questions
How frequently do the age ranges change?
Hilton allows properties to update their content at any time. Please make your best effort to provide the most up-to-date information to customers. Our Partner shop API provides the most current information available for available rooms and rates. No static data (property address, star ratings, geo info, etc) is returned. Only availability and rate-related data is provided.
How are the child rates managed?
Child rates are set up at the rate plan level. Child rates may be set up to have different rates based on date range.
How many child age ranges are supported?
Hilton currently supports a maximum of 6 age ranges.
How many children are permitted on the booking?
Hilton supports a maximum of 8 children with ages on the request however room types vary in adult/children counts they allow.