Viator Reservation System API (1.0)

The API specifications herein outline the steps and requisites for integrating operator reservation systems with Viator. This documentation serves as the definitive guide for developers and technical teams responsible for implementing and maintaining this critical integration.

The specifications are for the exclusive use of operators registered with Viator and their respective reservation system providers.

Integration with a reservation system may only commence after any one operator on the reservation system has registered with Viator. To learn more about joining Viator, visit the supplier sign-up page.

To begin, please review the following sections:

• What’s new
• Connectivity overview
• API overview
• Implementation approach
• Frequently asked questions

Adherence to these specifications is crucial for successful integration, guaranteeing optimal performance, data integrity, and a superior user experience for both operators and Viator customers.

If at any point you need clarification or help, please don’t hesitate to contact us here.

This section outlines the key updates and new features in the latest version of the Operator Connectivity API specifications:

The Operator Connectivity API now uses versioning for backward compatibility and smoother updates. Existing legacy endpoints are considered version 1.0, while versions of new endpoints begin with 2.0.

To allow early access and feedback on upcoming endpoints before release, a Beta program has been introduced. This allows partners to evaluate pre-production versions. Review the Beta section for newly introduced endpoints.

As new versions of the endpoints are introduced, older versions and endpoints that were replaced are set for deprecation. Review the Soon to Deprecate section for a list of endpoints scheduled for deprecation.

Version 2.0 and above endpoints now expose the API key on the HTTP headers. Backward compatibility for legacy v1 endpoints continues to be supported, no changes required at this point, but header key authentication is also supported on v1 endpoints.

Version 2.0 and above endpoints communicate using the JSON standard. Therefore, the headers "Content-Type" and "Accept" take only the "application/json" value and only this value will be sent in responses.

A simplified product variant (aka product option) identifier has been introduced to allow reservation systems to define a unique single identifier to identify any product variant. This new identifier is applicable only to v2.0 API's and must be returned in the [Tour List API] (#tag/Reservation-system-APIs/operation/tourList).

One of the most impactful changes with the new version is the introduction of pricing capabilities that support all of Viator's existing price types including per person price, tiered per person price and unit price. Review the Beta section for newly introduced endpoints.

Version 2.0 introduces a new endpoint that allows Viator to request for the reservation of inventory and price before the booking is made. In V1.0 inventory was held via the Real-time Availability API request using the AvailabilityHold attribute. In V2.0, this process has moved to the new endpoint that now also expects pricing to be held. Review the Beta section for the newly introduced endpoint.

For version 2.0 APIs a contract testing tool is available to help ensure that services are performing according to specification. The tool provides multiple test cases, along with parameters required to perform the tests, for each API. For more information review the Contract Testing Tool section under Downloads and links.

The following sections detail the operational impact of integration and endpoints on overall connectivity, operator processes, and customer experience.

The API structure is organized into three primary categories:

• Catalog operations
• Availability and pricing
• Booking operations

Tour list

The Tour List API streamlines the mapping of an operator's reservation system inventory (products and product options) to Viator's equivalent. These mapped values are then used in subsequent transaction requests, where Viator transmits requests using the reservation system's identifiers.

The details returned in the Tour List API are surfaced in the Product Connection tab of the Viator supply center to facilitate accurate inventory mapping between the two systems.

Mapped inventory must have capacity (available for sale). If a product cannot be mapped, there is likely a problem with the Tour List API response or with the inventory capacity (not available for sale, issue with availability api’s response). The technical team at the reservation system is typically better equipped to resolve such scenarios.

Integrating our comprehensive suite of availability and pricing APIs revolutionizes how operators manage availability and pricing of their inventory, significantly reducing the need for tedious manual updates within the management center. This powerful collection includes a set of distinct APIs, each tailored to streamline specific aspects of the operations and customer experience:

• Calendar API (v2.0) - Empowers Viator to access and retrieve long term availability, pricing and special offer (promotions) information from the reservation system. This allows Viator customers to view available dates and prices on the product details page calendar. For operators, these APIs automate the regular updates of availability. Pricing and special offers, eliminating the need for manual intervention through the Viator supply center. This API replaces both the Batch Availability and the Batch Pricing APIs (both of which are v1.0).

• Availability Check API (v2.0) - Designed for real-time updates, this API enables Viator to verify capacity (availability for sale) in real-time throughout the customers progression through the booking funnel. This ensures that customers always see the most current availability and pricing information, preventing overbookings, erroneous customer charges, encouraging last minute bookings and enhancing the overall customer experience. This capability is crucial for supporting operators' dynamic, fluctuating pricing strategies and responding instantly to market demands. This API replaces the Real-time Availability API ( v1.0).

By leveraging these APIs, you can automate a significant portion of operational tasks, leading to improved accuracy, reduced operational overhead, and a more responsive and efficient system for managing availability, pricing and special offers. This automation not only streamlines operators internal processes but also enhances the customer experience by providing up-to-date and reliable information.

Support for the above listed APIs is a mandatory integration requirement, highlighting their fundamental role in efficient inventory and pricing management for operators, and overall impact to the customer bookoing experience.

Legacy v1.0 Availability and Pricing APIs

Batch availability API

*This API will soon be scheduled for deprecation. This API updates the data used by the calendar that shows product availability on our sites. It can be used to automate the process of blocking-out dates on which the product is unavailable that would ordinarily be accomplished using the Availability section of the management center.

If you need to modify the availability of a product on a certain date, this change needs to be carried out on your system. Your changes will appear on our calendars once the periodic update occurs. The frequency of the update depends on how far in the future the affected date is, as follows:

Days into the future	Calendar update frequency
0-2	2 hours
3-30	1.5 days
90	3 days
180	4.5 days
180+	7 days

Therefore, please allow enough time for changes to availability made on your system to be picked up and reflected on the Viator and Tripadvisor calendars.

Real-time availability and pricing API

This API will soon be scheduled for deprecation. The real-time availability and pricing API checks that the date is still available before allowing a customer to proceed with their booking. If a customer selects a date that is no longer available, your API will respond with an unavailable message (e.g.: 'sold out' or 'no event'). The customer will be prevented from proceeding with the booking and will be asked to select an alternative date.

This API also checks the group size; for example, if we receive an availability request for three adults, and you only have two places available, an unavailability reason of “traveller mismatch” will prevent the booking of three, but it will not block the date from sale. We encourage internal discussion about the differences in the availability responses for the date and the traveller mix.

The Pricing section of the real-time availability and pricing API returns the per-person price for each traveller in the booking. The price received in this response is shown to the customer before they proceed with their booking. If you also return AvailabilityHold, we expect the price - as well as the inventory - to be held. The introduction of pricing information in the real-time availability response is to provide you with the flexibility to be more dynamic with your pricing.

Lastly, the real-time availability and pricing API provides you with the flexibility to reduce your booking cut-off time. We will always make an availability check and only send the booking to you if we receive an 'available' response.

Batch pricing API

This API will soon be scheduled for deprecation.

This API is similar to the batch availability API. Its role is to bulk-update the pricing as shown on the schedule and prices tab in the management center. On our shop front, the lowest price available for a date is used as the “from” price. This price is also used if the real-time availability and pricing API fails for any reason. As pricing changes less often than availability, this call runs less frequently when compared to the batch availability API.

When batch pricing is enabled, your team will no longer need to update pricing manually in the management center, as all pricing information will be copied over automatically from your system. We have included a screenshot below of how the management center will appear once batch pricing is enabled.

Note that when the batch pricing API is supported, you must also include the pricing information in your response to the real-time availability and pricing API. Together, these 2 APIs ensure we always receive the most up-to-date prices from you.

Regarding the price in the batch pricing API response, it is expected that you return the retail price for the product. On our side, we will then subtract the respective margin.

Exceptions: Our Batch Pricing API can only accept 1 currency and this should be the currency that appears in your management center. See available currencies.

The following booking operations APIs are available and, with the exception of the booking amendment API, are mandatory to support: Reserve Booking Booking amendment Booking cancellation These APIs ensure bookings are processed correctly according to your system's protocols.

Reserve API

The Reserve API (v2.0) is designed to hold inventory and price for a booking.

This API supersedes the InventoryHold function previously available in the Real-time Availability API (v1.0). Viator requires reservation systems to hold inventory for a specific duration, facilitating a seamless customer experience by allowing adequate time for payment completion during checkout. This mechanism helps operators avoid overbookings while also preventing inventory from being held unnecessarily. Reservation systems are encouraged to release previously reserved inventory if a booking is not confirmed within a predefined duration.

This API must only be used in combination with Availability and Pricing v2.0 APIs.

Booking API

The Booking API creates a booking in the operator's reservation system upon successful customer payment. This transmission finalizes the booking process.

Operators are not notified via email when a booking is successfully transmitted by the API. However, if an API booking attempt in unsuccessful, the booking fallback process is initiated, which then notifies operators of bookings via email.

Booking Cancellation API

The Booking Cancellation AP streamlines the cancellation and refund process for confirmed bookings. It automates the cancellation request by transmitting it directly to the operator's reservation system. This not only minimizes administrative tasks for operators but also guarantees precise inventory representation, facilitating the resale of tickets.

Operators will receive booking cancellation email notifications only if an API booking cancellation attempt is unsuccessful. Successful API booking cancellations do not generate email notifications for operators.

Booking Amendment

The Booking Amendment API allows changes to confirmed bookings to be sent to the operator’s reservation systems. Customers can request booking amendments after payment and booking confirmation, but before travel.

Permissible amendments:

• Lead traveler's name
• Traveler mix
• Travel date
• Hotel details
• Tour option

Operators will receive booking amendment email notifications only if an API booking amendment attempt is unsuccessful. Successful API booking amendments do not generate email notifications for operators.

1. Project Kick-off Meeting - Scheduled by Viator technical resources after initial contact with the Supplier. The following should be discussed:

• Determine Project Team Members
• Scope of Implementation (capabilities to be supported)
• Agree on Preliminary Time Lines
• Determine Project Team Communication Method

2. Specification Review and Data Mapping - Reservation systems review API specifications in preparation for development. This steps includes:

• Review of API specifications
• Mapping API fields to reservation system fields
• Mapping API product structure

3. Specification Clarifications - Reservation system will raise clarifications with Viator.

• This can be done via email or phone.

4. API Development - Reservation system will commence development of the necessary APIs. This includes:

• Development of reservation system services
• Development of Viator service requests
• Contract testing

5. Test Environment Configuration - Viator will configure the test environment in preparation for certification testing. This step includes:

• API configuration
• Product mapping

6. Certification Testing - Reservation system and Viator will conduct various certification tests to ensure APIs are working as expected. This step includes:

• Agreeing on test products
• Agreeing on a test schedule
• Test Execution and reporting (typically over email)

7. Production Environment Configuration - Viator will configure the production environment. This step includes:

• API configuration
• Product mapping

8. Go Live - Viator and reservation system prepare for Go Live. This includes:

• Schedule Go Live date
• "Switch On" the API, initially for a small number of products
• Transaction monitoring and issue resolution
• Roll out all applicable products
• Sign-off by reservation system and Viator

Integration with the Viator API presents considerable strategic benefits for operators and reservation systems. It substantially enhances distribution and sales capabilities by furnishing Viator with a more comprehensive inventory and real-time transaction capabilities.

API integration with Viator is essential for accommodating last-minute bookings, allowing operators to sell remaining inventory until their specified booking cutoff. Furthermore, the API automates post-booking transactions, such as amendments, cancellations, and redemption verification, which would otherwise necessitate manual handling by operators.

The API's primary functionalities encompass:

• Pricing synchronization
• Calendar optimization and capacity administration
• Reservation and booking confirmation
• Post-booking transaction automation

Additional advantages of API integration include:

• Streamlined Reconciliation: The Viator booking confirmation number is sent to the operator's reservation system via API. This number, along with the operator's confirmation or order number, is displayed on Viator customer vouchers/tickets, allowing for booking reconciliation within the operator's reservation system.

• Barcode Compatibility: The API allows reservation systems to generate barcodes that can be integrated into Viator customer paper or smartphone vouchers/tickets. This functionality is particularly important for operators who use barcode scanners for activity entry.

• Product Identification: Viator customer vouchers display the operator's product identifiers, which are correlated with Viator's own identifiers. This correlation allows operators to have a clearer identification of the product purchased by the customer.

This section provides details pertaining to the API supported business processes, security, communication, testing, and implementation. Achieving integration with Viator the use of both Viator and supplier built APIs:

• Reservation System APIs: Services developed by the reservation system and consumed by Viator.
• Viator APIs: Services developed by Viator and consumed by reservation systems.

This document provides detailed specifications for both, establishing a standard methodology for rapid integration with Viator.

The following sections assume a technical audience familiar with XML, JSON, Webservices, APIs, and similar technologies.

The Viator APIs have been designed to support a number of business processes, from initial product creation through to post-booking transactions. Each of these business processes are supported through Viator or reservation system APIs.

• Product validation and mapping - supported by the Tour List API.
• Determining the availability of a tour - supported by the Availability and pricing APIs.
• Creating a booking in the Suppliers system - supported by the Booking API.
• Amending a booking in the Suppliers system - supported by the Booking Amendment API.
• Cancelling a booking in the Suppliers system - supported by the Booking Cancellation API.

The following sections include the process work flows that the Viator APIs support.

Product creation

The process of creating products on Viator utilizes the Tour List API to retrieve product details and identifiers from the reservation system. The most important (and connectivity critical) information returned by the API are the product and product option identifiers used in subsequent requests to the reservation system.

Create a booking

During the booking process the Availability Check API (v2.0), Reserve API (v2.0) and Booking API are used by Viator to verify the availability. reserve inventory and create and confirm a booking in real time.

Amend a booking

Booking amendments utilize the Booking Amendment API. Booking amendments are triggered only for previously confirmed bookings.

Cancel a booking

Booking cancellations utilize the Booking Cancellation API. Booking cancellations are only ever triggered for previously confirmed bookings.

The Viator APIs support both RESTful (v1.0 and above) architecture and the SOAP protocol (v1.0 only).

• The Simple Object Access Protocol (SOAP), is a protocol specification for exchanging structured information in the implementation of web services in computer networks. It relies on XML information set for its message format, and usually relies on other application Layer protocols, most notably Hypertext Transfer Protocol (HTTP), for message negotiation and transmission.
• A RESTful web API (also called a RESTful web service) is a web API implemented using HTTP and REST principles. Representational state transfer (REST) is a style of software architecture for distributed systems such as the World Wide Web. REST has emerged as a predominant web API design model. The REST architectural style was developed by W3C Technical Architecture Group (TAG) in parallel with HTTP/1.1, based on the existing design of HTTP/1.0.

Both XML (v1.0 only) and JSON (v1.0 and above) formats are supported.

• JSON (JavaScript Object Notation), is a text-based open standard designed for human-readable data interchange. It is derived from the JavaScript scripting language for representing simple data structures and associative arrays, called objects. Despite its relationship to JavaScript, it is language-independent, with parsers available for many languages.
• XML (eXtensible Markup Language) is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. It is defined in the XML 1.0 Specification produced by the W3C, and several other related specifications, all gratis open standards.

Viator-built services consist of both RESTful (v1.0 and above) and SOAP (v1.0 only) web end-points.

All RESTful APIs use POST methods only, GET, DELETE, PUT, etc. methods are not supported. The message body of the POST request/response will include the payload described in this document.

The Viator APIs are designed to allow secure data transmission between suppliers and Viator. All APIs will use the Hypertext Transfer Protocol Secure (HTTPS). HTTPS provides authentication between the supplier's and Viator's systems, which protects against man-in-the-middle attacks. Additionally, it provides bidirectional encryption of communications which protects against eavesdropping and tampering with and/or forging the contents of the communication.

Authentication is further enhanced by the use of API keys, which are supplied within the payload (v1.0) or the header (v2.0) of each request. API keys are used to track and control how the API is being used, for example to prevent malicious use or abuse of the API. The API name acts as both a unique identifier and a secret token for authentication.

To prevent excessive load on Viator systems, a rate limit of 80 requests per (rolling) 15 second time window is applied .

Request rates exceeding this limit will result in a HTTP 429 (Too Many Requests) status code being returned. In order to avoid running-up against the rate limits, insert a delay of 2s if you receive a HTTP 429 status code.

Configurations must be determined and applied to both Viator and reservation systems to enable communication via the APIs. The following configuration items must be determined during the project initiation phase:

• Integration capabilities - provided by the reservation system, these are the APIs support by the reservation system (including mandatory API's).
• Reservation system endpoints - provided by the reservation system for each of the services supported.
• Data interchange format - provided by the reservation system, it is the format (JSON or XML) that will be used in all API calls. Applicable to v1.0 only. For v2.0 API's only JSON is supported.
• Max. number of availability days - provided by the reservation system, this is the maximum number of days for which the reseservation system will provide availability. Note: minimum: 365 days; maximum: 568 days.
• Supplier ID - provided by Viator in preparation for testing, the SupplierId uniquely identifies an operator in Viator systems
• Reseller ID - provided by Viator (for v1.0 APIs only) in preparation for testing.
• API key - provided by Viator in preparation for testing and Go Live. the API key is used for authenticatication
• Parameter name / parameter value - (optional) key / value sets used only when deemed necessary by the reservation system and Viator to uniquely identify a product variant.- Note: These values are defined by reservation systems as agreed to with Viator during Specification Review and Data Mapping.

Viator systems will make API requests to the reservation systems using the reservation systems product identifiers. The reservation system product identifiers are typically provided to Viator via the Tour List API). These are mapped to Viator products so that subsequent transactions utilize the reservation system product identifiers.

The API supports multiple fields that can be used to identify products and product options (aka product variants), i.e., a product option typically has either different pricing or inventory levels from other options of the same product.

In the APIs the following fields can be used as identifiers of products and/or product options. The supplier determines which of the below fields it needs to use to correctly interpret what product or product option an API request is for.

• SupplierProductCode – this is the only mandatory product identification field in Viator APIs. It is meant to be used for a code (key) that uniquely identifies a product.
  • Note: this field has a maximum length of 50 characters or less and must not include the pipe (|) character; product codes longer than this will fail.
• SupplierOptionCode – this field is optional. It is used when a product has multiple options, it identifies an option (or a variant) of the product.
• Name/Value - a max of four key/value pairs can optionally be used in conjunction with the SupplierOptionCode to uniquely identify a product variant. These appear under the Option element in the APIs. Similar to SupplierOptionCode they can be used to identify an option.
• productOptionId - this field has been introduced with v2.0 and is applicable only to v2.0 APIs. It is a singled identifier for the product variant. It is a single identifier that represents the existing v1.0 product option identifier concatenated key (i.e. it represents the combination of SupplierOptionCode and Name/Value pairs). This identifier will in the future replace the SupplierOptionCode and Name/Value fields.

Viator currently only supports a limited group of pricing rates (aka. age bands): Adult, Child, Youth, Infant and Senior. Reservation Systems and operators may support other pricing rates.

We recommend the following mapping of various pricing rates to Viator supported options.

Reservation System Price Rates	Viator Price Rates (Age Bands)
Adult	Adult
Child	Child
Youth	Youth
Infant	Infant
Senior	Senior
Concession	Senior
Veteran	Senior
Pensioner	Senior
Student	Youth
Teenager	Youth
Toddler	Infant
Baby	Infant
Everyone	Adult
Other	Adult
Group or Family Price	Not Supported

In v2.0 APIs Viator introduced the concept of unit pricing. For products priced in this manner the following is recommended:

Reservation System Price Rates	Viator Price Rates (Age Bands)
Car	Unit
Boat	Unit
Vehicle	Unit
Group	Unit

The booking cut-off value is a time, prior to a sellable item's start time, after which booking may no longer be accepted by the reservaon system; for example, a particular tour might not accept bookings if it is less than 24 hours before the start time.

For connected products, this value is provided to Viator via the bookingCutoff element of the Availability and pricing API responses.

BookingCutoff Usage

The bookingCutoff will be used to prevent bookings from take place after the time specificed in the bookingCutoff. It is also used to inform customers how long they have left before a booking cut-off restriction prevents them from booking. This aims to both drive customers to make a purchase and improve the customer experience by minimizing unexpected booking failures.

Note: Viator does not prevent customers from making a booking unless:

• The AvailabilityStatus.Status is set to UNAVAILABLE with an AvailabilityStatus.UnavailabilityReason of PAST_CUTOFF_DATE (v1.0 APIs only)
• The status is set to UNAVAILABLE and the unavailableReason is set to PAST_BOOKING_CUTOFF (v2.0 APIs only)

The UNAVAILABLE status is used by Viator as a beacon during its automated periodic checking process. An item will become unavailable as soon as this signal is received.

The following is applicable to legacy v1.0 Availability and Pricing APIs only. The Capacity element allows simple capacity management for a product. In this context, 'capacity' refers to the total number of remaining inventory for Viator to book and is returned by the reservation system in the response to an availability request.

There are two ways to use this system in the case where capacity is a matter of concern (i.e. limited spaces are available for the tour). The third scenario is when capacity is irrelevant to the tour or activity in question; i.e. when there is unlimited capacity for a free-sale product.

1. Allow all agebands to draw from the available remaining places; e.g., when all passengers are considered to be in the "Adult" ageband.

Example: There are 10 remaining places from which all agebands consume:

<TourAvailability>
    ...
    ...
    <Capacity>
         <Simple>
              <Remaining>10</Remaining>
         </Simple>
   </Capacity>
   ...
</TourAvailability>

{
    ...
    ...
    "TourAvailability": [
      {
        "Capacity": {
            "Simple": {
                "Remaining": 10
            }
        }
      }
    ]
}

2. Allow only specific agebands to consume the remaining capacity; e.g., so that infants do not consume the remaining spaces

Example: Only "ADULT" and "YOUTH" agebands consume from the remaining places; infants are not included in the capacity count:

<TourAvailability>
    ...
    ...
    <Capacity>
         <Simple>
              <Remaining>10</Remaining>
              <ConsumedBy>ADULT</ConsumedBy>
              <ConsumedBy>YOUTH</ConsumedBy>
         </Simple>
   </Capacity>
   ...
</TourAvailability>

{
    ...
    ...
    "TourAvailability": [
      {
        "Capacity": {
            "Simple": {
                "Remaining": 10,
                "ConsumedBy": [
                    "ADULT",
                    "YOUTH"
                ]
            }
        }
      }
    ]
}

3. This is a free-sale/unlimited capacity tour

Example: Tickets to an amusement park. In this case, simply return a high number that it would be very unlikely or impossible to consume.

<TourAvailability>
    ...
    ...
    <Capacity>
         <Simple>
              <Remaining>1000</Remaining>
         </Simple>
   </Capacity>
   ...
</TourAvailability>

{
    ...
    ...
    "TourAvailability": [
      {
        "Capacity": {
            "Simple": {
                "Remaining": 1000
            }
        }
      }
    ]
}

Considerations when using the Capacity element

Capacity is limited, but only for a non-Adult ageband

For example, a children's-only go-kart activity, where it is children that occupy the limited number of seats in the karts, and adults are only present as spectators (and therefore the adult capacity can be considered unlimited).

In such a case, use the primary ageband for the activity – in this case, "CHILD":

<TourAvailability>
    ...
    ...
    <Capacity>
         <Simple>
              <Remaining>10</Remaining>
              <ConsumedBy>CHILD</ConsumedBy>
         </Simple>
   </Capacity>
   ...
</TourAvailability>

{
    ...
    ...
    "TourAvailability": [
      {
        "Capacity": {
            "Simple": {
                "Remaining": 10,
                "ConsumedBy": [
                    "CHILD"
                ]
            }
        }
      }
    ]
}

The reported capacity may only be an approximation in some cases

If a product has complex rules governing the passenger mix, Simple may only provide an approximation of the available capacity.

For example, consider a speed-boat ride where both adults and children occupy the same seats, but children require special restraints, which are limited. In this case, you should use the overall number of seats and specify 'Adult', 'Senior' and 'Child' using the ConsumedBy element. E.g.:

<TourAvailability>
    ...
    ...
    <Capacity>
         <Simple>
              <Remaining>5</Remaining>
              <ConsumedBy>ADULT</ConsumedBy>
              <ConsumedBy>SENIOR</ConsumedBy>
              <ConsumedBy>CHILD</ConsumedBy>
         </Simple>
   </Capacity>
   ...
</TourAvailability>

{
    ...
    ...
    "TourAvailability": [
      {
        "Capacity": {
            "Simple": {
                "Remaining": 10,
                "ConsumedBy": [
                    "ADULT",
                    "SENIOR",
                    "CHILD"
                ]
            }
        }
      }
    ]
}

This will be used by Viator to limit the total number of passengers that can book, e.g., if the passenger capacity is five, a group of six will be automatically refused, but a group of five might still be unable to book if the passenger mix cannot be accommodated due to limited child restraints.

The Beta section introduces new endpoint versions, offering our Beta partners early access to features for review and prototyping. Developers can use these Beta endpoints to speed up adoption and to provide feedback on API functionality and usability.

Whilst intended for production release, these APIs may undergo modifications during the Beta phase if critical issues are identified. Developers may need to adjust their implementations if a change is deemed necessary. All changes to Beta endpoints will be communicated to Beta partners.

Please email supplierAPI@viator.com to provide feedback.

This section describes all of the possible services, some of which are mandatory, that reservation systems can developed to integrate with Viator.

All API requests made by Viator to the reservation system are specified. The reservation system will response to Viator requests in a synchronous manner, responding as per specification. Both request and response formats are described in detail in subsequent sections of this document.

This section describes the Viator built API(s) available for reservation system consumption.

Note: For these APIs, the request is sent to Viator and the response is received from Viator.

• XML Schema Definition (XSD)
• Web Services Description Language (WSDL) for Supplier Built Services (Booking, Availability, Amendment, etc.)
• Web Services Description Language (WSDL) for Viator Built Services (Booking Redemption, Availability Notification, etc.)

The Contract Testing Tool is a self-service tool provided by Viator to assist reservation systems testing and validating their API integration for v2 APIs (v1 APIs are not supported).

This tool is a web application (meant to be executed locally) that includes a complete suite of contract tests that enables developers to test their endpoints. Endpoints need not be exposed externally for tests to run.

Configuration and Execution

The first step is to make sure you have Docker desktop installed and running.

Then, get the values of your API Key and SupplierID (which should be provided by Viator after the Kick-off Meeting) and set them as environment variables as follows:

export API_KEY=<your-api-key>
export SUPPLIER_ID=<your-supplier-id (e.g, 123456789)>

Finally, run the Contract Testing Tool using the following commands:

docker pull public.ecr.aws/viator/cica:latest
docker run -it --rm --name viator-contract-testing -p 5173:5173 -p 8989:8989 \
  -e API_KEY=$API_KEY -e SUPPLIER_ID=$SUPPLIER_ID \
  --add-host=host.docker.internal:host-gateway \
  public.ecr.aws/viator/cica:latest

Usage

Access the application at http://localhost:5173.

In the left panel, you will find a list of capabilities (e.g., AVAILABILITY). After selecting a capability, the main page will present a set of scenarios which are tests that can be executed.

To execute a scenario the user must:

• Expand the scenario by clicking on it
• Fill the Capability Endpoint or the Global Endpoint (when the same endpoint serves all the capabilities) with the full URL of the API endpoint being tested.
  • Note: if you are running your api locally you must insert http://host.docker.internal:<port>/your-api-path instead of http://localhost:<port>/your-api-path as the contract testing tool is running on docker.
• Fill the form inputs required by the scenario being tested.
• Click on Execute Test and view the Test Report.

Q: If we use the API, how do suppliers control the inventory available to Viator?

A: Suppliers retain control of the inventory they expose to Viator. The API simply replaces the manual work of inserting bookings into your system and providing blockout information to Viator. Suppliers still control the inventory that they want to sell to Viator.

---

Q: Does the API contain pricing and payment information?

A: Viator is the credit card merchant of record for all transactions – no payment information needs to be processed by the supplier or supplier’s system. We do not send credit card information via the API. The supplier net rate and pricing information is stored on Viator's side and can be updated via the Batch Availability and Pricing API; or, through the regular process of updating the Schedule and prices tab in the Supplier Extranet.

---

Q: How can non-Viator suppliers use the Viator API?

A: If you have suppliers that are not working with Viator today, please refer them to the Supplier Sign Up link on Viator.com. The Viator API will only work with current Viator suppliers, but we are always looking for new and exciting products to offer.

---

Q: How do we map our internal product codes to Viator’s product codes?

A: At the commencement of the project, Viator will provide a list of the supplier's products and product options. Together, we can then define a mapping approach between Viator's and the supplier's systems. This is a critical part of the project, as we need to ensure that the mapping values correctly identify the variables that have an inventory concern.

Mapping is carried out either by the supplier or the administrator of the reservation system. Viator's mapping feature is available via the Supplier Extranet. The mapping wizard utilizes data from the Tour List and Batch Availability endpoints.

Common questions regarding the booking information that is sent:

Q: Will I receive the customers direct email address?

No, due to company policy, we will never provide the customer's real email address. However, you have the option to have the same obfuscated email address that is currently hidden behind our “Contact Customer” button in the management center to be sent to you.

This is an optional feature that your developers can accommodate, and it will place the obfuscated email address directly into your reservation system so your reservations team does not need to log into our management center to send the customer an email.

The added benefit is that communication between you and the customer is logged in the booking history notes, should you need it for future reference. This email address is valid for 30 days after the travel date.

Q: Will I receive the customers direct phone number?

Yes, if the customer completes the phone number field on our checkout page, tit will be included in the booking information. Note, however, that not all partners support this field.

Q: Will I receive the customer's hotel information?

Yes, if you currently have the hotel pick up box activated for your products, the customer will be able to select their hotel from the drop down menu and this information will be sent to you in the “Pick up point” field.

If you are currently collecting this information from the special requirements field, the “Special Requirements” field will be populated with this information.

Q: Will I still receive the information that a customer enters during the booking process such as flight and cruise ship information?

Yes, this information is passed in the question and answer fields of the booking request.

Q: How to do I correctly handle the product's guide language when it is an inventory concern?

For operating languages with limited capacity, such as a Portuguese guided tour, it is essential to accurately return the product option in the Tour List API. This facilitates the mapping of the equivalent Viator product option to the operator's system, allowing for capacity verification during booking.

However, if the operator provides audio or written language guides without capacity limitations, including product options of language in the Tour List API is not necessary. The audio guide language chosen by the customer at checkout will be transmitted with the booking request.

Q: When should I use SupplierOptionCode and how does this affect the product set-up?

The SupplierOptionCode serves as a unique identifier for various product options or variants. It can be paired with Name/value pairs to specify different versions of a product. For instance, a dinner cruise might offer "window seat" and "best available" as distinct options.

Q: Should I support barcode numbers or pass-through tickets? The answer is based on how operators expect customers to check-in to the tour or activity. There are two possible options:

Using Viator standard vouchers. These can include a per-traveller barcode (TravellerBarcode) or a per-booking barcode (TourBarcode) returned from the operator's reservation system in the Booking API. The use of per-traveler or per-booking is confirmed by product in Viator's supply center. Using the operator’s reservation system ticket, returned in the Booking API TourTicket. With this option, the Viator ticket will be suppressed, and customers will receive the provided ticket. This option cannot be controlled via Viators supply center; please contact us if this is desired.

Q: What is the relationship between 'start times' and the API?

The following is applicable to legacy v1.0 Availability and Pricing APIs only.

Our management center provides you with different time options to accommodate different product types, such as opening hours and start times.

However, for the API connection, if the starting time that the customer selects is important for you to know in the booking details; or, if there is an inventory concern, you must return the TourDepartureTime tag as a mapping value and do not include the start time as part of the SupplierOptionCode.

In the management center, you will then be restricted to using only the 'start times' option. The reason for this that the starting time information in the management center synchronizes with the information in the TourDepartureTime field, and this information is then presented to the customer on our site.

Example of start times syncing on the product connection tab:

This appears to the customer as:

All starting times listed on the product connection page that have been synchronized will be displayed to the customer. If a particular starting time is not available, that time will appear crossed-out.

The benefits of using the TourDepartureTime tag include:

Eliminating the need to identify each start time as a product option

• This saves your team time by obviating the need to create new product options in the management center. This also saves the SupplierOptionCode for when it is genuinely required to differentiate between the product options.

• The availability for each individual time can be checked, and the customer will be able to select their preferred time during the booking process instead of contacting you directly to arrange a time post-booking (but prior to travel).

Note: If there are any changes made to the Time option in the management center; for example, changing from start times to opening hours, this will break the API connection unless the TourDepartureTime is also removed from the API response.

Please email us on supplierAPI@viator.com with any questions or suggestions. A ticket will be logged with the API integrations team who will respond as quickly as possible.

The following is applicable to legacy v1.0 APIs only.

Code	Meaning
TGDS0001	Malformed request
TGDS0002	Authentication error
TGDS0003	Invalid connector
TGDS0004	Request timed out
TGDS0005	Service not available
TGDS0006	Unknown internal error
TGDS0007	Unsupported api request
TGDS0008	Unsupported supplier API
TGDS0009	Unsupported protocol
TGDS0010	Malformed URL
TGDS0011	Invalid supplier
TGDS0012	Invalid product
TGDS0013	Invalid product option code
TGDS0014	Connection timed out
TGDS0015	Invalid reseller ID
TGDS0016	Inactive account
TGDS0017	Inactive supplier
TGDS0018	Inactive reseller
TGDS0019	Unsupported reseller API
TGDS0020	Field validation error
TGDS0021	XML schema validation error
TGDS0022	Missing API parameter key/value
TGDS0023	Invalid data; i.e., data is in incorrect format, non-parsable or otherwise invalid
TGDS0024	Supplier specific errors
TGDS0025	Unsupported request for endpoint
TGDS0026	Invalid request
TGDS0027	Availability data not available for the specified date range
TGDS0028	Data not available
TGDS0029	Malformed response message
TGDS0030	Malformed request message
TGDS0031	Unhandled internal error in supplier system
TGDS0032	Event has been removed or otherwise became unavailable for booking
TGDS0033	Invalid pickup option
TGDS0034	Supplier system has limitations, which prevents this operation from succeeding
TGDS0035	Unknown transaction status
TGDS0036	Event availability has been changed so that it is impossible to book for this traveler mix
TGDS0037	Connection closed by reseller before response could be dispatched