Technical Guide for API Partners

Welcome to the Viator Partner Program! In this guide, we’ll go through a variety of topics regarding how you can best use the Viator Partner API to display, promote and sell Viator’s 395,000 products on your own website or travel-booking system. For our partners who are the merchant of record (merchant partners), we will also discuss how to interact with our booking systems via the Partner API to support your booking/checkout workflow.

All documentation pertaining to the Viator Partner API can be found here. If you have any questions about your integration, please reach out to affiliateapi@tripadvisor.com at any time.

Please note that which endpoints you are able to access depends on what kind of partner you are – merchant or affiliate.

Furthermore, in a small number of cases an endpoint accessible to both partner types will behave differently between merchants and affiliates. We will mention these differences in the relevant sections.

What partner type am I? Merchant or affiliate?

While we have one Viator Partner API, there are endpoints that are only available to a certain partner type. Below, we’ve outlined some key differences to help you understand which partner type you are.

viator merchant api

“Merchant” partners

A merchant integration is a robust and complex integration, and requires a deposit to be paid prior to development

Transaction occurs on partner's website

Partner is merchant of record

Partner handles customer service

Partner can markup or discount pricing

Affiliate API illustration

“Affiliate” partners

An affiliate integration is less complex than a merchant integration and does not require a deposit to be paid prior to development

Traffic is redirected to Viator to complete transaction

Viator is merchant of record

Viator handles customer service

You earn a commission everytime a product is booked

t

Still not sure what partner type you are?

Contact us and we’ll tell you what partner type you are.

Getting started: Building your local database

In order to begin selling Viator experiences, you must ingest and keep up-to-date a database of Viator products and availability schedules. Products may then be managed and filtered according to your business needs. All our products are categorized under a destination hierarchy. You will use this hierarchy to build your database and effectively catalogue our products.

/v1/taxonomy/destinations

Get details of all destinations

  • Every product in the Viator catalogue is categorized according to the destination/locale in which it operates. This endpoint returns a complete list of Viator destinations, including destination names and parent identifiers.
  • This endpoint is used to help define the locations of products (i.e. primary and secondary) for the purpose of merchandising products. For example, Disneyland Paris’s primary destination is Paris, even though the actual location (secondary location) is Marne-la-Vallee. Travelers are more likely to search for Paris when looking for Disneyland Paris than Marne-la-Valle.
  • This endpoint is used to provide navigation on your site, through drilldown lists, combo boxes, or breadcrumbs.
  • While destinations rarely change, we recommend refreshing the list of destinations weekly.

/v1/taxonomy/attractions

Gets all attractions for a destination

  • This endpoint returns all attractions within a destination and is used to help merchandize products by attraction. 
  • This is also useful for navigation as well as building out basic attractions pages. 

Ingesting products & keeping the product catalogue up to date

Key features of these endpoints

"

Ingest over 395,000 products quickly and efficiently

R

Updating product content with fewer, but more frequent requests provides travelers with accurate information

Only ingesting new or modified product information speeds up load times

d

New structured data fields make it easier to break out key information and merchandise products

By using a local database, you need only perform a single initial ingestion of data*; then, only new and updated product content will be ingested. This will result in faster load times and will provide a better experience for travelers. There are three product content endpoints that are used to ingest data:

/products/modified-since

1a. Perform an initial ingestion of all product data

  • Performs an initial ingestion of all product data into a local database. You may filter out any products during the initial ingestion.

1b. Ingest only new or updated product data

  • Used to ingest only new or updated product information. Products are considered updated when the supplier makes any changes to the product’s details, excluding pricing and availability changes, which are retrieved from the availability schedule endpoint.
  • We recommend polling this service hourly to look for updates and to avoid any discrepancies.

/products/{product-code}

2. Pull product data for a single product

  • Pulls info for a single product by providing the corresponding product code.
Use cases
  • Pulling product info for a single product can be useful for merchandising purposes. For example, you may want to recommend a related product for an email remarketing campaign. Or you may want to include a top product on a pop-up or intestinal to grab the attention of customers exiting your site.
  • Update product information between routinely scheduled checks for updated or new products via the /products/modified-since endpoint.
  • If you needed to force a refresh of some products in your system. For example, if products were corrupted or if you wanted to integrate new features you have missed on your initial ingestion.

    /products/bulk

    3. Pull product data for multiple products

    • Similar to /products/{product-code}, this endpoint will pull in product information for a specified list of products, up to 500 products per request.
    • This endpoint is useful for further product curation beyond featuring a single product. For example, you may curate a list of tours for a niche audience or you may want all product details of products from a single destination.
    • In the case that a product was not correctly ingested via the /products/modified-since endpoint, you can use /products/bulk to reingest those products.
    • This should be used only if you have a small curated product list that you want to refresh on schedule or if you need to need to fix some products on your end.

    *You may need to re-ingest the entire product catalogue during development

    What’s included in the initial ingestion of our product catalogue?

    These endpoints returns all product information, including, but not limited to:

    • Titles
    • Descriptions
    • Ticket types
    • Supplier photos*
    • Start and end times
    • Meeting points
    • Traveler pick up details (if applicable)
    • Inclusions and exclusions
    • Cancellation policy
    • Additional info
    • Booking confirmation settings (e.g. instant confirmation or on-request products)
    • Booking requirements (e.g. min or max travelers)
    • Booking questions
    • Itineraries
    • Product options
    • Supplier name

    *supplier photos are ingested as a default. Viator also allows travelers to upload their own photos. Traveler photos will have to be ingested via /v1/product/photos.

    /locations/bulk

    Get full location details for the requested location references

    • Location details include the name of the location, the street address, and the longitude/latitude coordinates of the location. These locations are not to be confused with destinations.
    • Locations detail can be used to highlight pickup/drop off points, to build itineraries, or even overlay locations on a map to help provide additional context to what a traveler can expect on the tour.
    • Travelers can also provide special pickup points when filling out booking questions. This endpoint can be used to provide those locations to travelers through a drop down list. Otherwise, travelers can specify custom pickup info through a plain text field.
      structured itinerary

      Example of a structured itinerary with a map overlay

      Getting availability and pricing for products

      Key features of these endpoints

      Real time availability checks ensure accuracy and create a seamless checkout

      Only ingesting new or modified availability schedules speed up load times

      Schedules can be used to display future availability

      f

      Structured data allows you to easily build a variety of display and filtering options

      The Viator Partner API’s availability endpoints enable you to provide availability and pricing information in real time. To improve transfer speeds and reduce the amount of data transferred, availability is communicated by providing the overall schedule season and specifying unavailable dates rather than available dates. Special pricing periods are also included allowing you to surface supplier promotions to customers.

      Ingesting and updating availability schedules follows a similar process as ingesting and updating product information:

      /availability/schedules/modified-since

      1a. Perform an initial ingestion of all availability schedules

      1b. Make regular calls to check for new or updated availability schedules

      • We recommend doing checks at least every hour to ensure that your travelers see the most up-to-date pricing and availability. A product’s availability is considered modified if a supplier makes changes to pricing or availability.

      /availability/schedules/{product-code}

      2. Pull availability schedules for a single product

        /availability/schedules/bulk

        3. Pull availability schedules for multiple products

        • This endpoint pulls availability for a list of products, up to 500 products per request.

          /availability/check

          4. Checking availability in real time

          • This endpoint enables a real time check and calculation of pricing and availability and should be used throughout the booking path. For example, this endpoint can be used to ensure accuracy when the traveler is starting the checkout process.
          • This endpoint would be used before a booking is made to verify the product is available on the desired date for the desired passenger mix. Before a booking hold can be requested, you’ll need to use this endpoint to check that it’s still available and make sure the pricing is correct.
          • This should not be called until a user inputs dates and passenger mix.

            Creating a seamless booking experience
            (MERCHANT PARTNERS ONLY)

            A series of booking endpoints enables you to build booking/checkout user flows that allow travelers to add experiences to shopping carts, provide pickup info, add special requirements (like dietary restrictions), and hold their booking to guarantee availability and pricing.

            booking workflow

            In general, to give your travelers the ability to book a product, you must do the following:

            /availability/check

            1. Check availability

            • Using traveler inputs of tour date, tour time, and passenger mix, you will perform a real time check before the traveler is able to add to a shopping cart and/or before placing the booking.

              /bookings/hold

              2. Request a booking hold

              • Requests the creation of a booking-hold – a guarantee that either the price or availability (or both) of the product will be retained until a booking request is made using the /bookings/book endpoint.
              • Availability holds may not be granted, but pricing holds will always be granted and is sufficient to confirm bookings.
              • Do not call this service just because the traveler picked a date and passenger mix. Only call this service if a user takes high intent actions, like adding to a cart or during checkout.
              Use Cases
              • Although booking holds are an optional feature, we recommend using this functionality. This feature gives travelers flexibility to continue to shop without worrying about any products becoming unavailable.

                /bookings/book

                3. Confirm the booking

                • Confirms/finalizes the held booking using the /bookings/book endpoint.
                • All relevant booking information will need to be provided in the request (e.g. booking questions).

                  /bookings/status

                  4. Provide booking statuses

                  • Requests the status of an existing booking. Statuses can be either: confirmed, rejected, cancelled, or pending.
                  • This endpoint is required for manual confirmation products (formerly known as “on request” products).
                  Use cases
                  • This is useful to display to users to keep them up to date on the status of their bookings.
                  • This is also useful when reconciling your finances to account for any cancelled bookings where a refund was processed.

                    Cancelling bookings (MERCHANT PARTNERS ONLY)

                    All cancellations (except those requested after the date of travel) must be performed via the API. Should you need to cancel a booking after the travel date, please contact Viator Partner Support.

                    /bookings/cancel-reasons

                    1. Getting cancellation reasons

                    • In order to successfully cancel a booking, a traveler must select one of our pre-set cancellation reasons. This endpoint pulls in the acceptable cancellation reasons. You can take these cancellation reasons and provide them to travelers during the cancellation process.
                    • Recommended: as the acceptable reasons for cancellation may be altered at any point, we recommend retrieving an up-to-date list from this endpoint at least weekly.

                      /bookings/{booking-reference}/cancel-quote

                      2. Getting cancellation quotes

                      • To see if a booking is eligible to be cancelled, make a call to the API using the booking reference number. As the merchant of record, you will be processing refunds and will need to call the API to get the correct refund amount.
                      • If the booking can be cancelled you will be returned a quote and can proceed with cancellation the booking using the /bookings/{booking-reference}/cancel endpoint.

                        /bookings/{booking-reference}/cancel

                        3. Cancel a booking

                          Exchange rates

                          /exchange-rates

                          Getting exchange rates

                          • All our products are priced in the supplier’s currency and will need to be converted to the end user. Using the /exchange-rates endpoint you can pull the exchange rates for conversions between specified currencies.

                          Supported currencies

                          While we support many currencies, payments for bookings can only be made using the following four currencies:

                          • GBP (British Pound)
                          • EUR (Euros)
                          • USD (US Dollars)
                          • AUD (Australian dollars)

                          While you can still price products in any of the supported currencies, you will be invoiced in your choice of the four currencies above.

                          Traveler photos

                          /v1/product/photos

                          Getting traveler-submitted photos

                          • Traveler photos are photos that travelers can upload when submitting their reviews. These photos are Unlike supplier photos, travelers photos are not ingested through any of the /products endpoints.
                          • Including traveler photos have their benefits. Traveler photos help capture the experience from a traveler’s point of view. We only require suppliers to upload a minimum of 4 photos when creating their listing and traveler photos can augment listings with just the minimum amount of photos.
                          • Including traveler photos is required for an “Excellent” build to our API, as we know that including traveler photos generally improves conversion.

                          Note: supplier photos are already ingested through our product ingestion endpoints.

                          Learn more about implementing traveler photos

                          Traveler reviews

                          /v1/product/reviews

                          Getting reviews

                          • This endpoint retrieves the plain text reviews for a product.
                          • Traveler reviews are an important factor for travelers when making bookings.

                          Determining an overall review rating

                          • The response from the /v1/product/reviews endpoint does not directly communicate the number of reviews available for a product or its average rating.
                          • In order to determine the average review rating for a product (e.g., for display or sorting purposes), you will need to ingest all product reviews and perform the calculation yourself.

                          Attractions (AFFILIATE PARTNERS ONLY)

                          These endpoints make it possible for affiliate partners to create pages dedicated to an attraction – e.g. a page that just promotes tours of the Colosseum. A single attraction could have multiple tour grades or multiple tour operators and by building an attraction page, you can present all options to your audience.

                          These endpoints can also be used to display attractions on search results pages (SRPs) and on destination pages.

                          /v1/search/attractions

                          Retrieve list of attractions

                          • This service retrieves a list of attractions associated with the given destination.

                          /v1/attraction

                          Get all attraction details

                          • Attraction details include, but are not limited to: review counts, descriptions, titles, and location information.

                          /v1/attraction/photos

                          Get all photos related to an attraction

                          • The photos in this request may be associated with products that are related to the attraction.

                          /v1/attraction/products

                          Get all attraction-related products

                          • Using this endpoint, you can pull in all the products related to an attraction.
                          • This endpoint can also be used for cross-selling opportunities. For example, you may want to promote nearby attractions.

                          /v1/attraction/reviews

                          Getting reviews for an attraction

                          • This service gets reviews related to an attraction. These reviews might be associated indirectly through the related products.