API Objects

Configuration

Field Type Description
emergency_contacts

ContactInfo array

Array of Technical Contact Info objects. Must be present. Must include technical contacts to be notified in case of urgent API issues.
info_contacts ContactInfo array Array of Contact Info objects. Must be present.
languages string array [Optional] Array of strings. This is a list of languages that the partner supports. Use the least specific language possible, e.g. If the partner supports all English regardless of country, list only “en”. Do not list all the currently supported variants of English. TripAdvisor may still send requests that do not use one of the partner’s supported languages. If this happens, the response can be any language the partner chooses; however, TripAdvisor will not allow this property to be displayed in Instant Booking for that particular locale.
pref_hotels number [Optional] Preferred number of hotels per availability request. TripAdvisor may still request a different number of hotels in one request. This is a suggestion to TripAdvisor.
five_min_rate_limit number [Optional] Preferred rate limit, number of requests over 5 minutes. This is a suggestion to TripAdvisor.

ContactInfo

Field Type Description
full_name string
The full name of the contact
email string
The email address for the contact. Maximum of 256 characters.
phone_number string
The phone number for the contact. maximum of 50 characters.

InventoryHotel

Object used in required hotels array containing information about a particular hotel. 

Used in: hotel_inventory

Field Type Description
ta_id number [Optional] The TripAdvisor identification number for this hotel. This is used to aid our automated matching process but does not guarantee that a match will be found.
partner_id string The unique string that the parter uses to identify this hotel. Maximum length 30 characters. Required for mapping purposes and availability requests. Each hotel must have a unique partner_id.
name string
Name of the hotel, in English. Maximum 300 characters. Required for automated matching. May not be blank.
street string
Street address, in English. Maximum 300 characters. Field required for automated matching. May not be blank.
city string
City of the hotel, in English. Maximum 100 characters. Required for automated matching. May not be blank.
postal_code string
[Optional] Postal Code for the hotel. Maximum 20 characters. Highly suggested to assist automated matching.
state string

State is required for all addresses from the United States (US), Australia (AU), Canada (CA), Malaysia (MY) and Philippines (PH).

For addresses from the United Kingdom (GB), New Zealand (NZ), Ireland (IE), Singapore (SG), South Africa (ZA), France (FR) and others the state is optional.

State, province, or other mid-level geographic region of the hotel, in English. Maximum 100 characters.
country string
Country of the hotel, in English. Maximum 100 characters. Required for automated matching. May not be blank.
latitude number
[Optional] Latitude of the hotel.
longitude number
[Optional] Longitude of the hotel.
desc string
[Optional] Description of the hotel. Maximum 1000 characters.
url string
The URL of the hotel on the partner site. Make this URL as specific as possible for the hotel and it must be unique in your inventory. Duplicate URLs in the Hotel Inventory will cause the feed import to fail. This URL must be accessible with a GET request. Maximum 2000 characters. Required for availability requests.
email string
[Optional] Email address of the hotel. Maximum 256 characters.
phone string
[Optional] Phone number of the hotel. Maximum 50 characters.
fax string
[Optional] Fax number of the hotel. Maximum 50 characters.
room_types

Map of Inventory

 

 objects

[Optional] Map that use a short description as the key and an inventory room type object as the value. The maximum length of the short description is 100 characters. The room type short descriptions listed for a hotel must be distinct.

InventoryRoomType

Field Type Description
url string
[Optional] The URL of the hotel on the partner site. Make this URL as specific as possible. This URL must be accessible with a GET request. Maximum 2000 characters.
desc string
[Optional] Description of the room type. Maximum 1000 characters.

RoomTypes

Used in: availability

Field

Type Description
room_types RoomType map

Affected when all flags below are true:

  • multiple_room_rates

A map from room type keys to room types. At minimum, there must exist a room type entry for every unique room_type_key used in room_rates RoomRate objects.

 

Field Type Description
persistent_room_type_code

string

This is optional.
This code identifies unique room types. We expect that this code persists across future availability calls. The combination of persistent_room_type_code and partner_hotel_code must be unique.
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

Provide when all flags below are true:

  • room_type_details
  • text
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."

Language specific requirements will be applied. For example, if a room description in English consists of only numbers and symbols, or is shorter than 4 characters, it may be blocked. See supported HTML tags.
photos Photo array

Provide when all flags below are true:

  • room_type_details
  • photos

List of photos of the room.

Image file type should be able to render on modern web browsers (JPG, PNG, GIF) (TIFF is not supported). Photos should support https.
room_amenities object

Provide when all flags below are true:

  • room_type_details

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. Hotel and room amenities are provided in separate parts of the response, and should not overlap. For example, amenities that have no bearing on the room (e.g. “free parking”) should not be included as a room amenity, but rather as a hotel amenity.  We recommend rooms offer a minimum of 10 amenities.

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

Provide when all flags below are true:

  • room_type_details

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 map of string:int

Provide when all flags below are true:

  • room_type_details

 Area of room in given units. If given, both value and unit are required.

Example: {"value":500, "unit": "square_feet" }

bed_configurations object

Provide when all flags below are true:

  • room_type_details 

A list of one or more possible configurations.

In order for a bed configuration to be valid, at least one element must exist in either the standard array or custom array.
Two or more configurations mean that the room could be configured to contain either (any) of these set ups.

For example, the following snippet illustrates how to represent two bed configurations, either one king bed OR two double beds:

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

The following snippet illustrates how to represent one bed configuration, with a crib AND a custom bunk bed:

"bed_configurations": [
  { "standard": [ { "count": 1, "code": 900302 } ],
    "custom": [ { "count": 1, "name": "Bunk bed"} ] }
]

 

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
900301  Roll-Away Bed
900302  Crib
900303  Unspecified Bed

 

extra_bed_configurations object

Provide when all flags below are true:

  • room_type_details

A list of one or more possible extra bed configurations.
Extra bed configurations are configurations of extra beds that can physically be added to the RoomType for the guest on request. This service may or may not be included in the price of this room.

In order for an extra bed configuration to be valid, at least one element must exist in either the standard array or custom array.
Two or more configurations mean that the room could be configured to contain either (any) of these set ups.

For examples, see bed_configurations.

room_view_type object

Provide when all flags below are true:

  • room_type_details

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 room_view_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": ["my own view of the dunes"] }

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

accessibility_features object

Provide when all flags below are true:

  • room_type_details

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

Provide when all flags below are true:

  • room_type_details

Options:

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

RatePlans

Used in: availability

Field

Type Description
rate_plans RatePlan map

Affected when all flags below are true:

  • multiple_room_rates

A map from rate plan keys to rate plans. At minimum, there must exist a rate plan entry for every unique rate_plan_key used in room_rates RoomRate objects.

 

Field Type Description
persistent_rate_plan_code string This is optional.
This code identifies unique rate plans. We expect that this code persists across future availability calls. The combination of persistent_rate_plan_code and partner_hotel_code must be unique.
name  string
The name of this rate plan. For example, "Best Available Rate".
 description  string Provide when all flags below are true:
  • rate_plan_details
  • text

Longer rate description. This will be displayed to end users, and should be in the language indicated by the language parameter.

Language specific requirements will be applied. For example, if a room description in English consists of only numbers and symbols, or is shorter than 4 characters, it may be blocked. See supported HTML tags.
photos Photo array

Provide when all flags below are true:

  • rate_plan_details
  • photos

List of photos representing the rate plan.

Image file type should be able to render on modern web browsers (JPG, PNG, GIF) (TIFF is not supported). Photos should support https.
 rate_amenities  object Provide when all flags below are true:
  • rate_plan_details

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

cancellation_policy  object

Provide when all flags below are true:

  • rate_plan_details

The cancellation policy:

  • Free cancellation until 2017-06-15 00:00:00Z.
  • From 2017-06-15 00:00:00 GMT to 2017-06-20 00:00:00 GMT, there is a cancellation fee of 50.00 USD.
  • After 2017-06-20 00:00:00 GMT, there is a fee of 25.00% of stay and a fee of one night's stay.

is represented in the API as:

"cancellation_policy": {
  "cancellation_summary": {
    "refundable": "full",
    "cancellation_deadline": "2017-06-15T00:00:00Z",
  },
  "cancellation_rules": [
    {
      "start_datetime": "2017-06-15T00:00:00Z",
      "end_datetime": "2017-06-20T00:00:00Z",
      "fixed_fee": {
        "fee": {
          "amount": 50.00,
          "currency": "USD"
        },
        "taxes_included": true
      }
    },
    {
      "start_datetime": "2017-06-20T00:00:00Z",
      "percent_fee": {
        "amount": 0.25
      },
      "night_fee": {
        "num_nights": 1.0
      }
    }
  ]
}
Name Type Description
cancellation_summary array of objects

A summary of the fee schedule associated with cancellation.

refundable string

This field is mandatory. Must be treated as dynamic and change over time according to the cancellation policy and deadline. In addition to this refundable information, cancellation_rules will enable TripAdvisor to display useful information to your customers, including "policy_info" text that is currently displayed to travelers. 

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"

Note: These fields are case sensitive and should be set as displayed above, they should not be for example 'Full' or 'None'.

Use cases can be found here: http://developer-tripadvisor.com/connectivity-solutions/instant-booking-api/support/

 cancellation_deadline  string Required if refundable is set to full. The date and time after which it is not free to cancel a reservation. Must be in ISO8601 date-time format, which includes time zone, e.g. YYYY-MM-DDT00:00:00+00:00.
unstructured_cancellation_text string

Provide when all flags below are true:

  • rate_plan_details (Same as parent)
  • text

Text describing the cancellation policy for the room. Should be in the language indicated by the language parameter.

cancellation_rules array of objects

A detailed fee schedule associated with cancellation represented as rules. For each rule, At least one of 'fixed_fee', 'percent_fee', or 'night_fee' must be non-null. If more than one is non-null, it will be interpreted as multiple fees with different types taking effect at the same time.

An empty cancellation rule array will be interpreted as no information provided.

Name Type Description
start_datetime string The time which the cancellation rule takes effect. If null, no start time will be used. Must be in ISO8601 date-time format, which includes time zone, e.g. YYYY-MM-DDT00:00:00+00:00.
end_datetime string

The time which the cancellation rule is no longer in effect. If null, no end time will be used. Must be in ISO8601 date-time format, which includes time zone, e.g. YYYY-MM-DDT00:00:00+00:00.

fixed_fee number

Fixed fee charged in the given currency

Name Type Description
fee number Value in a given currency.
amount number The numeric value.
currency string ISO 4217 currency code.
taxes_included boolean If true, taxes are included in given amount. (Note, if there are no taxes charged, this should also be set to true)
percent_fee number

Percent of booking that will be charged as a fee.

Name Type Description
amount number Percent value.
night_fee boolean

Number of nights of booking that will be charged as a fee using the average nightly rate.

Name Type Description
num_nights number Number of nights

 

 

 

meal_plan object

Provide when all flags below are true:

  • rate_plan_details

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": [ ]}

 

 

RoomRates

Used in: availability

Field Type Description
persistent_room_rate_code string
This is optional.
This code identifies unique room rates. We expect that this code persists across future availability calls. The combination of persistent_room_rate_code and partner_hotel_code must be unique.
room_type_key string
Key referencing the applicable RoomType. This key must exist in the response's room_types map in order for this to be considered a valid response.
rate_plan_key Price object
Key referencing the applicable RatePlan. This key must exist in the response's rate_plan map in order for this to be considered a valid response.
line_items LineItem array

Affected when all flags below are true:

  • real_time_pricing
An object containing the detailed breakdown of charges. See below.
payment_policy string

Provide when all flags below are true:

  • room_rate_details
  • text
How will the partner use the credit or debit card information, e.g. charged immediately or hold. Large text field.
rooms_remaining integer

Provide when all flags below are true:

  • room_rate_details

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

Provide when all flags below are true:

  • room_rate_details
  • text
Miscellaneous policies.
url string
The URL of the hotel on the partner site. This URL should go to a page that will show the price quoted and allow a user to book the room. Make this URL as specific as possible. This URL must be accessible with a GET request. If possible, the URL should go to a webpage in the language specified by the language parameter in the availability request.
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.

 

LineItems

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

Field Type Description
price Price object

When partner_booking_data is set to false (hotel or expanded availability), at least one of requested_currency_price or currency_of_charge_price should be populated. When partner_booking_data is set to true (booking availability) and in /booking_submit, currency_of_charge_price should also be populated. requested_currency_price should also be returned if this was included in previous calls.

Field Type
Description
requested_currency_price string
Value in a given currency. requested_currency_price - Should be populated with the price in the currency sent in the request. You may also populated this field if you cannot determine that the price you have is in the currency of charge.
 
Field Description
amount The numeric value.
currency ISO 4217 currency code
currency_of_charge_price  string
Value in a given currency. currency_of_charge_price - Should be populated with the price in the currency of charge. If you cannot determine the currency of charge, do not populate this field.
 
Field Description
amount The numeric value.
currency ISO 4217 currency code
type string
Describes the charge. Must be one of these values:
 
  • rate
  • tax
  • fee
sub_type string
Describes the sub type of charge. Must be one of these values:
 
Code Value Common Examples of Line Items Which Fall Under This Type
tax_city City taxes are defined as taxes applied by a local city or municipality, collected from the traveler at the time of their stay. These taxes may be flat rate or % based.
  • City Tax

  • Tourism Tax

  • Municipality Tax

fee_resort Resort fees are mandatory additional charges (separate from the base rate) collected by the hotel at time of stay for resort-type accommodations
  • Resort Fee

  • Amenity Fee

fee_transfer Transfer fees are mandatory fees charged by the hotel for transportation from the guest's point of arrival to the hotel itself.
  • Transfer Fee

  • Transfer Charge

  • Connection Fee

tax_environmental Environmental tax (sometimes called a green tax) are taxes or fees paid at the hotel at time of stay for impact to the local environment.  
  • Environmental Tax

  • Environmental Fee

  • Green Tax

tax_vat VAT or GST tax  
  • VAT

  • GST

tax_other Other Taxes: Inclusive of any taxes or fees that do not fall into any of the above five subtypes  
fee_other Other Fees: Inclusive of any fees that do not fall into any of the above five subtypes  
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.

 

Error

If the error object is present, please include as many complete attributes in the response as available.
 
Used in: availability
 
 Field  Type  Description
error Error object
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
String describing the error. Used for debugging. Maximum length is 1000 characters.
timeout number Number of seconds we should stop sending requests for use with Error Code 4
 

HotelDetails

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

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, e.g. “24 hour airport shuttle.” Relevant amenity codes are listed in Appendix B and were derived from from the OpenTravel Hotel Amenity Code List.  

Standard amenities are an integer array. Custom amenities specified via string array

photos Photo array

URLs for photos of the hotel to be displayed during the booking process. Image file type should be able to render on modern web browsers (JPG, PNG, GIF) (TIFF is not supported). Photos should support https.

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

checkin_checkout_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 or debit card used for booking.” Should be in the language indicated by the 'lang' parameter. Max length 1000 characters. 
checkin_time string Checkin time in the local timezone of the hotel in ISO8601 full-time format. This should include the timezone offset, if possible. E.g. 18:00+2
checkout_time string  Checkout time in the local timezone of the hotel in ISO8601 full-time format. This should include the timezone offset, if possible. E.g. 12:00Z
hotel_smoking_policy object

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

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)

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] Based on OTA code table (PET), added a “900401 - Pets not allowed” to the list. 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
parking_shuttle object

[Optional] Derived from OTAs code list of HAC (hotel amenities) describing parking and/or shuttle availability options to major transportation

41 Free airport shuttle
42 Free parking
53 Indoor parking
63 Off-site parking
64 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
hotel_ extra_bed_policy string

Provide when all flags below are true:

  • hotel_details (Same as parent)
  • text Provide information on additional beds and configurations available. Omit from response if you cannot provide this information.

Provide information on additional beds and configurations available.

Example: “Rollaway bed available”, “Crib”, “Extra beds available on request”

PartnerBookingDetails

Used in: availability

partner_booking_details object 

Provide when all flags below are true:

  • partner_booking_data

Information about the process of making a booking.

Name Type Description
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 or debit 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 or debit card guarantee, it will be up to the partner to either pass or not pass the card details to the hotel. If the hotel does not support a credit or debit card at the time of booking, please return a shortened list of the standard supported types (MasterCard, Visa).
terms_and_conditions string

Provide when all flags below are true:

  • partner_booking_data (Same as parent)
  • text

General terms and conditions text.

terms_and_conditions_url string Link to the partner's terms and conditions page.
payment_policy string

Provide when all flags below are true:

  • partner_booking_data (Same as parent)
  • text
Describes how the partner will use the credit card information, e.g. charged immediately or hold.
other_policy  string  Miscellaneous policies.
customer_support CustomerSupport

Required when all flags below are true:

  • partner_booking_data (Same as parent)
A required object containing the hotel’s customer support contact information for guests.
This must be returned on both successes and failures.

 

Photo

Field Type Description
url string
URL for the photo. Image file type should be able to render on modern web browsers (JPG, PNG, GIF) (TIFF is not supported). Photos should support https.
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.

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.

RoomStay

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

Used in: Reservation

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.

PaymentMethod

Request object describing the payment method of the booking.

Used in: booking_submit

Field

Type Description
card_type string
The type of credit or debit card used. Must be one of the following:
 
  • Visa
  • MasterCard
  • AmericanExpress
  • Discover
TripAdvisor requires a credit or debit 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 or debit card guarantee, it will be up to the partner to either pass or not pass the card details to the hotel.
card_number string
The credit or debit card number.
cardholder_name string
The name on the credit or debit card.
expiration_month string
The expiration month as a two-digit string (e.g. 01, 02, .. 12)
expiration_year string
The expiration year as four digit string.
cvv string
The cvv number.
billing_address Address object
The billing address of the card.

Address

Field Type Description
address1 string
Street address
address2 string
[Optional] Additional address information
city string
Town or city
state string

State or province

State is required for all addresses from the United States (US), Australia (AU), Canada (CA), Malaysia (MY) and Philippines (PH).

For addresses from the United Kingdom (GB), New Zealand (NZ), Ireland (IE), Singapore (SG), South Africa (ZA), France (FR) and others the state is optional.

postal_code string
U.S. Address: Required
Other Address: Optional
 
Zip code or postal code
country string
ISO 3166 country code

Reservation

Used in: booking_submit, booking_verify

Field Type Description
reservation_id string
Unique partner identifier for the reservation.
status string
The status of the reservation, must be one of:
 
  • Booked
  • Cancelled
  • CheckedIn
  • CheckedOut
confirmation_url string
Deep link to the reservation confirmation page.

 

The confirmation URL is displayed to the traveler after a booking has been confirmed. In addition, it is also displayed in the "My Bookings" page of the TripAdvisor account for the traveler.

 

Because this URL is displayed to the traveler, it therefore must be a link to a page owned by the booked property which:
1. displays any relevant confirmation codes, and,
2. confirms the dates, rooms and final price for the booking.
 

 

Example:
"confirmation_url": "http://bookings.bookingengine.com/Channels/BestHotel/confirm.jsp?mode=show&bid=8507809&bCode=9914&lang=en&currency=USD"

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.
partner_hotel_code string
The partner specific code for this hotel. In a /booking_submit request this should be the same as in the request.
hotel HotelDetails object
An object containing information about the hotel booked.
customer Customer object
An object containing the customer booking the reservation.
rooms RoomStay array
An array of RoomStay objects.
legal_text string
Optional. Text describing any legal requirements for the hotel. If a partner has a single policy across all bookings, return the partner's legal text here. For example: Terms of Service and Privacy Policy.
comments string
Optional. Generic reservation comments field.
line_items LineItem object
An array of LineItem objects will contain a separate LineItem for rate, tax, and fee types with each corresponding sub_type.

Problem

Response object that is optional for a successful booking but required when there is an issue with the booking.

Used in: booking_submit, booking_verify

Field Required Type Description Example
problem
Required
string One of the supported problem types.
"problem" : "MissingEmail"
explanation Required string Partner-specific message to be displayed to the user providing details of the problem, and should be in the language of the 'lang' parameter of the request.
"explanation" : "The e-mail
address is missing"
detail Optional string Partner-specific message providing details of the problem that will not be displayed to the user. Intended for logging purposes.
"detail" : "E-mail address
missing"

Problem Types

Used in: Problem

Here is the list of problem types that TripAdvisor supports:

  • CreditCardDeclined
  • CreditCardTypeNotSupported
  • MissingTravelerFirstName
  • MissingTravelerLastName
  • MissingEmail
  • MissingReservationFirstName
  • MissingReservationLastName
  • MissingWorkPhone
  • MissingHomePhone
  • MissingAddress
  • MissingCity
  • MissingStateProvince
  • MissingCountry
  • MissingPostalCode
  • MissingCardholderName
  • InvalidTravelerFirstName
  • InvalidTravelerLastName
  • InvalidEmail
  • InvalidReservationFirstName
  • InvalidReservationLastName
  • InvalidWorkPhone
  • InvalidHomePhone
  • InvalidAddress
  • InvalidCity
  • InvalidStateProvince
  • InvalidCountry
  • InvalidPostalCode
  • InvalidCardholderName
  • UnknownUserProblem
  • RoomNotAvailable
  • PartnerDown
  • PartnerTimeout
  • AgentAttention
  • PropertyNotSupported
  • PriceMismatch
  • UnknownReference
  • UnknownPartnerProblem

Example

This table illustrates different problem situations and how they map to the listed Problem Types.

Example Problem Type Note
Missing required values:
first_name MissingTravelerFirstName  
last_name MissingTravelerLastName  
card_type CreditCardDeclined The explanation field must note this value is missing.
card_number CreditCardDeclined The explanation field must note this value is missing.
expiration_month CreditCardDeclined The explanation field must note this value is missing.
expiration_year CreditCardDeclined The explanation field must note this value is missing.
cvv CreditCardDeclined The explanation field must note this value is missing.
country MissingCountry  
partner_data UnknownReference The explanation field must note this value is missing.
Invalid values:
email InvalidEmail  
country InvalidCountry This applies if the country code is incorrect.
expiration_month CreditCardDeclined

The explanation field must note this value is invalid.

Note that the required format is 'MM', where the allowed range of values is for 'MM' is 01-12.

expiration_year CreditCardDeclined

The explanation field must note this value is invalid.

Note that the required format is '20YY', where the allowed range of values is from the current year to 2099.

(expiration_month && 

expiration_year) < Today

CreditCardDeclined

The explanation field must note this value is invalid.

The date represented by the combination of Expiry Month and Expiry Year must not be in the past.

card_number CreditCardDeclined

The explanation field must note this value is invalid.

The credit or debit card number must pass the Luhn algorithm.

cvv CreditCardDeclined

The explanation field must note this value is invalid.

For AmEx the CVV is a four digit number. For Visa, MasterCard, and Discovery the CVV is a three digit number. No alphabetic characters or other symbols allowed.

partner_hotel_code UnknownReference

The explanation field must note this value is invalid.

reservation_id UnknownReference The explanation field must note this value is invalid.
Incorrect Data Types:
phone_number InvalidHomePhone The phone number must be sent as a string containing the allowed characters for phone numbers.
card_number CreditCardDeclined This value must be a string containing digits only.
expiration_month CreditCardDeclined This value must be a string containing two digits.
expiration_year CreditCardDeclined This value must be a string containing four digits.
cvv CreditCardDeclined This value must be a string containing four digits if the value of "card_type" is "AmericanExpress". It must be three digits if the value of "card_type" is "Visa","MasterCard", or "Discover".

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.

Used in: availability, booking_submit, booking_verify, booking_cancel

Field Type Description
phone_numbers Contact array
Phone numbers for customer support. At least one element must exist in either the standard array or custom array.
Field Type Description
standard array

An array of standard-format customer support phone numbers.

description Short description of the phone number
country_code Country calling code
number The phone number
custom array

An array of custom-format customer support phone numbers

description Short description of the phone number, e.g. customer support line
number The phone number
 
emails Contact array
An array of customer support emails.
description Short description of the email address
email Customer support email address
 
urls Contact array
An array of customer support urls.
description Short description of the url
url Customer support url
 

Contact

Field Type Description
contact string
The contact detail, e.g. phone number or email address.
description string
A description for this contact.
 

Price

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