/booking_availability_v7

Booking availability requests are sent by adding /booking_availability to your endpoint and sending the parameters explained below in a POST request. 
 
When the booking availability results are returned, they are presented to the traveler beside the original hotel availability results. The traveler can then proceed to the next step of making a room booking.
 
(Note: The details shown in the following sample image are subject to change)
 
Content Sample IB Grid 

 

Please note that TripAdvisor will always expect a response with "api_version": 7 in it, with the respective fields required in a v7 response. In order to transition from our current v5 to v7 (new) API, TripAdvisor may send you a request with the "api_version": 5 and transition these to "api_version": 7 in the near future. Please ensure that your v7 endpoint accepts the TripAdvisor request with variant "api_version" (both 5 and 7).

Request

http://partner-site.com/api_implementation/booking_availability

ContentType: application/x-www-form-urlencoded

api_version=7
&hotel={
  "ta_id": 97497, 
  "partner_hotel_code": "sfssc1",
  "partner_url": "http://www.partner-site.com/hotelcommonwealth"
}
&start_date=2016-03-21
&end_date=2016-03-23
&party=[{"adults":2}]
&lang=en_US
&currency=USD
&user_country=US
&device_type=d
&query_key=6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2
&booking_session_id=c575ec5ae3c84294bf67c1b05590b3c2
&booking_request_id=CSI-xkundqpe4nfrtem2ypq2ygjfde 

Parameters

Name Type Description
api_version number The version of the API that this request is using.
hotel object JSON serializable hash representing requested hotel. 
key description type
ta_id TripAdvisor hotel IDs integer
partner_hotel_code Partner hotel ID string
partner_url Deeplink for this property. string
Example: hotel={"ta_id": 1128635, "partner_hotel_code": "1191", "partner_url": "http://partner.com/deeplink/to/1191"} Note: All your availability lookups must use your partner_hotel_code. The TripAdvisor ID can change as the site changes. The partner_url is mostly used for internal purposes. Partners implementing the API may ignore this parameter.
start_date string The check-in date of the traveler. The date will be in the form YYYY-MM-DD.
end_date string The check-out date of the traveler. The date will be in the form YYYY-MM-DD.
party array Array of JSON objects representing number of adults and children traveling. 
key description type
adults The number of adults staying in the room. integer
children [Optional] The ages of any children staying in the room. integer array
Each Party object represents a request for a separate room. For example, "party":[{“adults": 2}] is a request for 1 room that accommodates 2 adults, or "party":[{"adults": 3},{"adults": 2, "children": [9,5]}] is a request for 1 room for 3 adults and 1 room for 2 adults and 2 children for a total of 2 rooms.
lang string Language code (see Supported Languages). The language that TripAdvisor would prefer that the partner return with. If the partner does not have the language of the request, they can return a less specific language. e.g. If the request is asking for de_AT, then the response can be de. If the partner does not have the language specified by lang, they will not show up in Instant Booking.
query_key string String useful for debugging. It is recommended for this value to be logged.
currency string [Not always present] ISO 4217 currency code. All prices, taxes, fees, and discount amounts should be returned in this requested currency. If this is not possible, the currency should match the one seen by a user from the given user_country if present (see below). If the currency the user will be charged in differs to the requested currency, always send the currency of charge. For example TripAdvisor requests USD but hotel is based in UK and charges in GBP, in that instance send GBP, currency conversion will be handled by TripAdvisor.
user_country string [Not always present] ISO 3166-1 alpha-2 country code corresponding to the user making this request. If present, local taxes and fees must be included and the currency must match the one seen by a user from this country visiting your website. If this is not possible, return the local currency of the hotel. This parameter is required to be supported if pricing differs based on the country where the user makes the request.
device_type string [Not always present] Identifies the user’s device type. Takes values “d”, “m” or “t” corresponding to DESKTOP, MOBILE, or TABLET, respectively. This value is required if pricing differs by device type.
booking_session_id string [Not always present] The booking_session_id is primarily used for internal purposes. Partners implementing the API may ignore this parameter.
booking_request_id string [Not always present] The booking_request_id is primarily used for internal purposes. Partners implementing the API may ignore this parameter.

Response

ContentType: application/json

{
    "api_version": 7,
    "hotel_id": 730099,
    "start_date": "2016-03-21",
    "end_date": "2016-03-23",
    "party": [
        {
            "adults": 2
        }
    ],
    "lang": "en_US",
    "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
    "user_country": "US",
    "device_type": "d",
    "hotel_room_types": {
        "king1": {
            "code": "king1",
            "name": "Deluxe King Room",
            "description": "Plush King bed, deluxe beddings, recently renovated bathroom, smoking permitted",
            "photos": [
                {
                    "url": "https://www.partnersite.com/FenwayRoomBed.jpg",
                    "width": 200,
                    "height": 300,
                    "caption": "Image of King Bed"
                }
            ],
            "room_amenities": {
                "standard": [
                    20,
                    900118
                ],
                "custom": [
                    "My custom chair",
                    "Wolf appliances"
                ]
            },
            "room_size_value": 500,
            "room_size_units": "square_feet",
            "bed_configurations": [
               [{
                 "type": "standard",
                 "code": 3,
                 "count": 1
                 },
                 {
                  "type": "custom",
                  "name": "Loft",
                  "count": 1
                 }]
            ],
            "room_view_type": {
                "standard": [
                    10
                ],
                "custom": [
                    "Northern Lights"
                ]
            },
            "accessibility_features": {
                "standard": [
                    900501, 900505
                ],
                "custom": [
                ]
            },
            "max_occupancy": {
                "number_of_adults": 2,
                "number_of_children": 0
            },
            "room_smoking_policy": "smoking"
        },
        "king2": {
            "code": "king2",
            "name": "Deluxe King Room - Non Smoking",
            "description": "Plush King bed, deluxe beddings, recently renovated bathroom",
            "photos": [
                {
                    "url": "https://www.partnersite.com/FenwayRoomBed.jpg",
                    "width": 200,
                    "height": 300,
                    "caption": "Image of King Bed"
                }
            ],
            "room_amenities": {
                "standard": [
                    20,
                    101,
                    900118
                ],
                "custom": [
                    "My custom chair",
                    "Wolf appliances"
                ]
            },
            "room_size_value": 400,
            "room_size_units": "square_feet",
            "bed_configurations": [
               [{
                 "type": "standard",
                 "code": 3,
                 "count": 1
                 }],
               [{
                  "type": "standard",
                  "code": 5,
                  "count": 2
                 }]
             ],
            "extra_bed_configurations": [
               [{
                 "type": "standard",
                 "code": 4,
                 "count": 1
                 },
                 {
                  "type": "custom",
                  "name": "Rollaway with wheel locks and adjustable height",
                  "count": 1
                 }]
            ],
            "room_view_type": {
                "standard": [
                    10
                ],
                "custom": [
                    "Northern Lights"
                ]
            },
            "accessibility_features": {
                "standard": [
                    900504
                ],
                "custom": [
                ]
            },
            "max_occupancy": {
                "number_of_adults": 2,
                "number_of_children": 2
            },
            "room_smoking_policy": "non_smoking"
        }
    },
    "hotel_rate_plans": {
        "bar": {
            "name": "Best Available Rate",
            "code": "bar",
            "description": "Best available rate available in March, suitable for family stays under 7 days",
            "photos": [
                {
                    "url": "https://www.partnersite.com/Jetski_kayak.jpg",
                    "width": 200,
                    "height": 300,
                    "caption": "Image of rate amenities"
                }
            ],
            "rate_amenities": {
                "standard": [
                    75
                ],
                "custom": [
                    "Complimentary jetskis",
                    "Kayak rentals"
                ]
            },
            "cancellation_rules": {
                "deadline": "2016-03-17T16:00:00",
                "penalty_exists": true,
                "policy_info": "Partially refundable rate",
                "fees": [
                    {
                        "currency": "USD",
                        "amount_type": "numNights",
                        "amount": 2,
                        "tax_inclusive": true,
                        "days_before_arrival": 2
                    },
                    {
                        "currency": "USD",
                        "amount_type": "fixed",
                        "amount": 50,
                        "tax_inclusive": true
                        "days_before_arrival": 4
                    }
                ]
            },
            "meal_plan": {
                "standard": [
                    22
                ],
                "custom": [
                    "Brunch on weekend mornings"
                ]
            },
            "discount_type": {
                "standard": [
                    5
                ],
                "custom": []
            }
        },
        "online": {
            "name": "Online Discount",
            "code": "online",
            "description": "Exclusive, non-refundable rate for online reservations",
            "photos": [
                {
                    "url": "https://www.partnersite.com/NFL_cable.jpg",
                    "width": 200,
                    "height": 300,
                    "caption": "Image of cable TV selection"
                }
            ],
            "rate_amenities": {
                "standard": [
                    207
                ],
                "custom": [
                    "NFL Network"
                ]
            },
            "refundable": "none",
            "cancellation_rules": {
                "penalty_exists": true,
                "policy_info": "Non-refundable rate. No cancellations permitted, all taxes and fees will need to be paid.",
                "fees": [
                    {
                        "currency": "USD",
                        "amount_type": "percent",
                        "amount": 100,
                        "tax_inclusive": true
                    }
                ]
            },
            "meal_plan": {
                "standard": [
                    22
                ],
                "custom": [
                    "Brunch on weekend mornings"
                ]
            },
            "discount_type": {
                "standard": [
                    9
                ],
                "custom": [
                    "Online Discount"
                ]
            }
        }
    },
    "hotel_room_rates": [
        {
            "final_price_at_booking": {
                "amount": 240,
                "currency": "USD"
            },
            "final_price_at_checkout": {
                "amount": 0,
                "currency": "USD"
            },
            "hotel_room_type_code": "king1",
            "hotel_rate_plan_code": "bar",
            "partner_data": {
               "myhotel_code": "sfssc1",
               "myroom_code": "FENWAY",
               "rate_hotel_info": 1
            },
            "line_items": [
                {
                    "price": {
                        "amount": 220,
                        "currency": "USD"
                    },
                    "type": "rate",
                    "paid_at_checkout": false,
                    "description": "This is the base rate."
                },
                {
                    "price": {
                        "amount": 20,
                        "currency": "USD"
                    },
                    "type": "tax",
                    "paid_at_checkout": false,
                    "description": "This is a tax."
                }
            ],
            "payment_policy": "Valid ID with proof of payment required at check in",
            "rooms_remaining": 2
        },
        {
            "final_price_at_booking": {
                "amount": 220,
                "currency": "USD"
            },
            "final_price_at_checkout": {
                "amount": 0,
                "currency": "USD"
            },
            "hotel_room_type_code": "king1",
            "hotel_rate_plan_code": "online",
            "description": "",
            "partner_data": {
               "myhotel_code": "sfssc1",
               "myroom_code": "FENWAY_KNG",
               "rate_hotel_info": 2
            },
            "line_items": [
                {
                    "price": {
                        "amount": 200,
                        "currency": "USD"
                    },
                    "type": "rate",
                    "paid_at_checkout": false,
                    "description": "This is the base rate."
                },
                {
                    "price": {
                        "amount": 20,
                        "currency": "USD"
                    },
                    "type": "tax",
                    "paid_at_checkout": false,
                    "description": "This is a tax."
                }
            ],
            "payment_policy": "Valid ID with proof of payment required at check in",
            "rooms_remaining": 1
        },
        {
            "final_price_at_booking": {
                "amount": 200,
                "currency": "USD"
            },
            "final_price_at_checkout": {
                "amount": 0,
                "currency": "USD"
            },
            "hotel_room_type_code": "king2",
            "hotel_rate_plan_code": "bar",
            "description": "",
            "partner_data": {
               "myhotel_code": "sfssc1",
               "myroom_code": "FENWAY_KNG",
               "rate_hotel_info": 3
            },
            "line_items": [
                {
                    "price": {
                        "amount": 180,
                        "currency": "USD"
                    },
                    "type": "rate",
                    "paid_at_checkout": false,
                    "description": "This is the base rate."
                },
                {
                    "price": {
                        "amount": 20,
                        "currency": "USD"
                    },
                    "type": "tax",
                    "paid_at_checkout": false,
                    "description": "This is a tax."
                }
            ],
            "payment_policy": "Valid ID with proof of payment required at check in",
            "rooms_remaining": 5
        },
        {
            "final_price_at_booking": {
                "amount": 180,
                "currency": "USD"
            },
            "final_price_at_checkout": {
                "amount": 0,
                "currency": "USD"
            },
            "hotel_room_type_code": "king2",
            "hotel_rate_plan_code": "online",
            "description": "",
            "partner_data": {
               "myhotel_code": "sfssc1",
               "myroom_code": "FENWAY_KNG2",
               "rate_hotel_info": 4
            },
            "line_items": [
                {
                    "price": {
                        "amount": 160,
                        "currency": "USD"
                    },
                    "type": "rate",
                    "paid_at_checkout": false,
                    "description": "This is the base rate."
                },
                {
                    "price": {
                        "amount": 20,
                        "currency": "USD"
                    },
                    "type": "tax",
                    "paid_at_checkout": false,
                    "description": "This is a tax."
                }
            ],
            "payment_policy": "Valid ID with proof of payment required at check in",
            "rooms_remaining": 3
        }
    ],
    "hotel_details": {
        "name": "Hotel Commonwealth",
        "address1": "500 Commonwealth Avenue",
        "address2": "",
        "city": "Boston",
        "state": "Massachusetts",
        "postal_code": "02492",
        "phone": "8001234567",
        "checkinout_policy": "For early check in, please contact hotel.",
        "checkin_time": "12:00",
        "checkout_time": "14:00",
        "hotel_smoking_policy": {
            "standard": [
                47
            ],
            "custom": [
                "Strict non smoking policy"
            ]
        },
        "pet_policy": {
            "standard": [
                6
            ],
            "custom": [
                "My own pet policy if applicable"
            ]
        },
        "child_policy": "All children are welcome",
        "parking_shuttle": {
            "standard": [
                185
            ],
            "custom": [
                "You can park on curbside in a metered spot"
            ]
        },
        "extra_bed_policy_hotel": "Rollaway beds and cribs available on request",
        "hotel_amenities": {
            "standard": [
                5,
                15
            ],
            "custom": [
                "Bean bag chairs"
            ]
        },
        "photos": [
            {
                "url": "https://www.partnersite.com/hotel_lobby.png",
                "width": 200,
                "height": 300,
                "caption": "Hotel Lobby"
            },
            {
                "url": "https://www.partnersite.com/hotel_cafe.png",
                "width": 200,
                "height": 300,
                "caption": "Hotel Cafe"
            }
        ],
        "extra_fields": [
            {
                "id": "text1",
                "description": "Enter text",
                "required": false,
                "type": "text",
                "default_value": "foo"
            },
            {
                "id": "select2",
                "description": "Choose an option",
                "required": true,
                "type": "single_select",
                "field_values": [
                    {
                        "id": "first",
                        "description": "First option"
                    },
                    {
                        "id": "second",
                        "description": "Second option"
                    }
                ]
            }
        ]
    },
    "accepted_credit_cards": [
        "Visa",
        "MasterCard",
        "AmericanExpress"
    ],
    "customer_support": {
        "phone_numbers": [
            {
                "contact": "555-555-5555",
                "description": "Support phone line"
            }
        ]
    },
    "terms_and_conditions": "Terms and conditions text",
    "terms_and_conditions_url": "http://www.example.com/terms_and_conditions",
    "payment_policy": "Payment policy partner text - use this field for payment policies that apply to the entire hotel",
    "other_policy": "Other policy partner text"
}

Properties

Field Type Description
api_version number
The version of the API that this request is using.
hotel_id number Echo the ta_id (not partner_hotel_code) requested by TripAdvisor in the 'hotel' object.
start_date string Echo the start date requested by TripAdvisor. Use the same format as described in request.
end_date string Echo the end date requested by TripAdvisor. Use the same format as described in request.
 

party array Echo the party array requested by TripAdvisor. Use the same format as described in request.
lang string Language code (see Supported Languages). The language of the response.
query_key string Echo the query key in the request by TripAdvisor.
user_country string
Echo the user country in the request by TripAdvisor.
device_type string [Not always present] Identifies the user’s device type. Takes values “d”, “m” or “t” corresponding to DESKTOP, MOBILE, or TABLET, respectively. This value is required if pricing differs by device type.
hotel_room_types  HotelRoomTypeCode map Map object that maps codes to objects.
The codes are the hotel room type codes.
The objects provide the details for the hotel room type.
hotel_rate_plans HotelRatePlanCode map
Map object that maps codes to objects.
The codes are the hotel rate plan codes.
The objects provide the details for the hotel rate plan.
hotel_room_rates

HotelRoomRates array

An array of objects detailing the different room and rate combinations for the entire party.
hotel_details HotelDetails 
Required object containing information about the hotel in general, such as address. This information will be presented to the customer during booking.
accepted_credit_cards string
An array of strings. Each string must be one of these values (case insensitive):
 
  • Visa
  • MasterCard
  • AmericanExpress
  • Discover
TripAdvisor requires a credit card at time of booking not only to support a hotel’s guarantee policy but also to reduce fraud. In the case where a hotel does not require a credit card guarantee, it will be up to the partner to either pass or not pass the credit card details to the hotel. If the hotel does not support a credit card at the time of booking, please return a shortened list of the standard supported types (MasterCard, Visa).
terms_and_conditions string
General terms and conditions.
Text field.
Length limit: 1000 characters.
terms_and_conditions_url string
[Optional] Link to the partner's terms and conditions page.
payment_policy string
Describes how the Partner will use the credit card information, e.g. charged immediately or hold.
Text field.
Length limit: 1000 characters.
other_policy string
[Optional] Miscellaneous policies.
Text field.
Length limit: 1000 characters.
customer_support CustomerSupport
A required object containing the hotel’s customer support contact information for guests.
This must be returned on both successes and failures.
errors Error array
Optional array of errors. The format and types of errors are described below.
 

Structure of Room and Rate Mapping

 Room Rate Mapping

HotelRoomTypes

The "hotel_room_types" map consists of the following fields, with their respective types and descriptions.

HotelRoomTypes

Field

Type Description
hotel_room_types HotelRoomTypeCode map
Map object that maps codes to objects.
The codes are the hotel room type codes.
The objects provide the details for the hotel room type.

 

HotelRoomTypeCode
Field Type Description
"<hotel_room_type_code>"

HotelRoomType

The hotel_room_type_code is itself a string. This value of the string is determined by the Connectivity Partner.
 
The hotel_room_type_code maps to a HotelRoomType object.

 

HotelRoomType
Field Type Description
code

string

The code must have the same value as the HotelRoomTypeCode. 
The hotel_room_type_code is itself a string. This value of the string is determined by the Connectivity Partner. The room type code must be unique for each room available in the hotel
name string
The name of this room type. Room names must summarize 1-2 significant selling points for the room, ideally in less than 50 characters. For example, you can include the bed type configuration information and the room view in the name (e.g. “One Bedroom Suite, One King Bed”, “Courtyard King”, “Garden View Room, King”, “King Studio”); or simply match the room name to brand.com
 
If a room name consists of only numbers and symbols, or is shorter than 4 characters, it will be blocked from Instant Booking.
description string
Longer room description. This will be displayed to end users, and should be in the language indicated by the 'lang' parameter. Ideal room descriptions are 250-400 characters in length. They are written in third person voice and highlight selling point for the room. For example, “This one-bedroom suite has a king bed. This corner suite also features a separate living room with a sofa bed, a well-equipped kitchen with complimentary grocery delivery services, and Paul Mitchell bath products.”
 
Max length 1000 characters. If a room name consists of only numbers and symbols, or is shorter than 4 characters, it will be blocked from Instant Booking. See supported HTML tags.
photos Photo array
An array of photo objects for the room.
room_amenities object

Array of number codes. Each code corresponds to an amenity for the OpenTravel Hotel Amenity Code List.  A map of the standard room amenities is listed under the Supported Amenities section.

The standard amenities will be returned as an integer array. If an amenity does not exist in the Supported Amenities list, then the Connectivity Partner may provide their own values. Return "custom":[ ] if no custom list exists.

Example:
{ "standard": [1 ,2, 5, 20, 60,], "custom": ["myamenity1", "myamenity2"] }

max_occupancy map of string:int

Maximum number of guests permitted in the room. {"number_of_adults": <num_adult>, "number_of_children": <num_child>}.

Example: {"number_of_adults": 3, "number_of_children": 2 }
room_size_value int [Optional] Integer value denoting room area. Specify the unit of measurement in room_size_units
room_size_units string

[Optional] Must be specified if room_size is provided. Pick one of the two options (derived from OpenTravel's Unit of Measurement code list - UOM ):

  • square_feet
  • square_meters
bed_configurations object

Specify the bed types for a room, and if needed multiple bed configurations available. The type of bed provided is based on OpenTravel BED code table: 

1 Double
2 Futon
3 King
4 Murphy Bed
5 Queen
6 Sofa Bed
7 Tatami Mats
8 Twin
9 Single
10 Full
11 Run of the House
12 Dorm Bed

 

The bed_configurations property is a list of one or more bed configuration objects. The bed configuration object is made up of one or more bed types objects. A bed type object can take one of two formats, "standard" or "custom", represented by the "type" field. A standard bed type must populate the "code" field with a integer representing the bed type. We encourage you to provide integer codes for available beds, as this will help toward localized content on TripAdvisor. If a "standard" bed type does not exist in the table above, then the Connectivity Partner may provide their own values in the "custom" field as a string.

Example: This room has only one bed configuration which includes both one King Bed AND one Loft Bed. We will use the "code":3 to represent the King Bed type from the codes listed in table above

           
           "bed_configurations": [
               [{
                 "type": "standard",
                 "code": 3,
                 "count": 1
                 },
                 {
                  "type": "custom",
                  "name": "Loft",
                  "count": 1
                 }]
            ]

 

Example: This room has two bed configurations, either one king bed OR two double beds.

            "bed_configurations": [
               [{
                 "type": "standard",
                 "code": 3,
                 "count": 1
                 }],
               [{
                  "type": "standard",
                  "code": 1,
                  "count": 2
                 }]
             ]

 

We encourage you to provide bed configurations available in this object and discontinue usage of "bed_type".

extra_bed_configurations object

Provide information on additional beds and configurations available. Based on OpenTravel BED code table:

1 Double
2 Futon
3 King
4 Murphy Bed
5 Queen
6 Sofa Bed
7 Tatami Mats
8 Twin
9 Single
10 Full
11 Run of the House
12 Dorm Bed
900301 Roll-Away Bed
900302 Crib
900303 Extra Beds Available on Request

 

The exta_bed_configurations property is a list of one or more bed configuration objects. Use this field to indicate extra bed's that can be made available to guests in a room. the property follows similar syntax to bed_configurations (see above).

Example: This room has two bed configurations, either one king bed OR two double beds. Additionally, a crib and custom roll-away bed are available on request.

            "bed_configurations": [
               [{
                 "type": "standard",
                 "code": 3,
                 "count": 1
                 }],
               [{
                  "type": "standard",
                  "code": 1,
                  "count": 2
                 }]
             ],

            "extra_bed_configurations": [
               [{
                 "type": "standard",
                 "code": 900302,
                 "count": 1
                 },
                 {
                  "type": "custom",
                  "name": "Rollaway with wheel locks and adjustable height",
                  "count": 1
                 }]
             ]

We encourage you to provide any extra bed configurations available in this object and discontinue usage of "extra_bed_type".

room_view_type object [Optional] Choose from available OpenTravel codes for Room View Type when available: 
1 Airport view
2 Bay view
3 City view
4 Courtyard view
5 Golf view
6 Harbor view
7 Intercoastal view
8 Lake view
9 Marina view
10 Mountain view
11 Ocean view
12 Pool view
13 River view
14 Water view
15 Beach view
16 Garden view
17 Park view
18 Forest view
19 Rain forest view 
20 Various views 
21 Limited view 
22 Slope view 
23 Strip view
24 Countryside view
25 Sea view

 

The standard extra_bed_type will be returned as an integer array. If a room_view_type does not exist in the table above, then the Connectivity Partner may provide their own values in the "custom" field as a string array. Return "custom":[ ] if no custom list exists.

Example: { "standard": [1,2,25], "custom": ["extra bed not available", "myextratype"] }

Example: {"standard": [2, 25], "custom": [ ]}

accessibility_features object

[Optional] Choose from available codes for accessibility features below:

900501 ADA compliant
900502 Compliant with local laws for disabled
900503 Accessible
900504 Mobility accessible
900505 In-room accessibility
900506 Accessible for blind
900507 Hearing accessible
900508 Roll-in shower
900509 Grab bars in bathroom

 

The standard accessibility features will be returned as an integer array. If an accessibility feature does not exist in the table above, then the Connectivity Partner may provide their own values in the "custom" field as a string array. Return "custom":[ ] if no custom list exists. We encourage you to avoid custom accesibility features, as this may hinder international rollout, and not allow display of standard accessibility icons for travelers. 

Example: {"standard": [900504, 900505], "custom": [ ]}

room_smoking_policy string
  • smoking
  • non_smoking

We also capture hotel_smoking_policy in HotelDetails. The options specified here should not invalidate information at the Hotel level. In the case of a mismatch, TripAdvisor will not display this information.

 

HotelRatePlans

The new "hotel_rate_plans" map consists of the following fields, with their respective types and descriptions.

HotelRatePlans

Field

Type Description
hotel_rate_plans HotelRatePlanCode map
A map object, which maps codes to objects.
The codes are the hotel rate plan codes.
The objects provide the details for the hotel rate plan.

 

HotelRatePlanCode
Field Type Description
"<hotel_rate_plan_code>"

HotelRatePlan

The hotel_rate_plan_code is itself a string. This value of the string is determined by the Connectivity Partner.
 
The hotel_rate_plan_code maps to a HotelRatePlan object.

 

HotelRatePlan
Field Type Description
code

string

The code must have the same value as the HotelRatePlanCode. 
The hotel_rate_plan_code is itself a string. This value of the string is determined by the Connectivity Partner. The rate plan code must be unique for each rate plan available in the hotel.
name string
The name of this rate plan.
For example, "Best Available Rate"
description string
Longer rate description. This will be displayed to end users, and should be in the language indicated by the 'lang' parameter.
Max length 1000 characters.
See supported HTML tags.
photos Photo array
[Optional] An array of photo objects for the rate plan.
rate_amenities object

Array of number codes where each code corresponds to a rate amenity. Each code corresponds to an amenity for the OpenTravel Hotel Amenity Code List. A map of the standard room amenities is listed under the

Supported Amenities  section. Use this list to specify amenities that are specific to the rate plan, such as "Executive Club Lounge Access", "English Breakfast Included," etc.

The standard amenities will be returned as an integer array. If an amenity does not exist in the Supported Amenities list, then the Connectivity Partner may provide their own values.

Example:
{ "standard": [1,2,5], "custom": ["myamenity1", "myamenity2"] }

refundable  string

We strongly encourage the use of cancellation_rules as this will enable TripAdvisor to display useful information to your customers, including "policy_info" text that is currently displayed to travelers. This field may be omitted if you are already providing cancellation_rules. 

Must be one of:

  • none - "no refund provided if cancelled"
  • partial - "After time of booking there is a charge less than the total reservation amount required for cancellation--the difference is then refunded"
  • full -  "There exists a time between time of booking and time of arrival where the reservation may be cancelled without any charge to the user. Reservations whose free cancellation expires within N days of time of arrival may still be marked fully refundable unless time of booking is within N days of time of arrival"
  • unknown - “cannot provide a refund policy” (Default)
cancellation_rules  object

Container for cancellation rules and policies. We encourage you to provide all the fields available to you. Contains the fields listed below: 

Name Type Description
deadline string

The date and time after which it is not free to cancel a reservation. Omit if the rate is non-refundable.

The format must match yyyy-MM-dd'T'HH:mm:ss. Please note there is no timezone info because it is localized to the property.

Example:

"cancellation_deadline": "2016-05-25T16:00:00"
penalty_exists boolean

true/false

policy_info string Text describing the cancellation policy for the room. Should be in the language indicated by the 'lang' parameter. Max length 1000 characters.
fees array of objects

Contains fees associated with cancellation. Specify multiple objects if cancellation fees change depending on days prior to arrival. The fees object determines combinations of cancellation cost for a booking.

Name Type Description
currency string ISO 4217 currency code. All prices, taxes, fees, and discount amounts should be returned in this requested currency. 
amount_type string
  • fixed
  • percent
  • numNights
days_before_arrival number Number of days prior to arrival. This field is specifically useful when there are multiple fee schedules. See example in JSON response above.
amount number

Amount charged.

If "amount_type" is "fixed", the "amount" will represent the fixed fee associated.

If "amount_type" is "percent", the "amount" will represent the percentage charged

If "amount_type" is "numNights", the "amount" will represent the number of nights

tax_inclusive boolean
  • true
  • false

This field is required for "fixed" amount_type.

For all other amount_type ("percent" and "numNights"), the traveler is liable to pay the tax associated with the amount_type, to be determined by Partner. If not returned, a default value of "true" will be assumed. A sample snippet of what TripAdvisor may display "Cancellation fees of 2 nights + tax for cancellations made after 03-17-2016, 16:00 local time".

For "tax_inclusive" = true, amount_type of "fixed", amount of "100", currency = "USD" - the traveler will be charged a "cancellation fee of 100USD + tax"

 

 

Example: /currency = "USD", /amount_type = "percent", /amount = 50, /days_before_arrival= 14 will translate to “Cancellation fee of 50% of booking + taxes if cancelled 14 days prior to arrival, in USD”

Example: /currency = "USD", /amount_type = "fixed", /amount = 50, /tax_inclusive = false, /days_before_arrival = 2 will translate to “Cancellation fee of 50 USD if cancelled 2 days prior to arrival, no additional taxes will be charged”

meal_plan object

Choose from available OpenTravel codes for meal plans (MPT):

1 All inclusive
2 American
3 Bed & breakfast
4 Buffet breakfast
5 Caribbean breakfast
6 Continental breakfast
7 English breakfast
8 European plan
9 Family plan
10 Full board
11 Full breakfast
12 Half board / modified American plan
14 Room only
15 Self catering
17 Dinner bed and breakfast plan
18 Family American
19 Breakfast
20 Modified
21 Lunch
22 Dinner
23 Breakfast & lunch

 

The standard meal_plan will be returned as an integer array. If a meal_plan does not exist in the table above, then the Connectivity Partner may provide their own values in the "custom" field as a string array. Return "custom":[ ] if no custom list exists.

Example: { "standard": [1,2], "custom": ["All you can eat", "Special breakfast"] }

Example: {"standard": [2, 4], "custom": [ ]}

discount_type  object

[Optional] Choose from available codes for Discount Types when available, based on OpenTravel Discount Types: 

 

1 AAA
2 AARP
3 Convention
4 Corporate
5 Family
6 Government
7 Group
8 Military
9 Promotional
10 Senior citizen
11 Tour
12 Weekday
13 Weekend
900001 Resident
900002 Non resident
900003 Out of state
900004 Attraction package

 

The standard discount_type will be returned as an integer array. If a discount_type does not exist in the table above, then the Connectivity Partner may provide their own values in the "custom" field as a string array. Return "custom":[ ] if no custom list exists.

Example: { "standard": [1,10], "custom": ["Florida resident discount", "Buy with sea world tickets and save"] }

Example: {"standard": [2, 4], "custom": [ ]}

 

HotelRoomRates

Field Type Description
hotel_room_type_code string
The identifier for the room type, used to find the associated room type from hotel_room_types in the response. The code must have the same value as one of the room types contained in the HotelRoomTypes map
hotel_rate_plan_code string
The identifier for the rate plan, used to find the associated rate plan from hotel_rate_plans in the response. The code must have the same value as one of the rate plans contained in the HotelRatePlans map.
final_price_at_booking Price object
An object containing the entire price to be paid at time of booking, including taxes and fees. This will be used to validate the line items.
final_price_at_checkout Price object
An object containing the entire price to be paid at time of stay, including taxes and fees. This will be used to validate the line items. If the full price is paid at the time of booking, this element must still be included, with an amount of 0 or 0.00.
line_items LineItem array
An object containing the detailed breakdown of charges.
payment_policy string
How will the partner use the credit card information, e.g. charged immediately or hold. Large text field.
rooms_remaining integer The number of rooms remaining / available at a given hotel for a given roomtype at a given price. This number should be >0.
other_policy string
[Optional] Miscellaneous policies. 
extra_fields Field array
[Optional] An array of extra fields the partner wants the user to fill in.
partner_data number, string or object
 

This data will not be interpreted by TripAdvisor, but will be sent back to the partner as-is when we attempt a booking. For example, this field might be used to store a partner 'rate key,’ ‘room key,’ and/or ‘product key.’ It can consist of arbitrary nested JSON, or a single string or number.

 
 

HotelDetails

Required object containing information about the hotel in general, such as address.  This information will be presented to customer during booking. 

Field Type Description
name string The name of this hotel
address1 string Street Address
address2 string [Optional] Additional address information
city string
Town or city
state string [Optional] State or province
postal_code string [Optional] Zip code or postal code
country string ISO 3166 country code
latitude number [Optional] Latitude coordinate
longitude number [Optional] Longitude coordinate
phone string Telephone number of the hotel
url string URL for general hotel contact, not a booking page.
hotel_amenities object

Array of integer codes where each code corresponds to a hotel level amenity. These amenities are not tied to a specific room but are applicable to the hotel, for e.g. “24 hour airport shuttle.” A map of the standard room amenities is listed under the Supported Amenities section, derived from from the OpenTravel Hotel Amenity Code List.  

Example: { "standard": [1 ,2, 5, 20, 60,], "custom": ["myamenity1", "myamenity2"] }

photos Photo array

URLs for photos of the hotel to be displayed during the booking process.

If no photos are available, an empty array should be returned.

checkinout_policy string Text describing the check-in/check-out policy for the hotel. Include items needed at check-in, e.g. “Please present valid identification and credit card used for booking.” Should be in the language indicated by the 'lang' parameter. Max length 1000 characters. 
checkin_time string HH:MM Specified in local time zone.
checkout_time string  HH:MM Specified in local time zone.
hotel_smoking_policy object

Use one of the following options (derived from HAC, GRI tables of OpenTravel):

47 All rooms non-smoking
198 Non-smoking room (generic)
268 All public areas non-smoking
900201 Smoking permitted in designated areas and rooms

Allow for custom smoking_policy info (similar to all the custom fields above)

Example: {"standard": [2, 4], "custom": [ ]}

child_policy string [Optional] Text to indicate special considerations for children. For example “Adult only resort” or “Children over 5 years”. If no information is provided, default to null.
pet_policy string [Optional] Derived from the PET code list of OpenTravel. Omit from response if you cannot provide this information:
1 Cats only
2 Dogs only
3 Large domestic animals
4 Midsize domestic animals
5 Small domestic animals only
6 Working animals only
7 All pets
8 Small domestic animals
9 Working animals
10 Domestic pets
900401 Pets not allowed

 

Example: {"standard": [2, 4], "custom": [ ]}

parking_shuttle object

[Optional] Derived from HAC code list of OpenTravel, describing parking and/or shuttle availability options to major transportation. Omit from response if you cannot provide this information.

41 Free airport shuttle
42 Free parking
53 Indoor parking
63 Off-site parking
64 On-site parking
65 Outdoor parking
68 Parking
75 Recreational vehicle parking
94 Truck parking
97 Valet parking
116 Accessible parking
171 Parking fee managed by hotel
184 Parking lot
185 Parking deck
186 Street side parking
189 Motorcycle parking
192 Bus parking
216 Long term parking
230 Secured parking
282 Airport shuttle service
293 Parking - controlled access gates to enter parking area
305 Shuttle to local businesses
306 Shuttle to local attractions
329 Limited parking
331 No parking available

 

Example: {"standard": [2, 331], "custom": [ ]}

Example: {"standard": [2, 4], "custom": ["Valet parking charges apply", "Shuttle to nearest subway station on Green Line"]}

 extra_bed_policy_hotel string

[Optional] Provide information on additional beds and configurations available. Omit from response if you cannot provide this information.

Example “Rollaway bed available”, “Crib”, “Extra beds available on request”
extra_fields object array [Optional] An array of extra fields the partner wants to display. Omit from response if you cannot provide this information.

 

Example: Price Validation

This example demonstrates the Price Validation Logic in detail. We consider "at booking" every payment that has to be made during the booking process. For example, the property may want to charge 50% as a security deposit early in the booking process, and the remaining 50% at a different stage afterwards. The "at checkout" indication is the amount the guest will pay at the moment they leave the property. 
 
In line_items, we have three mechanisms to provide prices: rates, taxes, and fee information. For each of those prices there is a true-or-false data field called "paid_at_checkout". If this value is "false", we assume that the amount is paid at booking. If it is true, the amount is paid at checkout. When we validate all of the amounts, we search through "line_items", take all the prices that have the flag "paid_at_checkout" equal to "true", sum the values, and then finally compare with the value of the "final_price_at_checkout" field. The values must add up, otherwise an error will be thrown. Similarly, we get all the prices with the flag "paid_at_checkout" equal to "false", sum these values, and then finally compare with the value of the "final_price_at_booking" field.
 

In summary, to build the "line_items" correctly the value of the final price for a property must be obtained first, then how much of it is taxes and fees must be determined.  Once these three figures are found, the breakdown on how much of each is to be paid at booking and how much is to be paid at checkout needs to be clarified.

Example calculation:

"line_items": [
 {
    "price": { "amount": 425.28, "currency": "USD" },
    "type": "rate",
    "description": "Rate",
    "paid_at_checkout": false
 },
 {
    "price": { "amount": 50.65, "currency": "USD" },
    "type": "tax",
    "description": "Tax",
    "paid_at_checkout": false
 },
 {
    "price": { "amount": 124.14, "currency": "USD" },
    "type": "rate",
    "description": "Rate",
    "paid_at_checkout": true
 },
 {
    "price": { "amount": 24.85, "currency": "USD" },
    "type": "tax",
    "description": "Tax",
    "paid_at_checkout": true
 }]

The total price at booking is the sum of everything that has the "paid_at_checkout" flag set to "false", and the total price at checkout is the sum of everything with flag set to "true".

At booking the guest would pay 425.28 + 50.65.

At checkout they would pay 124.14 + 24.85.

Example: Multiple Rooms

This example demonstrates how to work with multiple parties and multiple rooms.

The booking_availability response is exactly the same whether a single room (single object in the ' party' array) or multiple rooms (multiple objects in the ' party' array) are in the booking_availability request.

There are, however, some considerations as follows.

Using this as an example party array in the request: [{"adults": 3},{"adults": 2}], you can follow these guidelines when constructing the response:

  1. When we request multiple rooms you should send all rooms that can accommodate the largest party.
  2. In this case, you should respond with all available rooms that can accommodate 3 adults or more. 
  3. You should not send rooms that can accommodate only 2 adults or less. 
  4. You should also send only the room types that have available a number of rooms equal or greater than the number of parties. In this case there are two parties.
  5. The prices should be the total for the number of days and party. We will then divide it and come up with the price per night and per guest. The attributes used for these total values are the final_price_at_checkout, final_price_at_booking and line_items.

Another example party array might look as follows: [{"adults": 1},{"adults": 2},{"adults": 4}]
You should return all the room types that can accommodate the maximum number of adults (in this case 4) and have available at least the same number as the number of rooms requested (in this case 3).

Suppose that a hotel has a room type called “Double suite” that can accommodate 4 adults and a room type called “Large Double suite” that can accommodate 6. Both these room types could be returned in the response if the hotel has at least 3 rooms available of each.

All room types that can accommodate 1 or 2 adults maximum have to be excluded, and all room types that have less than 3 rooms available also have to be excluded.

Note that in the subsequent booking_submit request, there may be multiple rooms required to process the booking for the given ‘party’, but they will all be the same room-type .

API Objects

Error Object

If the errors array is present, please include as many complete attributes in the response as available. The api_version is required.

Field Type Description
error_code number
One of these error codes:
1 Unknown Error
2 Cannot Parse Request
3 Invalid Hotel ID. If partner_hotel_code is unknown, return this.
4 Timeout requested. Stops requests for the specified time.
5 Recoverable Error. Equivalent to http 503.
message string
[Optional] String describing the error. Used for debugging. Maximum length is 1000 characters.
timeout number
[Optional] Number of seconds we should stop sending requests for use with Error Code 4
hotel_id number
[Optional] The ta_id (not partner_hotel_code) of the hotel that this error applies to.

Example

In this case the hotel requested had an invalid hotel ID.

"errors": [
    {
        "error_code": 3,
        "message": "Hotel code 114134 is no longer used.",
        "hotel_ids": [
            114134
        ]
    }
]


Customer Support

This object contains details that the customer can contact for support with the booking. This object must be present for successful API responses, in addition to failure state API responses (for example, if a booking_submit call fails this object must be included).

A phone number that the customer can contact for support is required in the phone_numbers array.

Field Type Description
phone_numbers Contact array
An array of customer support phone numbers.
emails Contact array
An array of customer support emails.
urls Contact array
An array of customer support urls.

Photo

Field Type Description
url string
URL for the photo.
thumbnail_url string
[Optional] URL for thumbnail of photo.
caption string
[Optional] Caption for the photo. Should be in the language indicated by the 'lang' parameter in the request.
width number
[Optional] Width in pixels of full size photo.
height number
[Optional] Height in pixels of full size photo.

 

LineItem

An array of LineItem objects will contain a separate LineItem for each of rate, tax, and fee types.

Field Type Description
price Price object
An object containing the price of the line item.
type string
Describes the charge. Must be one of these values:
 
  • rate
  • tax
  • fee
paid_at_checkout boolean true if the charge will be paid at the time of stay. false if it will be paid at time of booking.
description string
A textual description for the charge. This may be displayed to end users, and should be in the language indicated by the 'lang' parameter in the response.

 

The following example shows how an array of LineItem objects can be used to represent the various pricing components of a room price. Let's say the following components make up a room price:

  • Base rate: 75 EUR
  • Taxes: 20 EUR
  • Fees: 5 EUR

The hotel requires that these components be paid as follows:

  • final_price_at_booking: 25 EUR (hotel charges taxes and fees immediately when booking was made)
  • final_price_at_checkout: 75 EUR (balance is paid at checkout)

Here is what the corresponding line_items for this price would look like:

line_items: [
{
    "price": {
        "amount": 75,
        "currency": "EUR"
    },
    "type": "rate",
    "paid_at_checkout": true,
    "description": "Base price"
},
{
    "price": {
        "amount": 5,
        "currency": "EUR"
    },
    "type": "fee",
    "paid_at_checkout": false,
    "description": "Resort fee"
},
{
    "price": {
        "amount": 20,
        "currency": "EUR"
    },
    "type": "tax",
    "paid_at_checkout": false,
    "description": "Total tax amount"
}
]



























Price

Field Type Description
amount number
The value of the price.
currency string
ISO 4217 currency code for the price.  

Customer

Field Type Description
first_name string
First name of the user booking the reservation.
last_name string
Last name of the user booking the reservation.
phone_number string
Phone number of the user booking the reservation.
email string
Email of the user booking the reservation.
country string
ISO 3166 country code of the user booking the reservation.

Customer Support

This object contains details that the customer can contact for support with the booking. This object must be present for successful API responses, in addition to failure state API responses (for example, if a booking_submit call fails this object must be included).

A phone number that the customer can contact for support is required in the phone_numbers array.

Field Type Description
phone_numbers Contact array
An array of customer support phone numbers.
emails Contact array
An array of customer support emails.
urls Contact array
An array of customer support urls.

 

RoomStay

Object to describe details of the primary traveler and party for a room.

Field Type Description
party Party object
An object containing the number of adults and children staying in this room.
traveler_first_name string
First name of the primary traveler staying in this room.
traveler_last_name string
Last name of the primary traveler staying in this room.