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.

• 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 Configuration, Hotel Inventory, Hotel Availability and Booking Availability calls should be on 1 endpoint while the Booking Submit, Booking Sync, Booking Verify and Booking Cancel calls should be on the other endpoint.

• Testing: Once you have finished building the latest API version, visit the API Submission site to complete the testing process. Please note: It is recommended that you provide test hotel IDs in the "List of hotel test Ids” field so the booking_submit calls are made against these properties during this process as the tool books live reservations. 
  If you fail any of the tests, you will need to fix the issues before you can proceed to the next test. 
• Quality Assurance: Once you have completed the above steps, we will conduct further testing before your migration to the latest API version can be approved.

• Production testing: We will make a test booking for a property already live on instant booking through your connectivity. Please indicate a suitable property with free cancellable rooms. During production testing, we will temporarily pause your instant booking traffic. We anticipate this taking no more than 48 hours.
• Confirmation: After successful testing, we will send you a confirmation and instant booking traffic to your endpoint will be re-enabled.

How do we determine which RoomType is being booked in the booking_submit function?

Only one room type will be booked for the entire stay.

Will TripAdvisor handle processing credit or debit card payments, or will they be transmitted to our system for the hotel to handle the payment?

Payment should be handled by either the Connectivity Partner or the hotel. TripAdvisor will pass the credit or debit card details in the PaymentMethodObject.

Should we provide different rates as different room types?

Each rate should be specified within the RatePlan object: Do not use the RoomType object to specify rateplans. In addition, you may enter relevant rate or room details in the RoomRate/“partner_data” field. 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' 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 that 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, how will the customer get a confirmation e-mail? Will TripAdvisor send a confirmation e-mail or will the Connectivity Partner be responsible for sending a confirmation e-mail (or both)?

When a booking is completed, the customer should get a confirmation e-mail from the hotel/Connectivity Partner. TripAdvisor will also send out a confirmation email separately, but after the hotel’s email — which helps to reinforce the idea that the customer booked with the hotel, that the hotel is fulfilling the reservation, and that the hotel 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 (the Connectivity Partner) to provide to us. We provide details on the booking (including cancellation policy and details on potential refunds in the case of cancellation), but having the hotel contact the traveler directly to ensure that he/she understands that there will be a cancellation charge is the best practice.