Product content and catalogue ingestion for the Viator Partner API v2 - full product detail, bulk retrieval, incremental modified-since ingestion, the product tag taxonomy, booking questions, product search and product-to-product recommendations.
{
"openapi": "3.0.2",
"info": {
"title": "Viator Partner API",
"description": "<style type='text/css'>\ncode { white-space: nowrap; }\na { font-weight: bold; }\n\nfigure {\n width: 100%;\n text-align: center;\n font-style: italic;\n font-size: smaller;\n text-indent: 0;\n border: thin silver solid;\n margin: 0.5em;\n padding: 0.5em;\n}\n</style>\n\n## Updates\n\n### Latest updates: \n\n| Date | Description |\n|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 5 May 2026 | Added support for product option level logistics resolution via a new optional `logistics` object. |\n| 13 Feb 2025 | Added `videos` object to [/products/{product-code}](#operation/products), [/products/modified-since](#operation/productsModifiedSince), [/products/bulk](#operation/productsBulk), [/products/search](#operation/productsSearch) and [/search/freetext](#operation/searchFreeText) responses. |\n| 4 Feb 2025 | Added `AED`, `ARS`, `CLP`, `CNY`, `COP`, `FJD`, `IDR`, `ILS`, `ISK`, `KRW`, `MXN`, `MYR`, `PEN`, `PHP`, `PLN`, `RUB`, `THB`, `TRY` and `VND` as currency options in the request to [/products/search](#operation/productsSearch) and [/search/freetext](#operation/searchFreeText). \n| 11 Sep 2025 | Updated [/bookings/modified-since](#operation/bookingsModifiedSince) response with new `eventTypes` and enabled endpoint access to all partner types. \n| 01 Jul 2025 | Added [/amendment/check/{booking-reference}](#operation/amendmentCheck), [/amendment/quote](#operation/amendmentQuote) and [/amendment/amend/{quote-reference}](#operation/amendmentAmend) endpoints to [Bookings](#tag/Bookings) section \n| 27 Mar 2025 | Update [/search/freetext](#operation/searchFreeText) request section add filtering by tags for \"searchType\": \"PRODUCTS\" \n| 20 Mar 2025 | Added [/products/recommendations](#operation/productsRecommendations) to [Products](#tag/Products) section. This endpoint will provide product-to-product recommendations to users. |\n| 19 Mar 2025 | Updated endpoints [/availability/schedules/{product-code}](#operation/availabilitySchedules), [/availability/schedules/bulk](#operation/availabilitySchedulesBulk), [/availability/schedules/modified-since](#operation/availabilitySchedulesModifiedSince), [/availability/check](#operation/availabilityCheck), [/search/freetext](#operation/searchFreeText), [/products/search](#operation/productsSearch), [/bookings/cart/hold](#operation/bookingsCartHold) and [/bookings/hold](#operation/bookingsHold) as well as [Inclusions & exclusions](#section/Appendices/Inclusions-and-exclusions) with `Extra Charges` information |\n| 11 Feb 2025 | Removed `TRANSACTION_NOT_ALLOWED`, `CARD_INACTIVE` and `CARD_RESTRICTED` rejection reasons from [/bookings/cart/book](#tag/Bookings/operation/bookingsCartBook). |\n| 4 Dec 2024 | Updated [/bookings/cart/book](#tag/Bookings/operation/bookingsCartBook) response with the following new rejection reason: `PROCESSOR_ISSUE_WITH_PAYMENT`. |\n| 19 Nov 2024 | Updated [/bookings/cart/book](#tag/Bookings/operation/bookingsCartBook) response with the following new rejection reasons: `SUSPECTED_FRAUD`, `SOFT_DECLINE`, `HARD_DECLINE`, `THREE_D_SECURE_REQUIRED`, `INTERNAL_ERROR`, `PROCESSOR_UNAVAILABLE`. |\n| 24 Oct 2024 | Deprecated [/v1/product/photos](#operation/v1ProductPhotos) endpoint |\n| 23 Oct 2024 | Added [/attractions/search](#operation/attractionsSearch) and [/attractions/{attraction-id}](#operation/attractions) to [Attractions](#tag/Attractions) section<br/>Added [/destinations](#operation/destinations) to [Auxiliary](#tag/Auxiliary) section<br/>Updated [Access to endpoints](#section/Access-to-endpoints) section to include new endpoints and removed the ones marked for deprecation<br/>Updated [Resolving references](#section/Workflows/Resolving-references) section |\n| 21 Oct 2024 | Removed `VIATOR_EXCLUSIVE` flag from product search endpoints |\n| 1 Oct 2024 | Removed COVID-19 safety attributes from `AdditionalInfo` schema (part of product content response; e.g., from [/products/{product-code}](#operation/products) endpoint) |\n| 6 Aug 2024 | Changes to behaviour with `DEFAULT` tour grade for product, availability, book hold and confirm endpoints. See note at end of section [Product Option Code](#section/Key-concepts/Product-options). Note: these changes are backwards compatible. |\n| 29 Jul 2024 | Updated [/bookings/modified-since](#operation/bookingsModifiedSince) response with new eventType: CUSTOMER_CANCELLATION, for Customer initiated cancellations. |\n| 14 Mar 2024 | Updated [/bookings/cart/book](#tag/Bookings/operation/bookingsCartBook) response with the following new rejection reasons: `INSUFFICIENT_FUNDS`, `INVALID_PAYMENT_DETAILS`, `TRANSACTION_NOT_ALLOWED`, `CARD_INACTIVE` and `CARD_RESTRICTED`.<br/> Updated [/bookings/status](#tag/Bookings/operation/bookingsStatus) response with `ON_HOLD` status |\n| 13 Feb 2024 | Updated [/suppliers/search/product-codes](#operation/suppliersSearchProductCodes) with the following new attributes: `supplierAgreedToLegalCompliance`, `registrationCountry`, `tradeRegisterName` and `registeredBusinessNumber`. Also updated the `ContactDetails` schema with a new attribute `countryCode`. |\n| 11 Sep 2023 | Added support for PDF vouchers. Made bookerInfo firstName required to match definition. |\n| 5 Jul 2023 | Added [/bookings/cart/hold](#operation/bookingsCartHold) and [/bookings/cart/book](#operation/bookingsCartBook) to [Bookings](#tag/Bookings) section<br />Added [/v1/checkoutsessions/{sessionToken}/paymentaccounts](#operation/paymentsCreateToken) to [Payments](#tag/Payments) section |\n| 15 May 2023 | Modified [Accept-Language-header-parameter](#section/Localization/Accept-Language-header-parameter) section to accurately reflect currently allowed values |\n| 16 Mar 2023 | Added [/search/freetext](#operation/searchFreeText) and [/suppliers/search/product-codes](#operation/suppliersSearchProductCodes) to [Access to endpoints](#section/Access-to-endpoints) section |\n| 6 Mar 2023 | Added Canadian dollars (CAD) as currency option in request and response to [/bookings/hold](#operation/bookingsHold), [/bookings/book](#operation/bookingsBook) and [/bookings/status](#operation/bookingsStatus) endpoints |\n| 6 Jan 2023 | Added two new COVID-19 safety attributes to `AdditionalInfo` schema (part of product content response; e.g., from [/products/{product-code}](#operation/products) endpoint) |\n| 4 Jan 2023 | Updated or created `ProductSearchFiltering`, `ProductSummary`, `ProductSearchSorting`, `ProductSearchFlag`, `TranslationDetails`, `SearchDurationInfo` and `SearchRatingInfo` schemata for the [/products/search](#operation/productsSearch) endpoint request/response, updated example request and merchant and affiliate response examples, and updated [Postman collections](#section/Testing/Postman-collections-for-testing) in line with these changes |\n| 3 Jan 2023 | Updated example request and response for [/search/freetext](#operation/searchFreeText) endpoint |\n| 12 Dec 2022 | Added [/search/freetext](#operation/searchFreeText) endpoint |\n| 10 Nov 2022 | Updated [/bookings/hold](#tag/Bookings/operation/bookingsHold) and [/bookings/modified-since/acknowledge](#tag/Bookings/operation/bookingsModifiedSinceAcknowledge) descriptions |\n \n\n\n### Update history: \n\n- All significant modifications made to this document since its creation can be found in the [Update history](#section/Appendices/Update-history) section.\n\n# Support\n\n## Onboarding / integration\n\nIf you require help or technical advice while you are carrying out your integration, please contact the onboarding team via email at: affiliateapi@tripadvisor.com\n\n### Integration guides\n\nOur onboarding specialists have put together [in-depth guides](https://partnerresources.viator.com/travel-commerce/implementation/?source=specs) covering various topics to help you during your integration. \n\n### Site certification for merchant partners\n\nIf you are a merchant partner, once your API integration has been completed, it must pass certification prior to going live in order to ensure data integrity and the appropriate use of API services. Please peruse and bear in mind [our certification requirements](https://partnerresources.viator.com/travel-commerce/merchant/certification/?source=specs) prior to and during development.\n\n## Operational support\n\nIf are a merchant partner, have completed your integration and your site is operational, please see the [Partner Help Center - Merchant partner support](https://partnerhelp.viator.com/en/categories/37-merchant-partner-support?source=specs) page for information about what to do if you encounter a problem and require support.\n\n# About\n\n## Viator Partner-API v2\n\n### What is it?\n\nThe Viator Partner API v2 comprises a set of endpoints that can support the operation of a fully-featured tours and experiences booking website or application; or, it can be integrated with your existing travel-booking software.\n\nThe API exposes a variety of services that allow the retrieval of all product details, such as descriptive text and structured metadata, pricing, terms and conditions, photos and reviews. This data can either be ingested and managed on your local system, or calls can be made in real time to retrieve content in response to your users' activity on your systems.\n\nThe API allows product content, pricing and availability data to be retrieved in bulk or queried in real-time, it can perform pricing calculations according to the number and type of traveler and product option combinations available, and it supports availability and pricing holds as part of its booking and booking-cancellation functionality. \n\n### Who is it for?\n\nThe Viator Partner-API is a designed for use by organizations partnered with Viator as [Affiliate partners](https://partnerresources.viator.com/travel-commerce/affiliate/) or [Merchant partners](https://partnerresources.viator.com/travel-commerce/merchant/).\n\n#### Affiliate partners\n\n\nAffiliate partners have full access to the areas of the API relating to content, but sales of Viator products must be carried out on the Viator site itself. \n\nWhen a customer wishes to book a product from an affiliate's site, they are instead redirected to the relevant product page on [viator.com](https://viator.com) via a unique URL in order to complete the purchase. Once on the Viator site, a cookie is set such that all transactions will accrue a commission for that partner until the cookie expires.\n\nPurchases of products originating from the affiliate's site are recorded and a commission on these sales is paid periodically.\n\nFor more information on this partner type, see: [Viator's Affiliate API Solution](https://partnerresources.viator.com/travel-commerce/affiliate/)\n\n#### Merchant partners\n\nThe merchant partner relationship is one in which the partner is the **merchant of record**; i.e., the partner takes full responsibility for all financial records and transactions carried out by their users, as well as providing customer support with regard to providing general assistance, processing cancellations and refunds, and liaising between suppliers and customers when the need to communicate arises.\n\nFor more information on this partner type, see: [Viator's Merchant API Solution](https://partnerresources.viator.com/travel-commerce/merchant/)\n\n\n## New features in this version\n\nThe Viator Partner-API v2.0 is a fully-redesigned system with regard to our previous API products. It includes all key fuctionality available in previous versions, but now provides nearly fully-structured data elements, and a more modern, concise and easily-understandable interface.\n\nIn addition, we have made significant improvements to performance across all functions of the API, and particularly in the area of product content and availability data ingestion.\n\n### Simplified and optimized data ingestion \n\nData ingestion has been greatly improved over previous versions of this API. Now, partners need only perform a single initial ingestion of data; then, only new and updated product content, availability and pricing information is retrieved as a 'delta update' as it becomes available.\n\nIn addition:\n- A single end-point allows both bulk ingestion and delta updates, which can be controlled using a pagination cursor or with a time-stamp parameter to allow for point-in-time ingestion of any new updates and easy recovery from ingestion failure\n- The structure of a product's pricing and availability schedules has been simplified to reduce response size\n\n#### Product content\n\n- All pricing is standardized to the supplier's currency, avoiding the need to update on account of exchange rate fluctuations \n- Structured location, tag, booking question, review and photo data is available from separate endpoints to allow for parallel ingestion, and resusable data can be ingested once and applied globally\n\n#### Availability schedule information\n\nImprovements to availability schedule ingestion performance and usability have been achieved:\n\n- Availability is now communicated by providing an overall schedule season and specifying *unavailable* dates instead of available dates, a significantly more compact format that improves transfer speeds and minimizes storage needs \n\n- Availability and pricing information is given on a days-of-the-week basis, which can help with filtering and improving visibility of product availability for customers.\n\n- Information about special pricing periods that may be running throughout a product's seasons is included and is easy to interpret, allowing partners to surface promotions to customers.\n\n- Accurate pricing and applicability information for products that have 'per unit' (group) pricing is now included in the availability & pricing response; whereas support for this pricing model was limited in previous versions of this API. This allows partners to improve pricing exposure for these products.\n\n### Structure-rich content\n\nProviding structured content is a major focus of this API. Product information that was previously stored as natural-language descriptions in a single, lengthy field is now represented in intuitively-structured, machine-interpretable schemata that empowers partners to apply finely-grained merchandising control, including:\n\n- Tour itineraries with comprehensive location data to allow for graphical display and advanced search\n- Tour details, inclusions and dynamic health & safety information to support changing requirements due to global pandemic response initiatives\n- Machine-parseable booking questions and answers\n\n### Improved real-time availability and pricing checking\n\nThe [real-time availability check endpoint](#operation/availabilityCheck):\n- Allows you to check availability and pricing in real-time for a specific product / [product-option](#section/Key-concepts/Product-options) / date / starting time / pax mix combination\n- Returns the ticket availability status along with a pricing breakdown (by age band) and total price (all age bands) in a simplified format to reduce response size\n- Pricing components are stated explicitly, including the Recommended Retail Price (RRP), partner net price, special-offer pricing and booking fee component details\n\n### Improved booking workflow\n\nThe [booking workflow](#section/Booking-concepts/Making-a-booking) now includes an optional booking-hold step, which allows you greater predictability of a successful booking, thereby increasing conversion rates by decreasing friction in the booking flow.\n\nThe [booking hold](#operation/bookingsCartHold) endpoint supports two kinds of hold:\n- Inventory/availability hold (increased likelihood of receiving a booking confirmation)\n- Pricing hold (mitigates against pricing changes at the time of booking)\n\nThe [real-time availability and pricing endpoint](#operation/availabilityCheck) also delivers \\~5% faster performance than previous versions of this API.\n\n# Access to endpoints\n\nThe API endpoints accessible to you depend on which kind of partner you are; affiliate or merchant. \n\n**Basic-access Affiliate partners** have access to a limited subset of the non-transactional endpoints of the Viator Partner API. The basic-access tier allows affiliates to quickly get started building their site with fewer complexities. The following step-by-step guide explains how to do it: [Golden Path \u2013 Basic Access Affiliate Partners](https://partnerresources.viator.com/travel-commerce/affiliate/basic-access/golden-path/?source=specs) \n\n**Full-access Affiliate partners** have access to all non-transactional endpoints; i.e., everything except booking, booking hold and booking cancellation endpoints. This access model applies equally to whitelabel partners.\n\n**Full-access + Booking Affiliate partners** have access to all the same endpoints as **Full-access Affiliate partners** as well as transactional endpoints. i.e., including cart booking, cart booking hold and booking cancellation endpoints.\n\n**Merchant partners** have access to all endpoints.\n\nThe following table describes which partner types have access to which endpoints:\n\n| Endpoint | Basic-access Affiliate | Full-access Affiliate | Full-access + Booking Affiliate | Merchant |\n|-----------------------------------------------------------------------------------------|:-----------------:|:----------------:|:------------:|:------------:|\n| [/products/modified-since](#operation/productsModifiedSince) | \u274c | \u2705 | \u2705 | \u2705 |\n| [/products/bulk](#operation/productsBulk) | \u274c | \u2705 | \u2705 | \u2705 |\n| [/products/{product-code}](#operation/products) | \u2705 | \u2705 | \u2705 | \u2705 |\n| [/products/tags](#operation/productsTags) | \u2705 | \u2705 | \u2705 | \u2705 |\n| [/products/booking-questions](#operation/productsSearch) | \u274c | \u274c | \u2705 | \u2705 |\n| [/products/search](#operation/productsSearch) | \u2705 | \u2705 | \u2705 | \u2705 |\n| [/products/recommendations](#operation/productsRecommendations) | \u274c | \u2705 | \u2705 | \u2705 |\n| [/attractions/search](#operation/attractionsSearch) | \u2705 | \u2705 | \u2705 | \u2705 |\n| [/attractions/{attraction-id}](#operation/attractions) | \u2705 | \u2705 | \u2705 | \u2705 |\n| [/availability/check](#operation/checkAvailability) | \u274c | \u2705 | \u2705 | \u2705 |\n| [/availability/schedules/{product-code}](#operation/availabilitySchedules) | \u2705 | \u2705 | \u2705 | \u2705 |\n| [/availability/schedules/bulk](#operation/availabilitySchedulesBulk) | \u274c | \u2705 | \u2705 | \u2705 |\n| [/availability/schedules/modified-since](#operation/availabilitySchedulesModifiedSince) | \u274c | \u2705 | \u2705 | \u2705 |\n| [/bookings/cart/hold](#operation/bookingsCartHold) | \u274c | \u274c | \u2705 | \u2705 |\n| [/bookings/cart/book](#operation/bookingsCartBook) | \u274c | \u274c | \u2705 | \u2705 |\n| [/bookings/hold](#operation/bookingsHold) | \u274c | \u274c | \u274c | \u2705 |\n| [/bookings/book](#operation/bookingsBook) | \u274c | \u274c | \u274c | \u2705 |\n| [/bookings/status](#operation/bookingsBook) | \u274c | \u274c | \u2705 | \u2705 |\n| [/bookings/cancel-reasons](#operation/bookingsCancelReasons) | \u274c | \u274c | \u2705 | \u2705 |\n| [/book
# --- truncated at 32 KB (2185 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/viator/refs/heads/main/openapi/viator-partner-api-v2-openapi.json