Support

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"
...

General FAQ

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 allowlist your IP address for security reasons?

Please contact Tripadvisor for a list of IP addresses.