Commonly Asked Questions about using Hilton's API Platform

This Page shows a limited number of examples of commonly asked questions, and their answers. Should you need help with something not covered here, please contact the Distribution Platforms Third Party Distribution Team.

Content API

Cn1. How can I get a list of properties to shop?

A: Please use the Content API to obtain a list of properties for shopping. The details about which properties can be shopped in the Content API response are in Developer Guide| Hilton Dev Portal for documentation

Cn2. Is it possible for Hilton to Provide the STR number of each hotel?

A: No. Hilton does not store STR IDs in our property content, thus we are not able to provide this data.

Cn3. What kind of information is NOT included in a Content API call?

A: Content API provides static data relating to the property and its features. Rate info and other dynamic values that can change day-to-day, or information specific to the partner or client, is not included in these calls.

Cn4. Why do I receive a status of HTTP 206 partial content when I make a Content API call?

A: The default Content API call retrieves data for up to 100 properties and will return 206 for partial content due to the volume of data being retrieved. Send additional requests to obtain data for the remaining properties until you receive HTTP 200 as status. Please see Obtain Property Information | Hilton Dev Portal for documentation for more info.

Shop

S1. Are there any recommendations for shopping multiple properties?

A: When using the shop multiple properties request, ensure that the propCodes belong to the same area. Do not shop properties hundreds of miles apart, for example. Multi Property Shop | Hilton Dev Portal for documentation

S2. Does the room's maximum occupancy include the number of children?

A: Yes, the 'roomOccupancy' field in our single product shop response will tell you the maximum number of people allowed in a room, and this includes children.
For additional information, please see Direct Connect – Shop Single Property | Hilton Dev Portal for documentation page.

S3. How can we determine if an extra person is allowed?

A: In the shop response, if “extraBedPermitted” and “extraPersonsAllowed” are set to true, it indicates that an extra person or bed are allowed.


"extraBedPermitted": true,
"extraPersonsAllowed": true,

S4. How can we determine the maximum occupancy for a room?

A: The maximum occupancy for a room is provided in the shop response under “roomOccupancy”.
For example, "roomOccupancy": 2 indicates that the room can accommodate up to two people.

S5. How can we identify changes in nightly rates?

A: Our system displays rates only when they change, with each rate effective from a specific date. For instance, consider the example below for arrival on 2024-11-03 and departure on 2024-11-07. In this example, the rate starting November 3rd differs from the rate starting November 5th, which remains the same for the rest of the stay (November 5th and 6th). This indicates a change in the nightly rate between consecutive nights.

In the response below is returned


"rateDetails":[
    {
        "effectiveDate":"2024-11-03",
        "extraChildRate":0.0,
        "extraPersonRate":40.0,
        "rate1Person":456.0,
        "rate2Person":456.0,
        "rollawayRate":0.0,
        "cribRate":0.0
    },
    {
        "effectiveDate":"2023-11-05",
        "extraChildRate":0.0,
        "extraPersonRate":10.0,
        "rate1Person":497.5,
        "rate2Person":497.5,
        "rollawayRate":0.0,
        "cribRate":0.0
    }
]

Here 03 and 04 Nov was one rate (456.0) and there is a second rate for 05 and 06 Nov (497.5)

S6. Is there a way to search for a room with specific attributes e.g. based on bed type, single or double beds?

A: No, but when you use Single Product Shops API, you can include a particular rate plan and room type in your request. The 'roomTypes' section in the response will provide details about the room attributes, including the number of beds in the 'numBeds' field.
For additional information, please see Direct Connect – Shop Single Property | Hilton Dev Portal for documentation page.

S7. What does the error "There cannot be more names than max occ" mean?

A: This error occurs when more guest names are included in the booking request than the room’s maximum occupancy allows. (maximum occupancy is returned in the shop response - for example, "roomOccupancy": 2).
Guest information for up to the maximum occupancy of a room can be provided with the booking request. If additional guest names are used (more than the maximum occupancy), the error message "There cannot be more names than max occ" is returned for the request. Once the booking is complete, additional guests can be added to specific GNRs.
Even if multiple rooms are requested, the booking request can only have guest names up to the number of single room occupancy. To update reservation use Update Reservation Stay Information | Hilton Dev Portal for documentation
For additional information on errors, see Error Reference Guide | Hilton Dev Portal for documentation

Book

B1. Can I request a booking / modification confirmation email as part of the reservation process?

A: Yes, as part of the booking or modify request, you can include the e-mail address combined with the field ‘sendConfirmation’ set to true and a confirmation email will be sent to the specified email address.

B2. During the booking or modification process, we are encountering the following error message: "Error Message: Value is required. Fields = addresses. Check all Profiles." What could be the reason?

A: In the event of sending client account information (clientId and clientType) in the booking request, it is necessary to include the Travel Agent and Corporate addresses.

B3. How do I indicate the number of rooms needed when booking multiple rooms?

A: The 'roomStays' section is used to indicate the number of rooms for partners, who are approved to book multiple rooms. Additional info can be found at Multi-room Shopping & Reservation | Hilton Dev Portal for documentation

B4. If we migrate from the XML connection to the JSON connection, will we be able to cancel (or modify) the old reservations using the new API?

A: Yes, in most cases you will be able to. Your old and new accounts will be mapped, and you will be able to view, cancel or modify any of your bookings. Please discuss this with your API coach.

B5. Why did we receive the error “there cannot be more names than max occ” when making a reservation request?

A: this error occurs when the number of guest names passed in the request exceed the number of people allowed for that room type. The count includes additional names, and the name of the guest booking the room.
This can occur in several scenarios, including:

The guest books multiple rooms, but passes more additional names than maximum occupancy per room.

E.g: guest books 2 K1 room types that have maximum occupancy of 2 guests, but includes 3 additional names, bringing the total number of guests to 4.

Shop response showing K1 room type features, where maximum occupancy of the room type is defined by the field "roomOccupancy".

                        
{
    "roomTypes": {
      "K1": {
        "roomTypeCode": "K1",
        "roomTypeDesc": [
          "KING GUEST ROOM",
          "AS OF 28 SQ. M/301 SQ. FT. FRENCH BALCONY",
          "SHOWER AND BATHTUB. DESK. SLEEPS 2."
        ],
        "roomOccupancy": 2,
        "numBeds": 1,
        "bedType": "king",
        "roomDisplayOrder": 10,
        "adaAccessibleRoom": false,
        "extraBedPermitted": false,
        "extraPersonsAllowed": false,
        "smokingRoom": false
      }
    }
  }

Booking request: 4 guests are listed which exceeds the maximum occupancy of the room type.

                        
{
  "roomStays": [
    {
      "numAdults": 2,
      "arrivalDate": "2025-04-01",
      "departureDate": "2025-04-03",
      "ratePlanCode": "XXXXXX",
      "roomTypeCode": "K1"
    },
    {
      "numAdults": 2,
      "arrivalDate": "2025-04-01",
      "departureDate": "2025-04-03",
      "ratePlanCode": "XXXXXX",
      "roomTypeCode": "K1"
    }
  ],
  "guest": {
    "name": {
      "lastName": "Smith",
      "firstName": "John"
    },
    "additionalNames": [
      {
        "lastName": "Smith",
        "firstName": "Jane"
      },
      {
        "lastName": "Smith",
        "firstName": "Jack"
      },
      {
        "lastName": "Smith",
        "firstName": "Jill"
      }
    ]
  }
}

The guest passes their own name as an additional name, exceeding the maximum occupancy of the room type.

E.g: guest books a K1 room that has maximum occupancy of 2, but adds their name under additional guests as well, bringing the total number of guests to 3.

                
{
  "roomStays": [
    {
      "numAdults": 2,
      "arrivalDate": "2025-04-01",
      "departureDate": "2025-04-03",
      "ratePlanCode": "XXXXXX",
      "roomTypeCode": "K1"
    }
  ],
  "guest": {
    "name": {
      "lastName": "Smith",
      "firstName": "John"
    },
    "additionalNames": [
      {
        "lastName": "Smith",
        "firstName": "John"
      },
      {
        "lastName": "Smith",
        "firstName": "Jane"
      }
    ]
  }
}

To resolve this issue, the guest can make the reservation, then add additional names to the specific GNRs after booking.
See the “additionalNames” parameter under Dc Reservation for usage and specification.

B6. Why do we receive an error stating rates are unavailable during reservation request even though the shop response returns availability for the same rate codes and room codes. (DerbySoft partners)

A: The standard shop response retrieves rates from a cache, which means room availability may have changed by the time a reservation request is made. It is recommended to perform a live check before proceeding with the booking in order to

Ensure you have the most up-to-date availability and rates
Reduce any booking errors due to unavailability.

The single product shop can be used to make live check calls to Hilton and allows you to shop for a specific ratePlanCode and roomTypeCode.
See Direct Connect - Shop Single Property | Hilton Dev Portal for documentation and Check for Available Rooms | Hilton Dev Portal for documentation

Cancel

Cx1. For multi room bookings, can I cancel all rooms in one go?

A: No, you must cancel each room separately. For multi-room bookings, each room has its own GNR number, and you need to use this along with the confirmation number to cancel. We recommend making a Retrieve (GET) call prior to cancelling a booking to ensure the reservation is still confirmed and the cancel deadline has not passed. For more information on cancelling, Please See Cancel a Reservation Stay | Hilton Dev Portal for documentation

Cx2. How can I determine if the reservation is cancellable?

A: It’s recommended to make a Retrieve (GET) request prior to cancellation to ensure the reservation is still pending and the cancellation deadline has not passed. This will help you confirm if the reservation is cancellable.
See Cancel a Reservation Stay | Hilton Dev Portal for documentation and Make & Manage Reservations | Hilton Dev Portal for documentation

Cx3. How can we read / determine cancellation penalty amount?

A: Hilton does not provide the cancellation penalty in the response message. However, you can determine the cancellation charges based on the following rules:

For a non-refundable rate the cancellation penalty is 100% of the stay.
For a stay with a deposit, the cancellation penalty is 100% of the deposit.
For a stay without a deposit, the cancellation penalty is 100% of the first night’s rate plus tax.