API v8 FAQ
Why has TripAdvisor merged /hotel_availability and /booking_availability?
Why - Allows greater flexibility for Partners to adapt to new revisions of the API. If TripAdvisor adds new items to it’s requests in the future, using a single API allows for such changes to be non-breaking in nature (Partner can choose to adopt changes when ready) therefore requiring minimal to no effort on the part of Partners. Additionally, the single API allows for consistency of data across different requests and lets us optimize the load on Partner servers.
How - The single endpoint leverages flags named “categories” and “category_modifiers” to request and receive different types of data from Partners. Each of these flags corresponds to particular sets of information in the response. The category_modifiers are particular types of data that can be applied to each of the categories in a specific request/response. We don’t have an exhaustive list of combinations, but expect that when we ask for a certain combination we receive those data pieces in the response. Both ‘categories’ and ‘category_modifiers’ are required.
How to differentiate a CPC call from an Instant Booking one?
With respect to CPC vs IB there’s no change from v7 to v8, and partners should work exactly the same way as they do for V7. In the event this doesn’t work, partners should contact their Account Manager explaining how V8 behavior differs from V7 so that we can look at their specific case.
Submitting different endpoints for CPC and IB both supporting V8 could be an option however - meaning that partner needs both endpoints to go through the certification process and both be maintained.
What is an example of response flags when a partner can responds TRUE when asked for FALSE?
In a single hotel availability request when TA is only requesting for the cheapest room rate available, we expect all category / flags requested to be set to FALSE (i.e. TA is not requesting for any additional room/rate/hotel details). There are two acceptable responses:
At minimum we expect to receive a single room-rate with the response flags set to all be false.
However, for the same request, a Partner is permitted to send TA more information. For example, Partner can potentially send all room-rates (instead of just one) for that hotel. Here a Partner is expected to set the "multiple_room_rates_included" to “true”
What are the request parameters and content data that TripAdvisor will be asking for?
In the UI, we will likely use room names, bed configuration, breakfast, free cancellation, pay at stay, rooms remaining, etc in Expanded Availability. We would like partners to send us exactly what we are asking for. However, partner is allowed to pass TripAdvisor other info fields (e.g. “hotel_details”), and TripAdvisor will drop the items we don’t need from the response.
With the merging of Hotel Availability and booking availability call will partners have to submit new endpoints?
Partners do not have to submit new endpoints. We can use existing endpoint and test in partner’s test environment first before we move to production to validate responses.
- If a partner submits new endpoints, we would need to whitelist it before starting any testing. (Whitelisting is a weekly process)
Will combining the calls increase the traffic volume to our system significantly?
We expect the traffic to be similar to what it is now. But partners can optimize the call and decrease traffic volume by only returning certain flags rather than returning all of the 9 different flags we are requesting.
Persistent Codes: These are unique codes that are meant to remain the same across multiple requests/responses. This will allow us to distinctly identify rooms/ rates and cache information in order to reduce load on Partner servers. For example, we expect the physical room type to remain fairly static.
What is the meaning of "Persistent Room Type Code / Rate Plan Code / Room Rate Code"?
Persistent codes, i.e. Unique codes that persist between multiple requests that TripAdvsior will make, help us identify a roomtype / rate easily and accumulate this data. Given that the physical room does not change, we are asking this room to be identified with a persistent code.
Taxes and Fees breakdown: This functionality will allow Partners to be able to display taxes, fees and base rates in ways that are more relevant to each market on TripAdvisor’s platform. The new API will help Partners and Hotels stay competitive and attract bookings from travelers looking for the lowest price.
What happens if a property is unable or does not provide all the taxes / fees?
Not every destination or hotels will charge every tax and fee we list in the documentation. For example in NYC hotels will have a city tax, a hotel tax, and an occupancy fee but they may not have a resort fee or any of the other taxes we list in the documentation. If a hotel does not provide a breakdown of their taxes then their displayed prices will appear less competitive in certain points of sale as we are unable to display the price minus certain taxes to show the customer the lowest price in the price finder
Not all of our properties have both taxes and fees broken down into the exact categories that TripAdvisor has listed. What shall we do in this case? Pass the 2 taxes separately or send a calculated sum number to TripAdvisor?
In general, if a property cannot break up the taxes and fees into the categories we provided (as in they have a tax/fee that does not match any of the ones we have), they can use the “other_tax/ fee” field. If they have a VAT and GST as separate items, it is okay to combine the two.
Other frequently asked questions:
Besides merging Hotel Availability and booking availability calls, and returning taxes and fees at a more granular level, are there any other major changes to the API?
- Yes, we are asking partners to return and use common objects across all API calls. Partners can maintain a single set of objects across TripAdvisor API functions (e.g. line_items and customer_support are objects that have been updated in /availability). We want Partners to use the same object across the entire API. This provides a consistent experience to Partners and lowers maintenance of multiple API versions. We are requesting partners to modify their current calls for Booking Submit, Booking Verify, Booking Cancel. To reiterate this is not a large change and in fact will streamline your code that uses common objects across API calls.
We are currently on older versions of the API for CPC. Will this have to be upgraded to V8 as well?
Yes, all CPC and IB endpoints will have to be upgraded to V8 since the changes to the hotel availability call are significant.
How should we return a "no availability" response?
In response_type there can be three values; if the hotel has availability ("available"), if the hotel has no availability ("unavailable") and if the hotel has an error ("error").
So for no availability, TripAdvisor would expect to see:
... "response_type": "unavailable" ...
Can we have 2 endpoints?
Yes, but if you decide to use 2 endpoints, then the Hotel Availability and Booking Availability calls should be on 1 endpoint while the Booking Submit, Booking Verify and Booking Cancel calls should be on the other endpoint.
Why do I keep getting the error 'JSON Does Not Match API'?
Did you include an optional field with an empty string in your responses? Fields that are marked as 'Optional' do not need to be included in your responses. When you do not have a value for an optional field, it should be omitted entirely. Do not include the field with an empty string.
How do we determine which RoomTypeObject is being booked in the booking_submit function?
Only one room type will be booked for the entire stay.
Will TripAdvisor handle processing credit card payments or will they be transmitted to our system for the hotel to handle the payment?
Payment should be handled by either the Partner or the hotel. TripAdvisor will pass the credit card details in the PaymentMethodObject.
Should we provide different rates as different room types?
If you prefer to create different rates as different room types you can do that. Alternatively, rate type details can be transmitted in the RoomTypeObject/“partner_data” field. Each RoomTypeObject has a partner_data field which can be any data you wish to include. We will then return this field to you in the booking_submit call so that the proper room/rate (product) can be booked.
I don’t see room codes or room codes in the API calls. How do I know which room/rate should be booked?
Each RoomTypeObject has a partner_data field which can be any data you wish to include. We will then return this field to you in the booking_submit call so that the proper room/rate (product) can be booked.
Can 'problem' be a custom code or can only defined 'Problem Types' can be used?
The problem field needs to be one of our allowed types, but you can fill in the explanation with something more specific that we can log.
What is the purpose of 'reference_id' in the /booking_submit and /booking_verify calls?
The purpose of this field is to assist in the case of a timeout when attempting a booking. By sending this id in booking_verify, we can determine the status of the booking and whether the reservation booked. Please note, the reference_id is only guaranteed to be unique during the booking session. This should not be considered to be the TripAdvisor 'confirmation number.'
When a booking is completed, where will the customer get a confirmation e-mail from? Will TripAdvisor send a confirmation e-mail or will the Partner be responsible for sending a confirmation e-mail or both of them will?
When a booking is completed, the customer should get a confirmation e-mail from the hotel/partner. TripAdvisor will also send out a confirmation email separately but after the hotel’s one in order for the customer to be very clear that they booked with the hotel and that the hotel is fulfilling the reservation and is responsible for any customer service question that may arise.
When booking_cancel is called, should the booking be cancelled even if there is a cancellation fee to be charged upon cancellation?
This is up to the hotel to determine and for you to provide to us. We provide details on the booking (including cancellation policy and details on potential refunds in the case of cancellation), but it might be good practice to have the hotel contact the traveler directly to ensure that he/she understands that there will be a cancellation charge.
Can I whitelist your IP address for security reasons?
We prefer that you do not use a whitelist of IPs. If you must whitelist, whitelist this entire list of IPs:
220.127.116.11 to 18.104.22.168
22.214.171.124 to 126.96.36.199
188.8.131.52 to 184.108.40.206
220.127.116.11 to 18.104.22.168
Is multi-room shopping and booking supported?
Yes, multi-rooms shopping and booking are supported; however, the rooms that are shopped/booked must be of the same room type.
Does TripAdvisor have its own unique IATA number that can be tied to bookings?
Yes, please use the IATA number 22502174.
What should I use if there is a field that I need that is not in the API?
Use the partner_data field. 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 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.
Do I need to return any credit cards if my hotel does not accept credit cards?
Yes. 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 list of the standard supported types (MasterCard, Visa, AmericanExpress, Discover).
How can we use a username and password for our API?
If the partner would like to verify that TripAdvisor is the requestor, Tripadvisor can optionally send a username and password to the partner using HTTP basic access authentication. This option should be used in conjunction with HTTP over SSL (HTTPS) to ensure that the username and password cannot be stolen. Using HTTPS requires a certificate from an audited certificate authority.