Viator API certification: back-end checks

Please download the form below and fill in your answers

Send this document back to us at affiliateapi@tripadvisor.com

We will verify your integration and ensure everything is in working order

We will reach out directly to you via email with additional questions or to let you know you’ve completed the back-end checks.

Only after back-end checks are completed, can you start the front-end certification – please check the options for the front-end certification in our certification documentation.

In order to keep your local databases up-to-date without placing an excessive burden on our servers, we recommend the following fixed cadences at which you should poll the content-ingestion endpoints:

To ensure your systems reflect any removals of or changes to existing destinations, locations or booking questions, we recommend retrieving full updates from these endpoints as follows:

When ingesting product content, in the event that you encounter an unknown reference – i.e., a new location reference, booking question, tag or destination id – or, if you need to perform a currency conversion for which the last exchange rate you retrieved has expired, we recommend you call the relevant endpoint to resolve the new reference immediately or just after completing the product content update.

1. The /products/modified-since endpoint must be used to ingest product content and to keep it up to date. Other product content endpoints (/products/bulk, /products/{product-code}) should not be used for this purpose unless you are ingesting products that haven’t been ingested before (for example, due to additional filtering rules on your end).
2. The product content updates must be pulled with the /products/modified-since endpoint at least hourly. The recommendation is to refresh it as frequently as possible, for example every 15-30 minutes, to avoid stale data.
3. To keep content up to date you must use delta updates and not re-ingest full content when an update is not required.
4. If you are ingesting and storing our content in your local database, please ensure that tags, reviews, destinations, locations, photos and booking questions are cached and refreshed periodically based on the recommended frequency of updates.

1. The /availability/schedules/modified-since endpoint must be used to ingest availability and pricing schedules and to keep this information up to date. Other availability endpoints (/availability/schedules/bulk, /availability/schedules/{product-code}) must not be used for this purpose unless you are ingesting products that haven’t been ingested before (for example, due to additional filtering rules on your end).
2. Availability and pricing schedules must be refreshed with the /availability/schedules/modified-since endpoint at least hourly. The recommendation is to refresh it as frequently as possible, for example every 15-30 minutes, to avoid stale data.
3. Please do not attempt to ingest the full catalog of availability schedules with each ingestion run. Ingest the full catalog once, and then only perform delta updates.
4. Do not use the availability real-time request with the /availability/check endpoint for ingestion purposes.
5. If you are converting prices from our supplier currency into your desired currency using the /exchange-rates endpoint, you must ingest exchange rates and refresh them based on the expiry timestamp from the response to this endpoint.

1. When using the search endpoint(s), it is necessary to paginate through the results in accordance with the limitations imposed by the API documentation (50 results per page maximum).
2. Search endpoints (/products/search, /search/freetext) must not be used for ingestion.
3. The number of calls to the /products/search endpoint should be controlled to avoid exceeding the rate limit. If you make a large number of concurrent requests you may be rate limited as described here and in case it happens, you can retry your request after the suggested time.

1. You must check real-time availability and pricing with the /availability/check endpoint, even if you have already ingested availability schedules.
2. You must verify the real-time availability of a bookable item*/passenger mix/travel date combination before submitting a booking request for that same bookable item*/passenger mix/travel date combination.
   *bookable item is what a customer actually purchases (i.e. the product or the product option or the start time – whichever is the lowest level on the product)
3. Real-time availability may not be requested unless the user has selected a travel date and passenger mix (age bands).
4. The request to /availability/check endpoint must be made with the currency in which you wish to be invoiced by Viator. This way you will be able to verify the final rate in that specific currency and avoid possible pricing discrepancies that could occur due to exchange rate fluctuations. This is especially important if you decided not to use the /exchange-rates endpoint.
5. In case the /availability/check endpoint returns a different price than previously displayed to the customer based on /schedules, the new price from the availability/check endpoint must be applied in order to proceed with the booking.

Full + booking access affiliate API partners are required to implement the /bookings/cart/hold endpoint in order to avoid last-minute availability and pricing changes that might occur during the booking process and in order to make a booking with the /bookings/cart/book endpoint. Partners who use this solution are not allowed to access the /bookings/hold or /bookings/book endpoint.

Using the /bookings/hold or the /bookings/cart/hold endpoint is not mandatory in case of merchant API partners but it is highly recommended to implement the booking hold with either of these endpoints to ensure that the booking will be confirmed at the expected price.

When the /bookings/cart/hold endpoint is used to make a hold, the /bookings/cart/book endpoint must be used to book (not the /bookings/book endpoint).
When the /bookings/hold endpoint is used to make a hold, the /bookings/book endpoint must be used to book (not the /bookings/cart/book endpoint).

1. A booking hold must only be placed when there is strong intention from your customer to purchase (when the customer is moving to the checkout page or when the card payment details are requested).
2. A booking hold must never be used to check a product’s availability, i.e. you should not call it immediately prior to making the booking to check the availability or price – for this purpose you would need to use the /availability/check endpoint. Booking hold is used to place a pricing and availability (when possible) hold for a short period of time needed to complete the booking (for example when a customer is providing all information required to book at checkout).
3. It is important to verify the timestamps returned for the availability hold and for the pricing hold to know how long each hold is valid for. If necessary (when the hold expires but the booking hasn’t been confirmed yet), another hold can be done (it will generate a new bookingRef that should be included in the booking request).
4. A new hold can only be placed in case the previous hold expires.
5. If you use the API payments solution:
   • PARTNER_FORM must be selected as the value for paymentDataSubmissionMode in the /bookings/cart/hold request.
   • The paymentDataSubmissionUrl from the /bookings/cart/hold response must be used to create a payment token with the /v1/checkoutsessions/{sessionToken}/paymentaccounts endpoint instead of constructing the URL manually
   • See our step-by-step guide for the API payments solution here.
6. If you use the Viator iframe solution:
   • hostingUrl must match the URL of the page hosting the iframe.
   • VIATOR_FORM must be selected as the value for paymentDataSubmissionMode as well as the hostingUrl must be provided in the /bookings/cart/hold request (URL of the page where the payment form is hosted, it should include the protocol, domain and any non-standard port, excluding the trailing ‘/’).
   • The paymentSessionToken from the /bookings/cart/hold response must be used to initialize the iframe.
   • See our step-by-step guide for the iframe solution here.
7. The correct currency code must be included in the hold request:
   • Full + booking access affiliate API partners can select one of the following currencies: USD, EUR, GBP, AUD, CAD, CHF, DKK, FJD, HKD, JPY, NOK, NZD, SEK, SGD, THB, ZAR, INR, BRL, TWD, MXN, CLP, IDR, ILS, KRW, PHP, PLN, TRY.
     • • 5 currencies are supported for merchant API partners: AUD, CAD, EUR, GBP, USD
8. The status of the hold must be correctly verified:
   • If you use the /bookings/hold endpoint you should check if the hold is provided for availability and for pricing separately (based on the timestamps) and in case the first hold expires before the booking request is sent place a new hold or verify the price and availability again with the /availability/check endpoint to avoid pricing discrepancies in bookings
   • If you use the /bookings/cart/hold endpoint, you must verify the booking status from the response prior to proceeding with the payment. When the status is REJECTED the customer must be advised that the product is not available to book (based on the rejectionReasonCode returned in the response).

1. Booking references (bookingRef and partnerBookingRef) and, when applicable (when using the /bookings/cart/hold endpoint ), cart references (cartRef and partnerCartRef) from the hold must be used when submitting the booking request and all booking details from hold request must match the details from the booking request.
2. If you use the API payments solution:
   • Use paymentDataSubmissionUrl from the /bookings/cart/hold to submit payment details with /paymentaccounts endpoint instead of constructing the URL manually.
   • x-trip-clientid header must be populated with the partner PID and a partner-generated request identifier must be included in the x-trip-requestid header
   • When creating the payment token with the /paymentaccounts endpoint it is mandatory to provide full credit card details (number, cvv, expMonth, expYear, name) including address (country + postalCode).
   • The country code (alpha-2 code for the customer country) and postal code must be accurate and for the owner of the card details.
   • The sessionAccountToken from the /paymentaccounts response must be used as the paymentToken in the /bookings/cart/book request.
   • The Javascript library must be included on your website and used to send through the device fingerprint.
   • Check that success and failure responses to /bookings/cart/book are handled appropriately and provide a suitable customer experience.
   • See our step-by-step guide for the API payments solution here.
3. If you use the Viator iframe solution:
   • You need the latest version of Edge, Firefox, Chrome or Safari, other browsers/older versions are not supported.
   • The paymentSessionToken from the /bookings/cart/hold response must be used in the initialization logic called on page load.
   • Implement the onSubmitSuccess and onSubmitError methods to deal with successful or error responses.
   • The country code (alpha-2 code for the customer country) and postal code must be accurate and for the owner of the card details.
   • The paymentToken returned in the object passed to the success callback method from the payment submitForm call must be used as the paymentToken in the /bookings/cart/book request.
   • The Javascript library must be included on your website and used to send through the device fingerprint.
   • Check that success and failure callbacks are handled appropriately and provide a suitable customer experience:
     • Success: Complete the booking
     • Failure: Provide appropriate error message to customer
   • See our step-by-step guide for the iframe solution here.
4. If you use either the API payments solution or the iframe solution you need to ensure that the fraudPreventionDetails in additionalBookingDetails will be populated appropriately*:
   • Use subChannelId if you have multiple channels (e.g. multi domains) (applicable to partners with multiple channels).
   • Use agencyId if you have for example, agencies in different geographies (applicable to agencies).
   • Use agentId if you have agents that make bookings (applicable to agencies).
   • voucherDeliveryType must be set appropriately based on how vouchers are delivered. Also it wil match one of the 3 predefined values (applicable to all partners)
   • voucherDisplayedPostPayment must be boolean and set appropriately (applicable to all partners).
   • customerMemberSince must be populated if such information is available (applicable to partners with customers that have membership/ are registered).
     *partners must implement where applicable.
5. In case a timeout has been implemented for the booking service it should not be shorter than 120 seconds (see Timeout).

1. The status field returned in the response to the booking service must be always verified prior to confirming the booking to the end customer. The booking can be confirmed only when the API returns a CONFIRMED status and it must not be confirmed when the API response returns REJECTED status. In case of an error response or a timeout, the booking status must be verified with the /bookings/status endpoint.
2. If you support manual confirmation products, you must verify the status of the bookings (confirmed/rejected) by calling the /bookings/status endpoint periodically and communicate the final booking status to travelers in a timely manner. Suppliers have up to 72 hours to confirm/reject the booking request, or it will be automatically rejected 24 hours before the activity start time.
3. The status of bookings must be checked with the /bookings/status endpoint not more than once every 3 minutes, hourly checks are recommended.

Please note: merchant API partners are required to implement the cancellation API workflow in order to cancel bookings on traveler’s behalf. This flow is optional for full + booking access affiliate API partners but if implemented, the rules described below apply.

1. The /bookings/{booking-reference}/cancel-quote endpoint must be called in real-time to verify the refund amount prior to canceling the booking.
2. It is necessary to verify the refundAmount and refundPercentage fields from the /bookings/{booking-reference}/cancel-quote response in order to check the refund amount. All bookings with travel date in the future return “status”: “CANCELLABLE” however this doesn’t mean that the booking is refundable (refundable amounts can vary depending on cancellation policy of the product.).
3. One of the cancellation reasons from the /bookings/cancel-reasons endpoint must be included in the /bookings/{booking-reference}/cancel request. We recommend monthly refresh of cancellation reasons.

1. In order to automate the process for supplier cancellations it is necessary to call the /bookings/modified-since endpoint at least every 5 minutes and no more frequently than every 10 seconds. In case you are not using API services to get canceled bookings, you will need to rely on emails sent by Viator and ensure that your customer operations team is able to inform travelers about canceled bookings in a timely way (24h customer support required).
2. In order to stop email notifications for supplier cancellations, it is necessary to acknowledge that the cancellation notification from the /bookings/modified-since/acknowledge endpoint has been received by the time indicated in the bookings[].acknowledgeBy field in the /bookings/modified-since response.
3. In case you are not using API services to retrieve supplier cancellations, you will need to rely on emails sent by Viator and ensure that your customer operations team is able to inform travelers about canceled bookings in a timely way (24h customer support required).

1. When getting details of location references with /locations/bulk, please make sure to use no more than 500 location references in each request.
2. Locations should be refreshed on a monthly basis or after each product ingestion cycle if new locations are identified in the product content response.

1. In case a timeout has been implemented for API services it should not be shorter than 120 seconds. This is especially important in case of the booking endpoints.
2. When the booking endpoint returns an error or the response times out, the /bookings/status endpoint must be used to verify if the booking has been confirmed prior to communicating the booking status to the customer, or prior to re-booking.