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 300,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. Access to endpoints depends on your partner type and the endpoints in this guided will be marked. For example, endpoints marked as below would not be accessible by Basic-access 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?
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.

“Affiliate” partners with basic access
Traffic is redirected to Viator to complete transaction
Viator is merchant of record and handles customer service
Have access to a limited set of non-bulk endpoints
Partner earns a commission every time a product is booked

“Affiliate” partners with full access
Traffic is redirected to Viator to complete transaction
Viator is merchant of record and handles customer service
Have access to all non-transactional endpoints
Partner earns a commission every time a product is booked

“Merchant” partners
Transaction occurs on partner’s website
Partner is merchant of record & handles customer service
Have access to most endpoints including transactional ones
Partner can markup or discount pricing
Getting started: choosing ingestion-model or search-model
While merchant partners are required to use the ingestion model, our affiliate API partners have two choices when deciding how they will connect to Viator’s supply: they can choose an ingestion-model or a search-model.
Ingestion model
- The ingestion model of connecting to Viator’s supply requires that the partner builds and maintains a local database of products and also requires that the partner makes regular calls to Viator to ensure that product and availability information is up to date.
- This model is required for merchant partners and is ideal for partners that want a full-scale tours and activities integration and can manage large amounts of data
Search model
- The search model is an easiest and faster way to connect to Viator’s supply via an API integration. The amount of data returned in a search API request is less than what would be returned using the ingestion model, and therefore there is no need to store any data.
- This model is ideal for partners that are looking for a fast integration and do not desire a full tours and activities integration.
Quick find
Building your local database
Products
- Ingest all product data
- Ingest only new or updated product data
- Pull single product data
- Pull multiple products data
- Pull product summaries based on search criteria
- Get location details
Availability
- Ingest all availability schedules
- Get new or updated availability
- Get single product availability
- Get multiple product availability
- Real time availability check
Booking (merchants only)
Cancellations (merchants only)
Exchange rates
Traveler photos
Traveler reviews
Attractions (affiliates only)
Building your local database (ingestion model)
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 300,000+ products quickly and efficiently
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
Structured data fields make it easier to break out key information and merchandise products
/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 our product catalogue?
These endpoints return 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
- Review ratings and counts
*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.
/products/search
Pull product summaries based on search criteria
- When product summaries are returned, they contain a small amount of crucial product information such as, but not limited to, title, short descriptions, images, pricing, and review ratings and counts.
- You can effectively filter out products returned in the request by specifying search criteria, such as destination IDs, price range, and date range. You also have the option to filter by category using tag IDs and can filter by flags, such as free cancellation or skip-the-line tours.
- You will specify the format in which you want the response, such as the language and currency and will specify how the response will be sorted. Tours, activities and experiences are ranked using exclusive Viator data that may include product quality, reviews, ratings, photos, popularity, user preferences, price, bookings made through Viator, and payments made by operators.
- This endpoint is ideal for where short product summaries would be ideal, such as on search cards on search results pages.
/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.
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
Structured data allows you to easily build a variety of display and filtering options
/availability/schedules/modified-since
1a. Perform an initial ingestion of all availability schedules
- Similar to using the /products/modified-since endpoint, you’ll use the /availability/schedules/modified-since endpoint to get availability for all products. Getting everything at once and updating only new or modified availability schedules will speed up ingestion and ensure availability is not stale.
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
- This endpoint can be used in conjunction with /products/{product-code to pull availability 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.

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
- If the /bookings/{booking-reference}/cancel-quote endpoint identifies the booking as cancellable, you can process the cancellation using /bookings/{booking-reference}/cancel.
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.
Traveler reviews
/reviews/product
Getting traveler reviews
- This endpoint retrieves traveler reviews, supplier responses, review photos and all other necessary attributes in one request.
- Reviews are retrieved on an individual product basis.
- “Helpful votes” left by other travelers help provide relevance to customers
- You can retrieve up to 500 reviews per product. Our research indicates that there are diminishing returns after the 100th review.
- You can filter reviews by rating, by a single language, and can filter out machine-translated reviews. Machine translated reviews will always be sorted after reviews in the primary language.
- You can sort reviews by one of the following: by highest rating, most recent, or most helpful. This sort is applied within the chosen languages.
Determining ratings
Product ratings and rating counts are returned by the /products/{product-code}, /products/bulk, and products/modified-since endpoints. Details of attributes included can be found in the API specs.
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.