Support

FAQ

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 connect@tripadvisor.com 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 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.

 
What is the process to migrate to the latest API version?
  1. 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. 
    • Important: For support please contact connect@tripadvisor.com. If your endpoint url has changed it will need to be re-whitelisted which is dependent on a weekly release cycle.
  1. 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.
  2. 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.
  3. 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. 

 

How does booking_sync work?

Booking "sync" requests are sent by adding /booking_sync to your endpoint and sending the params explained below in a POST request.

The purpose of the "booking_sync" API call is to update TripAdvisor with the full set of changes to bookings that have occurred on the hotel/property system.

The "booking_sync" API call is made daily to verify which bookings actually took place as expected, or conversely were cancelled or modified.

For example: If a cancellation is made over the phone to the hotel, TripAdvisor would find out via the booking_sync mechanism that the reservation was cancelled.

If "booking_cancel" or "booking_sync" API calls were not implemented, it would be up to the hotel/property to inform TripAdvisor that a cancellation was made — which they would need to do through the Instant Booking dashboard in their TripAdvisor Management Center.

If a booking has been cancelled, the original rate must be returned in the response. This also covers the case where there has been a cancellation fee charged.

In the case were a booking has been modified, the new rate must be returned in the response. (This rate must not include any charges applied to have the booking modified.)

Example:
  1. Booking in December for stay dates March 24th - March 28th, $400 base rate.
  2. Modification made on March 23rd to change stay March 24th - March 27th, which results in a $300 base rate.
  3. The response to the "booking_sync" call must contain the data  March 24th - March 27th, with a $300 base rate.
  4. If there was a $20 modification fee applied it should be included in the "fees" part of the "booking_sync" repsonse, but the $300 must remain as the base rate.

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:

  • 192.170.136.0 to 192.170.143.255

  • 199.102.232.0 to 199.102.235.255 

  • 78.152.60.0 to 78.152.60.7

  • 185.61.96.0 to 185.61.99.255

  • 62.189.165.18

  • 66.46.169.186

 

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.

 

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

 

Do the request parameters always follow the same order?
No. The order can vary and there’s no need to apply validations for it.

 

Do I need to return any credit or debit cards if my hotel does not accept credit or debit cards?

Yes. 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 cases 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).

 

Can any currency be provided for prices, taxes, fees, and discounts in the response?

No. The currency returned in all responses should respect the following criteria:

  • - If the currency parameter is present in the request, all values returned in the responses should be in that currency.
  • - If the above is not possible, and the user_country is present in the request, then the returned currency must match the one seen by a user from this country visiting your website.
  • - If the above is not possible, then the currency should be the local currency of the hotel.

 

Can the currency for local taxes and/or fees be different than that of the room prices?

No. It is imperative that all values for prices, taxes, fees, and discounts be provided in the same currency.

 

How should the refundable value and cancellation rules in /booking_availability RatePlan object be determined?

As of API version 8 we encourage the use of cancellation_policy.cancellation_rules in addition to the mandatory cancellation_policy.cancellation_summary as this will enable TripAdvisor to display useful information to your customers using semantic data. We still require you to provide "refundable" field in your response and the "cancellation_summary.unstructured_cancellation_text". Use the following to determine value of "refundable".
 
  • full: At time of booking the reservation may be cancelled without any charge to the user. Reservations with free cancellation expiring 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.

  • partial:  At time of booking, the reservation may be cancelled but will incur a charge less than the total reservation amount.

  • none: At time of booking, the reservation may be cancelled but no refund will be provided.  If the customer has not yet been charged, the full amount will be deducted.

Sample Use Cases to determine Refundable field:

  1. Standard rate
    • Deposit: None
    • Cancellation Text: 1 night stay if cancelled within 48 hours before arrival.
    • Examples:
      • Customer books reservation on March 1 for arrival April 1.
        • Refundable = full
        • Time of booking (March 1) is more than 48 hours before arrival (April 1)
      • Customer books reservation on March 31 for arrival April 1 and departure on April 2
        • Refundable = none
          • Time of booking (March 31) is less than 48 hours before arrival (April 1)
          • 1 night penalty is incurred which is the same as length of stay (1) - 100% penalty
      • Customer books reservation on March 31 for arrival April 1 and departure on April 3
        • Refundable = partial
          • Time of booking (March 31) is less than 48 hours before time of arrival (April 1)
          • 1 night penalty is incurred which is less than the length of stay (2) - 50% penalty

  2. Advanced Purchase rate:
    • Deposit: 100% deposit,
    • Cancellation Text: 100% penalty at time of booking
    • Examples:
      • Customer books reservation on March 1 for April 1
        • Refundable = none
          • 100% cancellation penalty at time of booking (March 1)
  3. Deposit rate:
    • Deposit: 1 night deposit
    • Cancellation Text: 1 night stay if cancelled within 48 hours of arrival
    • Examples:
      • Customer books reservation on March 1 for arrival April 1.
        • Refundable = full
          • Time of booking (March 1) is more than 48 hours before arrival (April 1)
      • Customer books reservation on March 29 for arrival April 1
        • Refundable = full
          • Time of booking March 29 is greater than 48 hours before arrival (April 1)
      • Customer books reservation on March 31 for arrival April 1 and departure on April 2
        • Refundable = none
          • Time of booking (March 31) is less than 48 hours before arrival (April 1)
          • 1 night penalty is incurred which is equal to the length of stay (1) - 100% penalty
      • Customer books reservation on March 31 for arrival April 1 and departure on April 3
        • Refundable = partial
          • Time of booking (March 31) is less than 48 hours before arrival (April 1)
          • 1 night penalty is incurred which is less than the length of stay (2) - 50% penalty

Working with Cancellation_Rules:

This object provides a breakdown of the cancellation policy into semantic fields. Note that the "Refundable" field and cancellation_rules.policy_info are still mandatory. Prototypes of how TripAdvisor may use this data to templatize content:

  1. Refundable logic and prototypes
    • Fully refundable:
      • Fields used: [refundable = full].
      • Other fields that could be used by TripAdvisor to construct a similar response: [deadline exists and deadline > booking date] or [booking date < relative deadline (dates booked - arrival dependency)]
      • Example: "Free cancellation until 2016-05-25, 16:00 local time"
    • Partially refundable:
      • Fields used: [refundable = partial]
      • Other fields that could be used by TripAdvisor to construct a similar response: [deadline exists and deadline <= booking date, fees] or [booking date >= relative deadline (dates booked - arrival dependency)]
      • Example: "If canceled or modified up to 7 days before arrival, a fixed amount of 100 USD (tax inclusive) will be charged."
  2. Amount type variations
    • Fixed
      • Fields used: [amount = 117.52], [currency = CAD]
      • Example: “Late cancel or no show will be charged 117.52 CAD.”
      • Potential logic:
        • If fixed_fee.fee.amount = 0, then Refundable = full
        • If 0 < fixed_fee.fee.amount < total_booking_value then Refundable = partial
        • If fixed_fee.fee.amount = total_booking_value then Refundable = none
    • Percent
      • Fields used: [amount = 10], [days before arrival = 7], 
      • Example: "If canceled up to 7 days before date of arrival, 10 percent of the total price of the reservation will be charged."
      • Potential logic:
        • If percent.amount = 100 then Refundable=none
        • If 0 < percent.amount < 100 then Refundable=partial
        • If percent.amount = 0 then Refundable=full
    • Nightly fee
      • Fields used: [num_nights = 1]
      • Example: "In case of no-show without advanced notice of cancellation, the price for the first night will be charged on the credit card provided."
      • Potential logic:
        • If num_nights=total nights (or > total nights) then Refundable = none
        • If 0 < num_nights < total then Refundable = partial
        • If num_nights = 0 then Refundable = full

For invoicing, do we invoice the hotels for the bookings that checked in the month before or checked out the month before?
We invoice by check out date.

 

For invoicing, do we charge VAT on the commissions?
If applicable, yes.

 

For invoicing, is the commission on the base rate?
Yes.

 

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.

Contact Us

For assistance with developing your Instant Booking API implementation send your question to connect@tripadvisor.com