API docs by Redocly

Viator Supplier API (1.0)

Download OpenAPI specification:Download

Home

Welcome to the Viator Supplier API Tools site. This site will help you develop APIs that will allow Viator to request your tour inventory availability in real time and automatically lodge bookings with your reservation system.

Note: Our supplier API and respective documentation is intended for use by current Viator suppliers and their IT services providers. You must be registered as a current Viator supplier before any development commences. For more information on joining Viator, please visit our new supplier sign-up page.

To get started, please review the Connectivity overview, the API overview, and the implementation approach.

We've provided a list of frequently asked questions and when you need help or want to schedule integration testing, please contact us here.

It's our goal to achieve real-time systems connectivity with as many suppliers as possible, so please don't hesitate to reach out for assistance. We look forward to working with our suppliers and their IT services providers to provide the best experience possible for our shared travellers.

Thanks for your support,

The Viator Supplier API team.

Connectivity overview

This section provides information for project participants that are focused on the operations side of the business to understand the information the API connection will provide and how that relates to procedures normally carried out using the management center.

The API comprises three sections:

  • Catalog operations
  • Availability and pricing
  • Booking operations

Catalog operations APIs

Tour list API

This API is used to retrieve the product codes (mapping identifiers) that identify your products on your system. This ensures that our product codes align with the correct product on your side and that any additional information - such as tour guide languages and departure times - are also synchronized.

You will see the information from this API when you click the Connect button in the Product Connection tab in the management center, and then selecting “Select it from their list of live products”.

Figure 1

The tour list will present all of the products that are available.

Once you select a product, our systems reach out to your batch availability API endpoint for at least one available date. This is to ensure that the product does appear in the batch availability response; and that, by entering the mapping, we will not inadvertently block a product from sale. Once you click “Save”, the product will be live and any new bookings will be sent directly to your system.

You can revisit this page at any time to check if the mapping values are correct; or, to re-map a product if you make any changes to it on your reservation system.

If a product does not appear in this list, please ask your development team if the product has been added to the tour list and batch availability responses.

Availability and pricing APIs

The availability and pricing APIs include:

  • Batch availability
  • Real-time availability (with optional real time pricing)
  • Batch pricing (requires approval)

These three APIs help to reduce the manual maintenance work that is currently undertaken in the management center. It is mandatory to support the batch availability and real-time availability APIs.

1. Batch availability API

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.

2. Real-time availability and pricing API

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.

3. Batch pricing API

The batch pricing API is currently in beta. If you are interested in supporting this API, please initiate a discussion with your API account manager before starting development so that we can assess whether your system can support it.

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.

Figure 1

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.

Batch pricing and the minimum margin

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:

Pricing in our APIs is always based on the per-person rate, and this includes the batch pricing API. At present, we are unable to support tiered pricing or per-unit pricing (e.g., per car, boat etc.).

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

Booking operations APIs

The booking operations APIs available to you are:

  • Booking
  • Booking cancellation
  • Booking amendment

These three APIs ensure that bookings are processed correctly according to your system's protocols. Supporting these APIs, except for the booking amendment API, is mandatory.

Booking API

This is the easiest API to understand, as it takes place at the completion of the booking process. This is when the booking is sent to your system. Once the API connection is live, you will no longer receive booking notifications by email unless the fallback process is activated.

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.

Booking Cancellation API

When a customer submits a cancellation request, this can be automatically sent to your system as an alternative to having your reservations team processing cancellation requests by email. This can reduce your administrative burden, ensures your availability is up to date, and provides you with an opportunity to re-sell the tickets.

Booking Amendment

Booking amendments are for any changes that need to be made to the booking details post-booking, but pre-travel. This allows the customer to hold the same booking number for the duration of the booking.

The changes that can be made include:

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

This API can update the booking details or notify your team of a change depending upon how you have implemented it on your side.

Considerations for a smooth connection

The relationship between 'start times' and the API

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

Figure 1

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:

Figure 1

This appears to the customer as:

Figure 1

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.

How to correctly handle the product's guide language when it is an inventory concern

If we need to check the availability for a specific operating language, then it is recommended to have 'language' as its own key/value pair. At this time, the guide language is still supported with product options on the schedule and prices tab; and, for this reason, we need to connect (map) each product option to the right language.

If you offer audio language guides and there is no inventory concern, then language is not required to be a mapping value. The audio guide language that the customer selects on the checkout page will be sent to you in the booking request.

When to use SupplierOptionCode and how this affects the product set-up

The SupplierOptionCode is used to differentiate between product options. For example, a dinner cruise may have two options: 'window seat' and 'best available'. The SupplierOptionCode is an easy way to identify the option being booked.

Figure 1

Should I support barcode numbers or pass-through tickets?

To decide upon the best option, we suggest considering how the customer will check-in or participate in the tour or activity.

For example, if the customer is happy to present our standard voucher (with the addition of the barcode number from your system) this can be achieved with either a per-traveller barcode (TravellerBarcode) or a per-booking barcode (TourBarcode). You can control the barcode type and the redemption information on the Tickets tab in the management center.

If the Tickets tab does not provide enough detail for the customer, you should consider supporting the TourTicket option. This option allows you to respond to our booking request with a URL to the PDF that the customer needs to present. The workflow is slightly different in this case, as the Viator / Tripadvisor ticket will be suppressed, and the customer will only see and receive your PDF. This option can not be controlled in the management center – please ask us to set this up for you if you wish to support this workflow.

Testing and how to go live

Once all of the considerations listed above have been addressed, development can proceed, and all APIs will be tested. We will check with you that any test bookings are received correctly and cancelled or amended as applicable. Once we all agree that testing is working successfully, then we can go live.

This process will include changing the API key used in testing to a production API key and selecting a pilot product. We recommend a product that will sell within a few days, but not your best-selling product.

If you are migrating from one system to another, products may need to be remapped, and this should be considered before moving into production.

The fallback process: what happens when the API fails to connect?

If an error is received; or, we are unable to validate your response, we will apply the booking process that appears in the management center.

Figure 1

This will allow customers to proceed with their bookings; therefore, you won’t lose any.

When errors do occur, API calls are still made; i.e., we will still make an availability call and a booking call. However, the responses to these calls will be what determines if the booking is made via the API or sent to you by email. Once the error is resolved, the API transactions will recommence.

Supplier built APIs

These are the functions that are provided by the supplier's tour reservation system.

  • Verify availability - This can be real-time availability which is checked during the booking process to determine if the tour is available. It may also be to determine availability for a date range for the purposes of determining blocked out dates (dates when tour is not available). Viator also supports batch availability calls that allow for the retrieval of availability from the Supplier in bulk - this call was designed to determine blocked out dates from suppliers with sizable product catalogs ( Batch Availability API). Viator also provides the capability for availability notifications from Suppliers which enables suppliers to proactively notify Viator of changes to availability (Availability Notification API) - this can be extremely useful for the Supplier as it enables it to make previously blocked out dates available.
  • Create Booking - Takes place once the booking is confirmed in Viator systems.
  • Amend Booking - Takes place when an amendment to an existing, confirmed booking is made in Viator systems.
  • Cancel Booking - Takes place when a cancellation to an existing, confirmed booking is made in Viator systems.
  • Tour List - Called by Viator to retrieve a list of products from the supplier. This will be used during the creation of a product in Viator systems.

Business processes supported by the Viator Supplier API

The Viator APIs have been designed to support several business processes, from initial product creation through to voucher redemption. Each of the business processes are supported by the API's called from either Viator or the Supplier.

  • Product (tour) validation/information within the Viator booking system - supported by the Tour List API.
  • Determining the availability of a tour - supported by the Availability, Batch Availability and Availability Notification 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.

API overview

The Viator API is a strategic advantage for Suppliers, system providers and Viator: the more robust our inventory, the wider the distribution and sales potential of the supplier’s products.

The two key API functions are for availability checking and inserting bookings into your system. Integration with our API will eliminate the current hassles of reservations teams having to manually manage block-outs, confirm on request bookings and manually re-key bookings into their reservations system. Integration with our API will also allow Viator to book your products closer to the departure time to increase last minute bookings and revenue. The other API functions such as amend, cancel and redeem are optional. These can be managed via the Viator Supplier Extranet if you choose to not implement them or add support at a later date.

There are several additional immediate benefits of connecting to Viator’s API. We will include your confirmation or order number on our vouchers which will simplify the reconciliation of our travelers with your system. We can also include your confirmation number on our voucher or smartphone as a barcode if you support scanners for entry to your activity. Because we will have to match our tour and option codes to yours, we can also include your tour and option codes on the vouchers, making it easier for your team to recognize the exact product our consumer purchased.

If you have developed a custom reservations system for your business you can share this website and documentation with your software developer to review. They can estimate the effort required to implement the API for your business

Feel free to email our support desk if you want to set up a call to discuss the project.

We look forward to you working with us to achieve system connectivity very soon, and please do not hesitate to let us know if you need assistance moving forward with this exciting project.

Introduction

This section provides technical details about the APIs that enable connectivity between Viator and its suppliers, outlining the business processes supported by the API and details the specifications of the APIs, both Viator and supplier side, security, communication, testing and implementation steps.

To achieve true integration, development effort is required from both Viator and its suppliers. The Viator supplier API is therefore made up of APIs that fit into two groups:

  • Supplier-built APIs - Those APIs (services) developed by the supplier and consumed by Viator.
  • Viator-built APIs - Those APIs (services) developed by Viator and consumed by the supplier.

This document provides detailed specifications for both sets of APIs in order to establish a standard methodology for suppliers to connect with Viator systems in the shortest possible time. Having a standard method of connectivity means that adapters to receive information from the supplier are already built and tested which leads to a faster implementation and reduced errors.

The following sections assume the reader has a technical background and is familiar with XML, JSON, Webservices, APIs and similar technologies.

Supplier-built APIs

These are the functions that are provided by the supplier's tour reservation system:

  • Verify availability - This can be real-time availability which is checked during the booking process to determine if the tour is available. It may also be to determine availability for a date range for the purposes of determining blocked out dates (dates when tour is not available). Viator also supports batch availability calls that allow for the retrieval of availability from the Supplier in bulk - this call was designed to determine blocked out dates from suppliers with sizable product catalogs ( Batch Availability API). Viator also provides the capability for availability notifications from Suppliers which enables suppliers to proactively notify Viator of changes to availability (Availability Notification API) - this can be extremely useful for the Supplier as it enables it to make previously blocked out dates available.
  • Create Booking - Takes place once the booking is confirmed in Viator systems.
  • Amend Booking - Takes place when an amendment to an existing, confirmed booking is made in Viator systems.
  • Cancel Booking - Takes place when a cancellation to an existing, confirmed booking is made in Viator systems.
  • Tour List - Called by Viator to retrieve a list of products from the supplier. This will be used during the creation of a product in Viator systems.

Supported Business processes

The Viator APIs have been designed to support a number of business processes, from initial product creation through to voucher redemption. Each of the business processes are supported by the APIs called from either Viator or the Supplier.

The following sections include the process work flows that the Viator Supplier APIs support. Both Viator and supplier-built APIs are described.

Product creation

The process of creating products on Viator's systems utilizes the tour list API (when supported by the supplier) to retrieve product details from the supplier. The most important (and connectivity critical) information returned by the API are the supplier tour and tour option codes which will be used in all booking related communications with suppliers. These codes are unique values that represent the supplier tours and tour options.

product creation workflow

Figure – Product creation workflow

Create a booking

During the booking process the availability API and booking API are used by Viator Systems to verify the availability of tours and, ultimately, create and confirm the booking with the supplier in real time. Availability is confirmed throughout the process to reduce the chance of rejected bookings.

create booking workflow

Figure - Create booking workflow

Amend a booking

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

amend booking workflow

Figure – Amend booking workflow

Cancel a booking

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

cancel booking workflow

Figure - Cancel booking workflow

Webservice architecture

The Viator supplier APIs support both RESTful architecture and SOAP protocol.

  • 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 and JSON data 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.

Environments

Viator-built services consist of both RESTful and SOAP web end-points. Details about test and production environments are listed below.

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 XML/JSON payload described in this document. Content-Type header will be application/xml for both request and response.

Note: End points for supplier-built APIs must be provided to the Viator technical team for both test and production environments.

Security

The Viator supplier 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 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. Both Viator and suppliers will generate API keys to be used with every request to and from, this allows for a higher degree of security in the transmission of information between systems.

Rate limiting

To prevent excessive load on our systems, we limit the rate at which API calls can be made to 80 requests per 15 second time window (rolling).

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.

Implementation approach

  1. Project Kick-off Meeting - Scheduled by Viator technical resources after initial contact with the Supplier. The following should be discussed:
    1. Determine Project Team Members
    2. Scope of Implementation (capabilities to be supported)
    3. Agree on Preliminary Time Lines
    4. Determine Project Team Communication Method
  2. Specification Review and Data Mapping - Supplier will review the API specifications in preparation for development. This steps includes:
    1. Review of API specifications
    2. Mapping API fields to Supplier system fields.
  3. Specification Clarifications - Supplier will raise questions / clarifications with Viator. This can be done via email (email address listed under Support section of this document) or via phone.
    1. Questions / Answers (email support)
  4. API Development - Supplier will commence development of the necessary APIs. This includes:
    1. Development of Supplier side APIs
    2. Development of Viator side API calls (if supported)
    3. Testing (internally)
  5. Test Environment Configuration - Viator will configure the Test environment to enable testing with the Supplier. This step includes:
    1. API Configuration (as listed under section Supplier API Configuration)
    2. Product Configuration will require product mapping between Supplier and Viator.
  6. Integration Testing Kick-off - Supplier and Viator will conduct various tests to ensure APIs are working as expected. This step includes:
    1. Determining the necessary test cases based on the APIs supported by the Supplier.
    2. Agreeing on a Test Schedule.
    3. Test Execution and reporting (typically over email)
  7. Production Environment Configuration - Viator will configure the Production environment. This step includes:
    1. API Configuration (as listed under section Supplier API Configuration)
    2. Product Configuration will require product mapping between Supplier and Viator.
  8. Go Live - Viator and Supplier prepare for Go Live. This includes: Schedule Go Live Date
    1. "Switch On" the API
    2. Configure a small number of products to use the API
    3. Transaction Monitoring and Issue Resolution
    4. Roll out all applicable products to use the API
    5. Sign Off by Supplier and Viator

Supplier-built APIs

This section describes the APIs that must be developed on the supplier's system to enable automated communications with Viator systems. The business processes supported by these APIs are:

  • Verify availability - This can be real-time availability which is checked during the booking process to determine if the tour is available. It may also be to determine availability for a date range for the purposes of determining blocked out dates (dates when tour is not available). Viator also supports batch availability calls that allow for the retrieval of availability from the supplier in bulk - this call was designed to determine blocked out dates from suppliers with sizable product catalogs (batch availability API).
  • Create booking - Takes place once the booking is confirmed in Viator systems
  • Amend booking - Takes place when an amendment to an existing, confirmed booking is made in Viator systems
  • Cancel booking - Takes place when a cancellation to an existing, confirmed booking is made in Viator systems
  • Tour list - Called by Viator to retrieve a list of products from the supplier. This will be used during the creation of a product in Viator systems

For integration with Viator the following APIs must be supported:

All other APIs are optional but the more APIs that are supported, the more processes (amendment, cancellation, etc.) are automated increasing the benefits for all involved.

All API calls made by Viator systems to the supplier will include the necessary information to be used by the supplier system to understand the request. The supplier system will response to the request in a synchronous manner, returning the necessary information per specification. Both request and response formats are described in detail in subsequent sections of this document.

Supplier API Configuration

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

  • Supplier capabilities - provided by the supplier during project initiation, these are the APIs that the supplier will support
  • Supplier connection points - provided by the supplier for each of the supported APIs in preparation for testing and implementation
  • Data interchange format - provided by the supplier during project initiation, it is the format (JSON or XML) that will be used in all API calls
  • Max. number of availability days - provided by the supplier during project initiation, this is the maximum number of days for which the supplier will provide availability.
    • Note: minimum: 365 days; maximum: 568 days.
  • Supplier ID - provided by Viator in preparation for testing, the SupplierId uniquely identifies the supplier in Viator systems
  • Reseller ID - provided by Viator in preparation for testing, the ResellerId uniquely identifies Viator in the supplier systems
  • API key - provided by Viator in preparation for testing and implementation, the API key will authenticate Viator or the supplier (depending on the API call)
  • Parameter name / parameter value - (optional) key / value sets used only when deemed necessary by supplier and Viator to fulfill unique circumstances.
    • Note: These values are agreed upon during project initiation.

Product mapping

Viator systems will send API requests to the supplier that include the supplier's product codes. The suppliers product codes are provided to Viator by the supplier (typically via the tour list API) and are mapped to Viator products. Once mapped, transactions that Viator systems sends to the supplier's system are sent using the suppliers product codes.

The API supports multiple fields that can be used to identify a product or a product option (or variant), i.e., an option may be a different departure time, a tour that includes different options, a tour that is run in a different language, etc. Options typically have 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.
  • Option 1 to 4 – these four key/value pair fields are optional, they appear under the Option element in the APIs. Similar to SupplierOptionCode they can be used to identify an option (a good example may be DepartureTime). These fields can be used in combination with SupplierOptionCode or individually.

Suggested Price Option Mapping

Viator currently only supports a limited group of pricing options (age bands): Adult, Child, Youth, Infant and Senior, although Reservation Systems and Suppliers may support other pricing categories.

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

External Price Options / Age Bands Viator Price Options / 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

BookingCutoff and Capacity elements

How to use the BookingCutoff element

What is the booking cut-off?

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

This value is provided to Viator in two ways:

  1. By the supplier's system in the contents of the BookingCutoff element of the Availability response
  2. By taking the value entered by the supplier in the Booking Details section in the management center for that product (if the previous method is unavailable)

Note: The value provided in the BookingCutoff element takes precedence over the value entered by the supplier in the management center.

How does Viator use the booking cut-off value?

The booking cut-off value will be used to inform customers how long they have left before a booking cut-off restriction might prevent them from booking the item. This will improve the customer experience by minimizing unexpected booking failures.

Please note that the value should be considered advisory, as Viator does not prevent customers from attempting to make a booking – even if it is past the booking cut-off time – unless we receive an AvailabilityStatus.Status of UNAVAILABLE and an AvailabilityStatus.UnavailabilityReason of PAST_CUTOFF_DATE. Only then will the item become unavailable for sale.

Therefore, if your system responds to the availability request with an AvailabilityStatus.Status of AVAILABLE, even if it is past the time stipulated in BookingCutoff.DateTime, we will continue to allow booking requests for this item to proceed.

The AvailabilityStatus.Status value is also used by Viator as a beacon during its automated periodic checking process. The item will be switched to an unavailable state as soon as this signal is received.

Example BookingCutoff value formats

<TourAvailability>
    <Date>2021-11-18</Date>
    <TourOptions/>
    <AvailabilityStatus>
        <Status>AVAILABLE</Status>
    </AvailabilityStatus>
    <BookingCutoff>
        <DateTime>2021-11-07T12:13:14+10:30</DateTime>
    </BookingCutoff>
</TourAvailability>
<TourAvailability>
    <Date>2021-11-19</Date>
    <TourOptions/>
    <AvailabilityStatus>
        <Status>AVAILABLE</Status>
    </AvailabilityStatus>
    <BookingCutoff>
        <ProductDateTime>2021-11-08T12:13:14</ProductDateTime>
    </BookingCutoff>
</TourAvailability>
<TourAvailability>
    <Date>2021-11-09</Date>
    <TourOptions/>
    <AvailabilityStatus>
        <Status>AVAILABLE</Status>
    </AvailabilityStatus>
    <BookingCutoff>
        <NotApplicable>true</NotApplicable>
    </BookingCutoff>
</TourAvailability>

How to use the Capacity element

The Capacity element allows simple capacity management for a product. In this context, 'capacity' refers to the total number of places remaining for Viator to book and is returned by your 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.

Tour list API

The tour list API enables suppliers to provide a list of available tours (and tour options). The tour list (product master) will include descriptive fields to enable Viator to map its products to the supplier's product list. Mapping will be based on tour codes and tour option codes - these uniquely identify each tour and tour option.

Request Body schema:
requestType
required
string

TourListRequest

required
object (TourListRequest)

Root element for Tour List Request

Responses

Response Schema:
responseType
required
string

TourListResponse

required
object (TourListResponse)

Root element for Tour List Response

Request samples

Content type
{
  • "requestType": "TourListRequest",
  • "data": {
    }
}

Response samples

Content type
{
  • "responseType": "TourListResponse",
  • "data": {
    }
}

Real-time Availability API

The Real-time Availability API is designed to allow Viator to instantly ascertain whether a specific tour provider has space for a certain number of passengers. This is accomplished by the API interacting directly with the supplier's reservation system in real time.

This API provides a versatile interface that enables suppliers to disclose availability data for a particular date or a range of dates for tours, both with and without additional options. Based on the suppliers' responses, Viator's systems will then permit (for available dates) or prohibit (for unavailable dates) customers from booking a tour.

Since this API checks availability directly from the supplier's system, we anticipate a decrease in booking rejections and a boost in last-minute reservations.

When the Availability API is utilized for a single date, its primary function is to verify real-time availability. This happens when a customer is booking a tour for a specified date and passenger count. If the supplier's response confirms availability, the customer will be able to finalize their booking. In order to minimize latency, Viator also performs periodic availability checking for single-dates, however it will not include any information about the traveler mix, as it is not related to any user activity.

In contrast, when the Availability API is employed with a date range, it's purposed to determine bulk future availability. This information is saved within Viator's systems, enabling the caching of availability data. This cached data proves essential under circumstances where the supplier's system can't be accessed for real-time availability checks (for instance, due to a communication line disruption).

Supporting the user workflow

As the customer progresses through their workflow, there are three different kinds of real-time availability request that will be requested, corresponding to the three stages in that workflow:

  1. The traveler selects a product and a date on which they would like to travel (as well as their desired traveler mix)
    • The request will include StartDate, SupplierProductCode and TravellerMix
    • The response should include all available TourOptions (which will allow the customer to pick from)
  2. The traveler selects a product option and adds the product with the selected product option to their shopping cart
    • The request will include StartDate, SupplierProductCode, TravellerMix and TourOptions
  3. The traveler proceeds to the checkout
    • The request will include StartDate, SupplierProductCode, TravellerMix, TourOptions and AvailabilityHold
Request Body schema:
requestType
required
string

AvailabilityRequest

required
object (AvailabilityRequest)

Root element for Real-time Availability Request

Responses

Response Schema:
responseType
required
string

AvailabilityResponse

required
object (AvailabilityResponse)

Root element for Real-time Availability Response

Request samples

Content type
Example
{
  • "requestType": "AvailabilityRequest",
  • "data": {
    }
}

Response samples

Content type
Example
{
  • "responseType": "AvailabilityResponse",
  • "data": {
    }
}

Batch Availability API

The Batch Availability API is designed to allow Viator to discern availability on a large scale, leveraging a push-based methodology to determine the status of supplier availability. This API facilitates suppliers in sharing availability information for all their products (including any associated product options) over a requested date range.

Upon receiving the suppliers' information, Viator's systems will be updated to either permit (for available dates) or prohibit (for unavailable dates) customers from booking a tour. By proactively informing Viator about their availability, suppliers have the control to set specific dates as either available or unavailable, in line with their system's capacity.

Since the suppliers actively push date availability changes to Viator's systems, a more seamless and efficient integration is achieved.

Request Body schema:
requestType
required
string

BatchAvailabilityRequest

required
object (BatchAvailabilityRequest)

Root element for Batch Availability Request

Responses

Response Schema:
responseType
required
string

BatchAvailabilityResponse

required
object (BatchAvailabilityResponse)

Root element for Batch Availability Response

Request samples

Content type
{
  • "requestType": "BatchAvailabilityRequest",
  • "data": {
    }
}

Response samples

Content type
Example
{
  • "responseType": "BatchAvailabilityResponse",
  • "data": {
    }
}

Batch Pricing API

Pricing is currently in beta. If you are interested in supporting this API, please inform your API account manager before starting development. We will then assess whether your system is able to support the current pricing model.

The batch pricing API allows Viator to retrieve pricing information in bulk, by enabling suppliers to provide pricing information for their products for a requested date range.

For suggestions on mapping Viator Pricing Options (Age Bands) for tickets to external pricing options, please see the above section “Suggested Price Option Mapping”.

Request Body schema:
requestType
required
string

BatchPricingRequest

required
object (BatchPricingRequest)

Root element for Batch Pricing Request

Responses

Response Schema:
responseType
required
string

BatchPricingResponse

required
object (BatchPricingResponse)

Root element for Batch Pricing Response

Request samples

Content type
{
  • "requestType": "BatchPricingRequest",
  • "data": {
    }
}

Response samples

Content type
{
  • "responseType": "BatchPricingResponse",
  • "data": {
    }
}

Booking API

The Booking API enables suppliers to receive Booking requests from Viator systems in real time. A successful request will create the booking in the supplier's system and return a success message to Viator systems which will confirm the booking directly to the customer. Each API call is always for a single booking only.

For suppliers that support the Availability API, the booking request is only ever made after Viator receives confirmation that the supplier has availability (if there have been no errors in the availability response). For suppliers that do not support the Availability API, booking requests will be sent without prior availability confirmation.

Request Body schema:
requestType
required
string

BookingRequest

required
object (BookingRequest)

Root element for Booking Request

Responses

Response Schema:
responseType
required
string

BookingResponse

required
object (BookingResponse)

Root element for Booking Response

Request samples

Content type
{
  • "requestType": "BookingRequest",
  • "data": {
    }
}

Response samples

Content type
Example
{
  • "responseType": "BookingResponse",
  • "data": {
    }
}

Booking Amendment API

The Booking Amendment API enables suppliers to receive amendment requests to confirmed bookings from Viator systems in real time. A successful request will amend an existing confirmed booking in the supplier's system and return a success message to Viator systems. Each API call is always for an amendment to a single booking only.

Request Body schema:
requestType
required
string

BookingAmendmentRequest

required
object (BookingAmendmentRequest)

Root element for Booking Amendment Request

Responses

Response Schema:
responseType
required
string

BookingAmendmentResponse

required
object (BookingAmendmentResponse)

Root element for Booking Amendment Response

Request samples

Content type
{
  • "requestType": "BookingAmendmentRequest",
  • "data": {
    }
}

Response samples

Content type
{
  • "responseType": "BookingAmendmentResponse",
  • "data": {
    }
}

Booking Cancellation API

The booking cancellation API will be used by Viator to cancel previously confirmed bookings directly with suppliers. An API cancellation does not include details regarding refunds, it focuses purely on the cancellation of the actual booking.

Request Body schema:
requestType
required
string

BookingCancellationRequest

required
object (BookingCancellationRequest)

Root element for Booking Cancellation Request

Responses

Response Schema:
responseType
required
string

BookingCancellationResponse

required
object (BookingCancellationResponse)

Root element for Booking Cancellation Response

Request samples

Content type
{
  • "requestType": "BookingCancellationRequest",
  • "data": {
    }
}

Response samples

Content type
{
  • "responseType": "BookingCancellationResponse",
  • "data": {
    }
}

Redemption API

Redemption is currently in beta. If you are interested in supporting this API, please inform your API account manager before starting development. We will then assess whether your system is able to support the current redemption model.

The Redemption API enables Viator to identify ticket redemption status at both booking and traveller level.

Request Body schema:
requestType
required
string

RedemptionRequest

required
object (RedemptionRequest)

Root element for Redemption Request

Responses

Response Schema:
responseType
required
string

RedemptionResponse

required
object (RedemptionResponse)

Root element for Redemption Response

Request samples

Content type
{
  • "requestType": "RedemptionRequest",
  • "data": {
    }
}

Response samples

Content type
Example
{
  • "responseType": "RedemptionResponse",
  • "data": {
    }
}

Viator-built APIs

This section describes the API(s) offered by Viator systems that enable automated communications with Supplier systems.

Viator has developed these services and is able to make them available to any of its suppliers if they wish to utilize them.

Note that for these APIs, the request is sent to Viator and the response is received from Viator.

Availability Notification 2 API

The availability notification API gives suppliers the ability to notify Viator when changes to the availability of a product at the supplier's end occurs. This allows Viator to make previously blocked-out dates available, increasing the possibility of last-minute bookings. It also ensures dates can be blocked-out as soon as they become unavailable. If you are interested in supporting this API, please inform your API account manager before starting development.

Request Body schema:
requestType
required
string

AvailabilityNotification2Request

required
object (AvailabilityNotification2Request)

Root element for Availability Notification 2 Request

Responses

Response Schema:
responseType
required
string

AvailabilityNotification2Response

required
object (AvailabilityNotification2Response)

Root element for Availability Notification 2 Response

Request samples

Content type
{
  • "requestType": "AvailabilityNotification2Request",
  • "data": {
    }
}

Response samples

Content type
{
  • "responseType": "AvailabilityNotification2Response",
  • "data": {
    }
}

Appendices

TGDS error codes

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 unavilabe 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 travler mix
TGDS0037 Connection closed by reseller before response could be dispatched

Update history

Version Comments Date
1.4.11 Added Redemption API 27 Feb, 2024
1.4.10 Removed Parameter and Extension elements from all Requests/Responses schemas and examples 31 Jan, 2024
1.4.9 Modified advice for pricing by removing SupplierPrice element from Batch Pricing and Real Time Availability schemas and examples 29 Jan, 2024
1.4.8 Added TourTicket element to Booking Amendment response and modified schemas regarding Capacity and BookingCutoff elements in the Availability response from 'required' to 'optional' 10 Jan, 2024
1.4.7 Restructured page sections in order to clean up documentation and have a richer integration with Redocly 22 Dec, 2023
1.4.6 Returned Batch Pricing API section using RetailPrice. Added Suggested Price Option/Age Band Mapping. Availability notification API moved out of Beta 02 Nov, 2023
1.4.5 Published new manual ported from Mkdocs to Redoc CMS 19 May, 2023
1.4.4 Temporarily removed Batch Pricing API section and pricing details from real-time availability call for maintenance purposes 15 Feb, 2023
1.4.3 Removed API Resources section 5 Oct, 2022
1.4.2 Fixed error regarding capitalization of ageband designators regarding Capacity.Simple.ConsumedBy element 5 Oct, 2022
1.4.1 Modified advice regarding requirement for Capacity and BookingCutoff elements in the Availability response from 'optional' to 'mandatory' 4 Oct, 2022
1.4.0 Corrected example VersionTag value in Availability notification request sample 2 12 July, 2022
1.3.9 Added link to up-to-date WSDL/XSD for supplier-built services API resources section 10 March, 2022
1.3.8 Added Periodic Availability Checking response sample to real-time availability and pricing endpoint 23 Feb, 2022
1.3.7 Added Capacity element to the Availability response and instructions on its use in How to use the Capacity element 3 Feb, 2022
1.3.6 Added information about new BookingCutoff element 25 Oct, 2021
1.3.5 Added Viator-built services – Push Availability Notification API 30 Apr, 2021
1.3.4 Added VersionTag element to Availability response and Batch availability response 8 Apr, 2021
1.3.3 Updated wording in Batch pricing API 18 Aug, 2020
1.3.2 Slight clarification of field descriptions 26 Mar, 2020
1.3.1 Deprecated TourDuration 7 Feb, 2019
1.3 Added ticket to booking response 1 Nov, 2019
1.2 Added contact email to booking response. 1 Nov, 2019
1.1 Added Real-time Pricing API 1 Nov, 2019
1.0.9 Added Batch Pricing API 1 Nov, 2019
1.0.8 Upentry batch availability API samples to reflect appropriate XML structure 6 Nov, 2015
1.0.7 Correct availability response, TravellerMixAvailability, AvailabilityHold and AvailabilityStatus parent tags in table and sample. Upentry description of product mapping. Improved description for UnavailabilityReason. Added notes in API resources regarding WSDL and XSD usage. 26 Oct, 2015
1.0.6 Corrected TimeStamp format / example and changed case of SupplierId, ResellerId elements to match XSD. 5 May, 2014
1.0.5 Removed TravelTime from AvailabilityRequest. Document out of sync with XSD. 13 Feb, 2014
1.0.4 XML samples upentry to provide better end to end understanding of the various APIs 25 Nov, 2013
1.0.3 Added Viator Supplier API Test Harness URL. 15 Nov, 2013
1.0.2 TourDuration upentryd in Samples to reflect Spec. 23 Sept, 2013
1.0.1 Batch Availability: Supplier Product Code is Optional. All except Tour List: Rename TourOption to TourOptions. 27 Aug, 2013
1.0 Confirmed version. 29 July, 2013

Frequently asked questions

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.

Contact us

Please send all questions and suggestions to SupplierAPI@viator.com as this will log a ticket into our Supplier API Support system and ensures that we will respond as quickly as possible.