Latest update¶

Version	Comments	Date
1.4.5	Returned Batch Pricing API section using RetailPrice. Added Suggested Price Option/Age Band Mapping. Availability notification API moved out of Beta	18 Aug 2023
1.4.4	Temporarily removed Batch Pricing API section and pricing details from real-time availability call for maintenance purposes	13 Mar 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 Jul 2022
1.3.9	Added link to up-to-date WSDL/XSD for supplier-built services API resources section	10 Mar 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

Introduction¶

The purpose of this document is to provide technical details about the APIs that enable connectivity between Viator and its suppliers. The document outlines 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.

This document assumes the reader has a technical background and is familiar with XML, JSON, Webservices, APIs and similar technologies.

Business process support¶

The Viator APIs have been designed to support a number of business processes:

Product (tour) creation within the Viator booking system: supported by the tour list API.
Determining the availability of a tour: supported by the availability API and batch availability API.
Creating a booking in the supplier's system: supported by the booking API.
Amending a booking in the supplier's system: supported by the booking amendment API.
Canceling a booking in the supplier's system: supported by the booking cancellation API.

The following section includes 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

Implementation approach¶

The following is a list of activities that should take place during the implementation of automation (APIs) between Viator and suppliers. The suggested approach ensures the necessary steps are taken and provides visibility both to suppliers and Viator of the status of the implementation and the steps that should be taken next. The steps should be used as a guideline during the implementation:

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 timelines
4. Determine project team communication method
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
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)
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)
Test environment configuration - Viator will configure the test environment to enable testing with the supplier. This step includes:
1. API configuration (as listed under supplier API configuration)
2. Product configuration will require product mapping between supplier and Viator.
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)
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.
Go-live - Viator and supplier prepare for go-live. This includes:
1. Schedule go-live date
2. "Switch on" the API
3. Transaction monitoring and issue resolution
4. Sign-off by supplier and Viator

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.

Supplier-built services¶

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:

Booking API
Availability API
Batch availability API
Tour list API

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.

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.

Tour list request¶

Tag	Parent tag	Description	Optionality
`TourListRequest`		Root element	Mandatory
`ApiKey`	`TourListRequest`	String representing key used to identify the requester - key is provided by supplier	Mandatory
`ResellerId`	`TourListRequest`	Unique identifier for Viator.	Mandatory
`SupplierId`	`TourListRequest`	String representing unique supplier identifier within Viator's systems.	Mandatory
`ExternalReference`	`TourListRequest`	String representing unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`TourListRequest`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/ time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`TourListRequest`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only.	Optional
`Parameter`	`TourListRequest`	Parametrized extension point root element. Holds key/ value pair based extension points. Used only when agreed to by Viator and supplier.	Optional
`Name`	`Parameter`	String representing Key of Key Value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing Value of Key Value pair.	Mandatory (when `Parameter` element is used)

Tour list request sample¶

The below is a sample of a tour list request. The request is very simple and is intended to request a list of all products from the supplier.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<TourListRequest xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722994001</ExternalReference>
  <Timestamp>2013-12-10T13:30:54.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
</TourListRequest>

JSON:

{
  "requestType": "TourListRequest",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722994001",
    "Timestamp": "2013-12-10T13:30:54.616+10:00",
    "Extension": {},
    "Parameter": {}
  }
}

Tour list response¶

Tag	Parent tag	Description	Optionality
`TourListResponse`		Root element	Mandatory
`ApiKey`	`TourListResponse`	String representing key used to identify the requester - key is provided by supplier	Mandatory
`ResellerId`	`TourListResponse`	Unique identifier for Viator.	Mandatory
`SupplierId`	`TourListResponse`	String representing unique supplier identifier within Viator's systems.	Mandatory
`ExternalReference`	`TourListResponse`	String representing unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`TourListResponse`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`TourListResponse`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only.	Optional
`Parameter`	`TourListResponse`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and supplier.	Optional
`Name`	`Parameter`	String representing key of key/value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing value of key/value pair.	Mandatory (when `Parameter` element is used)
`RequestStatus`	`TourListResponse`	Request status root element. Holds the status information for the requested transaction.	Mandatory
`Status`	`RequestStatus`	Status of the request. Valid values are: SUCCESS for a successful transaction, or ERROR for unsuccessful transaction. (`Error` node must be populated)	Mandatory
`Error`	`RequestStatus`	Error root element.	Optional (Mandatory when `Status` = Error)
`ErrorCode`	`Error`	String representing the error code.	Mandatory (when `Error` element is used)
`ErrorMessage`	`Error`	String representing the error message in friendly format.	Optional
`ErrorDetails`	`Error`	String representing the technical error cause and details.	Optional
`Tour`	`TourListResponse`	Tour root element. Holds product (tour) and product option (tour option) information.	Mandatory
`SupplierProductCode`	`Tour`	String representing supplier's unique product (tour) code (identifier). This code will be used across multiple API calls. Maximum length: 50 characters	Mandatory
`SupplierProductName`	`Tour`	String representing the product (tour) name (name associated with supplier product code).	Mandatory
`CountryCode`	`Tour`	ISO 3166-1 two-letter code of the country where the tour is held. ISO 3166 is the International Standard for country codes and codes for their subdivisions. For more information visit iso.org.	Mandatory
`DestinationCode`	`Tour`	UN/LOCODE representing the city of the tour. UN/LOCODE includes over 95.721 locations in 243 countries. It is used by most major shipping companies, by freight forwarders and in the manufacturing industry around the world. For more information visit unece.org	Mandatory
`DestinationName`	`Tour`	String representing the location where tour is held.	Mandatory
`TourDescription`	`Tour`	String representing the description of the tour.	Mandatory
`TourOption`	`Tour`	Root element for tour options. Holds tour option information.	Optional
`SupplierOptionCode`	`TourOption`	String representing supplier's tour option code (identifier). An option is a version of the tour and each option must have a unique code. Examples: A tour that is conducted by a Spanish guide and also by an English guide has two options. A tour that has a luxurious version and a cheaper version is considered to have two options. A list of the suppliers product options can be provided by Viator for mapping purposes	Optional
`SupplierOptionName`	`TourOption`	String representing the product option (tour option) name (name associated with supplier option code).	Optional
`TourDepartureTime`	`TourOption`	Time of tour option departure. Values should be in time format. Example: `09:00:00`. Note: A tour that runs three times throughout the day (as the same tour option) will have three different `TourDepartureTime` elements.	Optional
`Option`	`TourOption`	Option root element. Contains additional information used to aid with the mapping of Viator tour options to supplier products when an supplier option code is not available.	Optional
`Name`	`Option`	String representing the option name.	Mandatory (when `Option` element used)
`Value`	`Option`	String representing the option value.	Mandatory (when `Option` element used)

Tour list response sample¶

The sample below represents the supplier response to a tour list request. In this sample, the supplier has two products, each product has multiple options. Note that values found under the <Option> node for each product/product option are key value pairs that assist in identifying the product in the suppliers reservation system (when supplier product code and supplier option code are not sufficient to uniquely identify the product). Below table displays the products and product options listed in the sample response:

Supplier product code	Supplier product name	Supplier product option code	Supplier option name	Product key value pairs (name = value;)
`BLUE`	Blue Mountains Adventure	BASIC	Basic Shared Accommodation	room = dualocc;
`BLUE`	Blue Mountains Adventure	DELUXE	Deluxe	Shared Accommodation room = dualocc;
`BLUE`	Blue Mountains Adventure	TWOROOMS	Separate Rooms	Accommodation room=singleocc;
`BLUE`	Blue Mountains Adventure	DELUXE_HOTEL	Deluxe Shared Accommodation w Hotel Pickup	room=dualocc; pickup=Y;
`ROCKSHIST`	Rocks Historical Walking Tour		3 hour historical tour	lang=en;lunch=no;
`ROCKSHIST`	Rocks Historical Walking Tour		3 hour historical tour in German	lang=de; lunch=no;
`ROCKSHIST`	Rocks Historical Walking Tour		3 hour historical tour with lunch in German	lang=de; lunch=yes;

XML:

<?xml version="1.0" encoding="UTF-8"?>
<TourListResponse xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722994001</ExternalReference>
  <Timestamp>2013-12-10T13:30:54.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <RequestStatus>
    <Status>SUCCESS</Status>
  </RequestStatus>
  <Tour>
    <SupplierProductCode>BLUE</SupplierProductCode>
    <SupplierProductName>Blue Mountains Adventure</SupplierProductName>
    <CountryCode>AU</CountryCode>
    <DestinationCode>SYD</DestinationCode>
    <DestinationName>Sydney</DestinationName>
    <TourDescription>Blue Mountains Adventure Tour</TourDescription>
    <TourOption>
      <SupplierOptionCode>BASIC</SupplierOptionCode>
      <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name>Room</Name>
        <Value>dualocc</Value>
      </Option>
    </TourOption>
    <TourOption>
      <SupplierOptionCode>DELUXE</SupplierOptionCode>
      <SupplierOptionName>Deluxe Shared Accommodation</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name>Room</Name>
        <Value>dualocc</Value>
      </Option>
    </TourOption>
    <TourOption>
      <SupplierOptionCode>TWOROOMS</SupplierOptionCode>
      <SupplierOptionName>Separate Rooms Accommodation</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name>Room</Name>
        <Value>singleocc</Value>
      </Option>
    </TourOption>
    <TourOption>
      <SupplierOptionCode>DELUXE_HOTEL</SupplierOptionCode>
      <SupplierOptionName>Deluxe Shared Accommodation w Hotel Pickup</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name>Room</Name>
        <Value>dualocc</Value>
        <Name>Pickup</Name>
        <Value>Y</Value>
      </Option>
    </TourOption>
  </Tour>
  <Tour>
    <SupplierProductCode>ROCKSHIST</SupplierProductCode>
    <SupplierProductName>Rocks Historical Walking Tour</SupplierProductName>
    <CountryCode>AU</CountryCode>
    <DestinationCode>SYD</DestinationCode>
    <DestinationName>Sydney</DestinationName>
    <TourDescription>Rocks Historical Walking Tour</TourDescription>
    <TourOption>
      <SupplierOptionCode />
      <SupplierOptionName>3 hour historical tour</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name>lang</Name>
        <Value>en</Value>
        <Name>lunch</Name>
        <Value>no</Value>
      </Option>
    </TourOption>
    <TourOption>
      <SupplierOptionCode />
      <SupplierOptionName>3 hour historical tour in German</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name>lang</Name>
        <Value>de</Value>
        <Name>lunch</Name>
        <Value>no</Value>
      </Option>
    </TourOption>
    <TourOption>
      <SupplierOptionCode />
      <SupplierOptionName>3 hour historical tour with lunch in German</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name>lang</Name>
        <Value>de</Value>
        <Name>lunch</Name>
        <Value>yes</Value>
      </Option>
    </TourOption>
  </Tour>
</TourListResponse>

JSON:

{
  "responseType": "TourListResponse",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722994001",
    "Timestamp": "2013-12-10T13:30:54.616+10:00",
    "Extension": {},
    "Parameter": {},
    "RequestStatus": {
      "Status": "SUCCESS"
    },
    "Tour": [
      {
        "SupplierProductCode": "BLUE",
        "SupplierProductName": "Blue Mountains Adventure",
        "CountryCode": "AU",
        "DestinationCode": "SYD",
        "DestinationName": "Sydney",
        "TourDescription": "Blue Mountains Adventure Tour",
        "TourOption": [
          {
            "SupplierOptionCode": "BASIC",
            "SupplierOptionName": "Basic Shared Accommodation",
            "TourDepartureTime": "09:00:00",
            "Option": [
              {
                "Name": "Room",
                "Value": "dualocc"
              }
            ]
          },
          {
            "SupplierOptionCode": "DELUXE",
            "SupplierOptionName": "Deluxe Shared Accommodation",
            "TourDepartureTime": "09:00:00",
            "Option": [
              {
                "Name": "Room",
                "Value": "dualocc"
              }
            ]
          },
          {
            "SupplierOptionCode": "TWOROOMS",
            "SupplierOptionName": "Separate Rooms Accommodation",
            "TourDepartureTime": "09:00:00",
            "Option": [
              {
                "Name": "Room",
                "Value": "singleocc"
              }
            ]
          },
          {
            "SupplierOptionCode": "DELUXE_HOTEL",
            "SupplierOptionName": "Deluxe Shared Accommodation w Hotel Pickup",
            "TourDepartureTime": "09:00:00",
            "Option": [ 
              {
                "Name": [
                  "Room",
                  "Pickup"
                ],
                "Value": [
                  "dualocc",
                  "Y"
                ]
              }
            ]
          }
        ]
      },
      {
        "SupplierProductCode": "ROCKSHIST",
        "SupplierProductName": "Rocks Historical Walking Tour",
        "CountryCode": "AU",
        "DestinationCode": "SYD",
        "DestinationName": "Sydney",
        "TourDescription": "Rocks Historical Walking Tour",
        "TourOption": [
          {
            "SupplierOptionCode": "",
            "SupplierOptionName": "3 hour historical tour",
            "TourDepartureTime": "09:00:00",
            "Option": 
            [
              {
                "Name": [
                  "lang",
                  "lunch"
                ],
                "Value": [
                  "en",
                  "no"
                ]
              }
            ]
          },
          {
            "SupplierOptionCode": "",
            "SupplierOptionName": "3 hour historical tour in German",
            "TourDepartureTime": "09:00:00",
            "Option": 
            [
              {
                "Name": [
                  "lang",
                  "lunch"
                ],
                "Value": [
                  "de",
                  "no"
                ]
              }
            ]
          },
          {
            "SupplierOptionCode": "",
            "SupplierOptionName": "3 hour historical tour with lunch in German",
            "TourDepartureTime": "09:00:00",
            "Option": 
            [
              {
                "Name": [
                  "lang",
                  "lunch"
                ],
                "Value": [
                  "de",
                  "yes"
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Batch availability API¶

The batch availability API enables Viator to the determine availability in bulk scale and uses a push methodology to determine supplier availability. This API has been designed to enable suppliers to provide availability information for all its products (and options) for a requested date range. Based on the request from suppliers, Viator systems will be informed of which dates to allow (for available dates) or disallow (for unavailable dates) customers to book a tour. By notifying Viator of availability, suppliers are empowered to make dates available or unavailable based on their systems availability. Because the supplier pushes the date changes to Viator systems, a better integration is achieved.

The following sections describes the batch availability request and response format and provides example XML for both.

Batch availability request¶

Tag	Parent tag	Description	Optionality
`BatchAvailabilityRequest`		Root element	Mandatory
`ApiKey`	`BatchAvailabilityRequest`	String representing key used to identify the requester - key is provided by supplier	Mandatory
`ResellerId`	`BatchAvailabilityRequest`	Unique identifier for Viator.	Mandatory
`SupplierId`	`BatchAvailabilityRequest`	Unique supplier identifier within Viator's systems.	Mandatory
`ExternalReference`	`BatchAvailabilityRequest`	Unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`BatchAvailabilityRequest`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) -> 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`BatchAvailabilityRequest`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only.	Optional
`Parameter`	`BatchAvailabilityRequest`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and supplier.	Optional
`Name`	`Parameter`	String representing key of key/value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing value of key value pair.	Mandatory (when `Parameter` element is used)
`StartDate`	`BatchAvailabilityRequest`	Date for which tour availability is being requested from supplier. If supplied without an `EndDate`, then a single date availability request is being made. If supplier with an `EndDate`, then availability request is for a date range. The date should be in date format: YYYY-MMDD. Example: 2000-01-31	Mandatory
`EndDate`	`BatchAvailabilityRequest`	End date of date range for which tour availability is being requested from upplier. If this is empty, availability will be searched for the given `StartDate` only. The date should be in date format: YYYY-MM-DD. Example: 2000-01-31	Optional
`Mode`	`BatchAvailabilityRequest`	Availability request mode. Valid values include: ALL - This mode requests that all dates are returned with appropriate availability status.	Mandatory

Batch availability request sample¶

The sample below represents a request for all changes to availability since "2020-01-14T13:04:27.500Z" for operation dates between 2020-01-14 and 2020-02-13.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BatchAvailabilityRequest xmlns="http://toursgds.com/api/01">
  <ApiKey>ZDNycnlSdWwzcw</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>1023_2936275621425724</ExternalReference>
  <Timestamp>2020-01-14T13:04:27.500Z</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <StartDate>2020-01-14</StartDate>
  <EndDate>2020-02-13</EndDate>
  <Mode>ALL</Mode>
</BatchAvailabilityRequest>

JSON:

{
  "requestType": "BatchAvailabilityRequest",
  "data": {
    "StartDate": "2020-01-14",
    "EndDate": "2020-02-13",
    "Mode": "ALL",
    "ApiKey": "ZDNycnlSdWwzcw",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "1023_2936275621425724",
    "Timestamp": "2020-01-14T13:04:27.500Z"
  }
}

Batch availability response¶

Tag	Parent tag	Description	Optionality
`BatchAvailabilityResponse`		Root element	Mandatory
`ApiKey`	`BatchAvailabilityResponse`	String representing key used to identify the responder - key is provided by Viator	Mandatory
`ResellerId`	`BatchAvailabilityResponse`	Unique identifier for Viator.	Mandatory
`SupplierId`	`BatchAvailabilityResponse`	Unique supplier identifier within Viator system.	Mandatory
`ExternalReference`	`BatchAvailabilityResponse`	Unique transaction identifier - unique across all transactions. Matches number provided in request.	Optional
`Timestamp`	`BatchAvailabilityResponse`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`BatchAvailabilityResponse`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only	Optional
`Parameter`	`BatchAvailabilityResponse`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and supplier	Optional
`Name`	`Parameter`	String representing key of key/value pair.	Mandatory (when Parameter element is used)
`Value`	`Parameter`	String representing value of key/value pair.	Mandatory (when Parameter element is used)
`RequestStatus`	`BatchAvailabilityResponse`	Request status root element. Holds the status information for the requested transaction.	Mandatory
`Status`	`RequestStatus`	Status of the request. Valid values are: SUCCESS for a successful transaction, or ERROR for unsuccessful transaction. (`Error` node must be populated. Other root elements may be omitted in this case.)	Mandatory
`Error`	`RequestStatus`	`Error` root element	Optional (Mandatory when `Status` = error)
`ErrorCode`	`Error`	String representing the error code.	Mandatory
`ErrorMessage`	`Error`	String representing the error message in friendly format.	Optional
`ErrorDetails`	`Error`	String representing the technical error cause and details.	Optional
`BatchTourAvailability`	`BatchAvailabilityResponse`	Batch availability root element. Holds availability for each product (tour) or product option (tour option). For products with more than one option, multiple `TourAvailability` elements will be provided in the response, one for each option. If a product has no options, then a single `BatchTourAvailability` element will be provided in the response with no `SupplierOptionCode`.	Mandatory
`Date`	`BatchTourAvailability`	Date for which tour availability is being supplied. The date should be in date format: YYYY-MM-DD. Example: 2000-01-31	Mandatory
`SupplierProductCode`	`BatchTourAvailability`	String representing suppliers unique product (tour) code (identifier). This code will be used across multiple API calls. Maximum length: 50 characters	Mandatory
`TourOptions`	`BatchTourAvailability`	Tour option root element. Holds details pertaining to each of the tour options (including default if no tour options exist).	Optional
`SupplierOptionCode`	`TourOptions`	String representing suppliers tour option code (identifier). An option is a version of the tour and each option must have a unique code. Examples: A tour that is conducted by a Spanish guide and also by an English guide has two options. A tour that has a luxurious version and a cheaper version is considered to have two options. A list of the suppliers product options can be provided by Viator for mapping purposes.	Optional
`SupplierOptionName`	`TourOptions`	String representing the product option (tour option) name (name associated with supplier option code).	Optional
`TourDepartureTime`	`TourOptions`	Time of tour departure. Values should be in time format. Example: `09:00:00`. Note: A tour that runs three times throughout the day (as the same tour option) will have three different `TourDepartureTime` elements.	Optional
`Option`	`TourOptions`	Option root element. Contains additional information used to aid with the mapping of Viator tour options to supplier products when an supplier option code is not available.	Optional
`Name`	`Option`	String representing the option name	Mandatory (when `Option` element used)
`Value`	`Option`	String representing the option value.	Mandatory (when `Option` element used)
`AvailabilityStatus`	`BatchTourAvailability`	Availability status root element. Holds the availability status for given product (tour) or product option (tour option).	Mandatory
`Status`	`AvailabilityStatus`	Status of availability. Valid values include: AVAILABLE - when product is available for the given `Date` and `TravellerMix`. UNAVAILABLE - when product is not available for the given `Date` and `TravellerMix`.	Mandatory
`UnavailabilityReason`	`AvailabilityStatus`	Reason why product is not available. Valid values include: SOLD_OUT - when the product (tour) / product option (tour option) is sold out. When this reason code is received, the product or product option become unavailable for sale on Viator systems. BLOCKED_OUT - when the product (tour) / product option (tour option) has been blocked out (not taking place on this date). When this reason code is received, the product or product option become unavailable for sale on Viator systems. INACTIVE - when the product (tour) / product option (tour option) is no longer active. When this reason code is received, the product or product option become unavailable for sale on Viator systems. PAST_CUTOFF_DATE - when the booking cut-off date has been reach for this product (tour) / product option (tour option). When this reason code is received, the product or product option become unavailable for sale on Viator systems. NO_EVENT - This event is not longer valid. When this reason code is received, the product or product option become unavailable for sale on Viator systems	Optional (mandatory when `Status` = UNAVAILABLE)
`TravellerMixAvailablibity`	`BatchTourAvailability`	Traveller mix availability root element. Holds availability information for each age band.	Optional
`Adult`	`TravellerMixAvailability`	True if availability exists for adult age band. Boolean field: `true` or `false`.	Optional
`Child`	`TravellerMixAvailability`	True if availability exists for child age band. Boolean field: `true` or `false`	Optional
`Youth`	`TravellerMixAvailability`	True if availability exists for youth age band. Boolean field: `true` or `false`	Optional
`Infant`	`TravellerMixAvailability`	True if availability exists for infant age band. Boolean field: `true` or `false`	Optional
`Senior`	`TravellerMixAvailability`	True if availability exists for senior age band. Boolean field: `true` or `false`	Optional
`VersionTag`	`BatchTourAvailability`	Version tag root element. Version tagging allows availability responses to be tagged with one of: a time-stamp, a text-string, or a numeric identifier. Attaching this tag will allow our systems to determine which availability response should be taken as the most recent in the event that multiple availability responses for the same product arrive with differing information. Our systems will consider the availability response with the most recent timestamp, or highest textual or numeric value as the authoritative response.	Optional
`Timestamp`	`VersionTag`	Timestamp to determine the order in which this availability response was generated; e.g. `2021-12-02T12:34:56.789012345Z`	Optional
`Textual`	`VersionTag`	Text string of your choosing. Our systems will consider the highest-value string to be that which was sent most recently. E.g., `20121202-V000000231434`	Optional
`Numeric`	`VersionTag`	Numeric value of your choosing. Our systems will consider the highest number to be that which was sent most recently. E.g., `553957349573498`	Optional

Batch availability response sample¶

Single date / multiple products response¶

The sample below represents the supplier response to a single date / multiple product batch availability request (see batch availability request sample). Each product has one option (9am private / 9am group), therefore availability is shown for each option of the product. In this example one tour has been sold out and is therefore unavailable and the other is available.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BatchAvailabilityResponse xmlns="http://toursgds.com/api/01">
  <ApiKey>ZDNycnlSdWwzcw</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992616</ExternalReference>
  <Timestamp>2013-07-25T13:29:52.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <RequestStatus>
    <Status>SUCCESS</Status>
  </RequestStatus>
  <BatchTourAvailability>
    <Date>2014-10-1</Date>
    <TourOptions>
      <SupplierOptionCode>BASIC</SupplierOptionCode>
      <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name>Room</Name>
        <Value>dualocc</Value>
      </Option>
    </TourOptions>
    <SupplierProductCode>BLUE</SupplierProductCode>
    <AvailabilityStatus>
      <Status>UNAVAILABLE</Status>
      <UnavailabilityReason>SOLD_OUT</UnavailabilityReason>
    </AvailabilityStatus>
    <VersionTag> 
      <Numeric>553957349573497</Numeric>
    </VersionTag>
  </BatchTourAvailability>
  <BatchTourAvailability>
    <Date>2014-10-1</Date>
    <TourOptions>
      <SupplierOptionCode>9AM</SupplierOptionCode>
      <SupplierOptionName>Bondi Beach Private Lesson 9AM</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name />
        <Value />
      </Option>
    </TourOptions>
    <SupplierProductCode>BON_GRO</SupplierProductCode>
    <AvailabilityStatus>
      <Status>AVAILABLE</Status>
    </AvailabilityStatus>
    <VersionTag> 
      <Numeric>553957349573498</Numeric>
    </VersionTag>
  </BatchTourAvailability>
</BatchAvailabilityResponse>

JSON:

{
  "responseType": "BatchAvailabilityResponse",
  "data": {
    "ApiKey": "ZDNycnlSdWwzcw",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992616",
    "Timestamp": "2013-07-25T13:29:52.616+10:00",
    "Extension": {},
    "Parameter": {},
    "RequestStatus": {
      "Status": "SUCCESS"
    },
    "BatchTourAvailability": [
      {
        "Date": "2014-10-1",
        "TourOptions": {
          "SupplierOptionCode": "BASIC",
          "SupplierOptionName": "Basic Shared Accommodation",
          "TourDepartureTime": "09:00:00",
          "Option": 
          [
            {
              "Name": "Room",
              "Value": "dualocc"
            }
          ]
        },
        "SupplierProductCode": "BLUE",
        "AvailabilityStatus": {
          "Status": "UNAVAILABLE",
          "UnavailabilityReason": "SOLD_OUT"
        },
        "VersionTag": {
          "Numeric": "553957349573497"
        }
      },
      {
        "Date": "2014-10-1",
        "TourOptions": {
          "SupplierOptionCode": "9AM",
          "SupplierOptionName": "Bondi Beach Private Lesson 9AM",
          "TourDepartureTime": "09:00:00",
           "Option": [{}]
        },
        "SupplierProductCode": "BON_GRO",
        "AvailabilityStatus": {
          "Status": "AVAILABLE"
        },
        "VersionTag": {
          "Numeric": "553957349573498"
        }
      }
    ]
  }
}

Date range / single product response¶

The sample below represents the supplier response to a batch availability request for unavailable dates (Blockouts) of a single product (BLUE) for a date range (2014-10-30 to 2014-10-31) - see batch availability request sample. In this example tours that are unavailable for the entire date range are displayed.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BatchAvailabilityResponse xmlns="http://toursgds.com/api/01">
  <ApiKey>ZDNycnlSdWwzcw</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992616</ExternalReference>
  <Timestamp>2013-07-25T13:29:52.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <RequestStatus>
    <Status>SUCCESS</Status>
  </RequestStatus>
  <BatchTourAvailability>
    <Date>2014-10-30</Date>
    <TourOptions>
      <SupplierOptionCode>BASIC</SupplierOptionCode>
      <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name>Room</Name>
        <Value>dualocc</Value>
      </Option>
    </TourOptions>
    <SupplierProductCode>BLUE</SupplierProductCode>
    <AvailabilityStatus>
      <Status>UNAVAILABLE</Status>
      <UnavailabilityReason>SOLD_OUT</UnavailabilityReason>
    </AvailabilityStatus>
    <VersionTag> 
      <Numeric>5539573495734986</Numeric>
    </VersionTag>
  </BatchTourAvailability>
  <BatchTourAvailability>
    <Date>2014-10-31</Date>
    <TourOptions>
      <SupplierOptionCode>BASIC</SupplierOptionCode>
      <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name>Room</Name>
        <Value>dualocc</Value>
      </Option>
    </TourOptions>
    <SupplierProductCode>BLUE</SupplierProductCode>
    <AvailabilityStatus>
      <Status>UNAVAILABLE</Status>
      <UnavailabilityReason>SOLD_OUT</UnavailabilityReason>
    </AvailabilityStatus>
    <VersionTag> 
      <Numeric>5539573495734987</Numeric>
    </VersionTag>
  </BatchTourAvailability>
</BatchAvailabilityResponse>

JSON:

{
  "responseType": "BatchAvailabilityResponse",
  "data": {
    "ApiKey": "ZDNycnlSdWwzcw",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992616",
    "Timestamp": "2013-07-25T13:29:52.616+10:00",
    "Extension": {},
    "Parameter": {},
    "RequestStatus": {
      "Status": "SUCCESS"
    },
    "BatchTourAvailability": [
      {
        "Date": "2014-10-30",
        "TourOptions": {
          "SupplierOptionCode": "BASIC",
          "SupplierOptionName": "Basic Shared Accommodation",
          "TourDepartureTime": "09:00:00",
          "Option": [{}]
        },
        "SupplierProductCode": "BLUE",
        "AvailabilityStatus": {
          "Status": "UNAVAILABLE",
          "UnavailabilityReason": "SOLD_OUT"
        },
        "VersionTag": {
          "Numeric": "5539573495734986"
        }
      },
      {
        "Date": "2014-10-31",
        "TourOptions": {
          "SupplierOptionCode": "BASIC",
          "SupplierOptionName": "Basic Shared Accommodation",
          "TourDepartureTime": "09:00:00",
          "Option": [{}]
        },
        "SupplierProductCode": "BLUE",
        "AvailabilityStatus": {
          "Status": "UNAVAILABLE",
          "UnavailabilityReason": "SOLD_OUT"
        },
        "VersionTag": {
          "Numeric": "5539573495734987"
        }
      }
    ]
  }
}

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

Real-time availability API¶

This API enables Viator to contact the supplier's reservation system in real time to determine if a tour (with or without specifying a particular tour option) is availabile given a specific number of passengers on a certain date – or, across a range of dates.

Being able to verify availability in real time with the supplier leads to fewer booking rejections and an increase in last-minute bookings.

Based on the response received from the supplier, Viator's systems will allow or prevent customers booking a tour depending on its availability on that day.

When an availability request is made with a single date, the intention is to determine up-to-the-minute availability information for the tour. This call is made when the customer is booking a tour and has selected a specific date and traveller mix. If the response from the supplier indicates that the tour is available given these criteria, the customer will be allowed to complete the booking.

Therefore, in the response for a single date request, you are expected to include availability information in the response.

Periodic availability checking¶

In order to minimize the latency with regard to determining availability information and increase the accuracy of our local records, our systems will reach out periodically (approximately once every 30 minutes) with a simple real-time availability request for a single date that does not include any information about the traveler mix, as it is not initiated by or related to any user activity.

Example:

{
  "requestType":"AvailabilityRequest",
  "data": {
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992616",
    "Timestamp": "2022-02-23T13:29:52.616+10:00",
    "StartDate": "2022-02-25",
    "SupplierProductCode": "BLUE"
  }
}

Supporting the user workflow¶

As the customer progresses through their workflow; i.e., as they are attempting to determine the availablility of – and eventually book – a product, there are three different kinds of real-time availability request that you will receive, corresponding to the three stages in that workflow.

The stages are as follows:

1. The traveler selects a product and a date on which they would like to travel (as well as their desired traveler mix)¶

The real-time availability request will include:

StartDate
SupplierProductCode
TravellerMix

Example:

{
  "requestType":"AvailabilityRequest",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992616",
    "Timestamp": "2013-07-25T13:29:52.616+10:00",
    "StartDate": "2014-10-31",
    "SupplierProductCode": "BLUE",
    "TravellerMix": {
      "Adult": "1",
      "Child": "1",
      "Youth": "0",
      "Infant": "0",
      "Senior": "0",
      "Total": "2"
    }
  }
}

The response should include: all available TourOptions (product options) given the specified criteria for the traveler to choose in the next step of the workflow.

2. The traveler selects a product option and adds the product with the selected product option to their shopping cart¶

The real-time availability request will include:

StartDate
SupplierProductCode
TourOptions
TravellerMix

Example:

{
  "requestType":"AvailabilityRequest",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992616",
    "Timestamp": "2013-07-25T13:29:52.616+10:00",
    "StartDate": "2014-10-31",
    "SupplierProductCode": "BLUE",
    "TourOptions": {
      "SupplierOptionCode": "BASIC",
      "SupplierOptionName": "Basic Shared Accommodation",
      "TourDepartureTime": "09:00:00",
      "Option":
      [
        {
          "Name": "Room",
          "Value": "dualocc"
        }
      ]
    },
    "TravellerMix": {
      "Adult": "1",
      "Child": "1",
      "Youth": "0",
      "Infant": "0",
      "Senior": "0",
      "Total": "2"
    }
  }
}

3. The traveler proceeds to the checkout¶

At this point in the workflow, it will be necessary to implement an 'availability hold' to ensure that the availability which they were guaranteed persists until the traveler can complete their transaction.

The real-time availability request will include:

StartDate
SupplierProductCode
TourOptions
AvailabilityHold
TravellerMix

Example:

{
  "requestType":"AvailabilityRequest",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992616",
    "Timestamp": "2013-07-25T13:29:52.616+10:00",
    "StartDate": "2014-10-31",
    "SupplierProductCode": "BLUE",
    "TourOptions": {
      "SupplierOptionCode": "BASIC",
      "SupplierOptionName": "Basic Shared Accommodation",
      "TourDepartureTime": "09:00:00"
    },
    "AvailabilityHold": {
      "Expiry": "PT300S"
    },
    "TravellerMix": {
      "Adult": "1",
      "Child": "1",
      "Youth": "0",
      "Infant": "0",
      "Senior": "0",
      "Total": "2"
    }
  }
}

Date range requests¶

When an availability request is made for a date range, the intention is to determine future availability in bulk. Viator's systems will cache this information for use in cases where the supplier's systems cannot be reached for real-time availability checks (e.g., due to interrupted network connectivity).

Availability request¶

Tag	Parent Tag	Description	Optionality
`AvailabilityRequest`		Root element	Mandatory
`ApiKey`	`AvailabilityRequest`	String representing Key used to identify the requester - key is provided by supplier	Mandatory
`ResellerId`	`AvailbilityRequest`	Unique identifier for Viator	Mandatory
`SupplierId`	`AvailabilityRequest`	Unique supplier identifier within Viator system	Mandatory
`ExternalReference`	`AvailabilityRequest`	Unique transaction identifier - unique across all transactions – used in the response to identify the initial request	Optional
`Timestamp`	`AvailabilityRequest`	Time of creation of request; date/time (timestamp) that requires timezone information along with date/time; the date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time), or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`AvailabilityRequest`	Extension point that allows the addition of arbitrary element nodes; any such elements can be used upon agreement between Viator and supplier only	Optional
`Parameter`	`AvailabilityRequest`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and supplier.	Optional
`Name`	`Parameter`	String representing key of key / value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing key of key / value pair.	Mandatory (when `Parameter` element is used)
`StartDate`	`AvailabilityRequest`	Date for which tour availability is being requested from supplier. If supplied without an `EndDate`, then a single date availability request is being made. If supplied with an `EndDate`, then availability request is for a date range. The date should be in date format: YYYY-MMDD. Example: 2000-01-31	Mandatory
`EndDate`	`AvailabilityRequest`	End date of date range for which tour availability is being requested from supplier. If this is empty, availability will be searched for the given `StartDate` only. The date should be in date format: YYYY-MM-DD. Example: 2000-01-31	Optional
`SupplierProductCode`	`AvailabilityRequest`	String representing suppliers unique product (tour) code (identifier). This code will be used across multiple API calls. Maximum length: 50 characters	Mandatory
`TourOptions`	`AvailabilityRequest`	Tour option root element. Holds details pertaining to each of the tour options (including default if not tour options exist).	Optional
`SupplierOptionCode`	`TourOptions`	String representing suppliers tour option code (identifier). An option is a version of the tour and each option must have a unique code. Examples: A tour that is conducted by a Spanish guide and also by an English guide has two options. A tour that has a luxurious version and a cheaper version is considered to have two options. A list of the suppliers product options can be provided by Viator for mapping purposes.	Optional
`SupplierOptionName`	`TourOptions`	String representing the product option (tour option) name (name associated with supplier option code).	Optional
`TourDepartureTime`	`TourOptions`	Time of tour departure. Values should be in time format. Example: `09:00:00`. Note: A tour that runs three times throughout the day (as the same tour option) will have three different `TourDepartureTime` elements.	Optional
`Option`	`TourOptions`	Option root element. Contains additional information used to aid with the mapping of Viator tour options to supplier products when an supplier option code is not available.	Optional
`Name`	`Option`	String representing the option name	Mandatory (when `Option` element used)
`Value`	`Option`	String representing the Option Value	Mandatory (when `Option` element used)
`AvailabilityHold`	`AvailabilityRequest`	Availability hold root element. Availability hold is sent with an availability request only if a Viator customer proceeds to checkout (high probability of confirmed sale).	Optional
`Expiry`	`AvailabilityHold`	Duration after which the availability hold should expire for the current request. This is a suggested value, the supplier can determine to define its own duration (which will be provided in the availability API response). Expiry value must be positive and provided in duration format: PnYnMnDTnHnMnS. Example: PT300S (5 minutes)	Mandatory (when `AvailablilityHold` is used)
`TravellerMix`	`AvailabilityRequest`	Traveller mix root element. Holds the number of travellers at each age band for which availability is being requested. If not specified, then overall availability is requested. Traveller age bands are based on supplier provided age ranges.	Optional
`Adult`	`TravellerMix`	Number of adults	Optional
`Child`	`TravellerMix`	Number of children	Optional
`Youth`	`TravellerMix`	Number of youths	Optional
`Infant`	`TravellerMix`	Number of infants	Optional
`Senior`	`TravellerMix`	Number of seniors	Optional
`Total`	`TravellerMix`	Total number of travelers	Optional

Availability request sample¶

Single date request¶

The sample below represents an availability request for 1 adult and 1 child, sent to the supplier system for product: BLUE, option: BASIC (supplier option). The request asks for availability to be held for 300 seconds (5 minutes).

XML:

<?xml version="1.0" encoding="UTF-8"?>
<AvailabilityRequest xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992616</ExternalReference>
  <Timestamp>2013-07-25T13:29:52.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <StartDate>2014-10-31</StartDate>
  <EndDate />
  <SupplierProductCode>BLUE</SupplierProductCode>
  <TourOptions>
    <SupplierOptionCode>BASIC</SupplierOptionCode>
    <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
    <TourDepartureTime>09:00:00</TourDepartureTime>
    <Option>
      <Name>Room</Name>
      <Value>dualocc</Value>
    </Option>
  </TourOptions>
  <AvailabilityHold>
    <Expiry>PT300S</Expiry>
  </AvailabilityHold>
  <TravellerMix>
    <Adult>1</Adult>
    <Child>1</Child>
    <Youth>0</Youth>
    <Infant>0</Infant>
    <Senior>0</Senior>
    <Total>2</Total>
  </TravellerMix>
</AvailabilityRequest>

JSON:

{
  "requestType":"AvailabilityRequest",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992616",
    "Timestamp": "2013-07-25T13:29:52.616+10:00",
    "Extension": {},
    "Parameter": {},
    "StartDate": "2014-10-31",
    "EndDate": "",
    "SupplierProductCode": "BLUE",
    "TourOptions": {
      "SupplierOptionCode": "BASIC",
      "SupplierOptionName": "Basic Shared Accommodation",
      "TourDepartureTime": "09:00:00",
      "Option": 
      [
        {
          "Name": "Room",
          "Value": "dualocc"
        }
      ]
    },
    "AvailabilityHold": {
      "Expiry": "PT300S"
    },
    "TravellerMix": {
      "Adult": "1",
      "Child": "1",
      "Youth": "0",
      "Infant": "0",
      "Senior": "0",
      "Total": "2"
    }
  }
}

Date range request¶

The sample below is for a date range availability call sent to the supplier for the BASIC option of the supplier's product "BLUE". The request specifically asks for availability between October 30 and October 31 of 2014 for 1 adult and 1 child. The <Option> node is used as a way to provide the supplier information that helps identifying the product at the suppliers system, in this case the supplier uses "room" as and identifier. The <option> node is used to provide key value pairs (<name> and <value>) that aid with product identification. In this example, the suppliers product and option are identified by the SupplierProductCode, SupplierOptionCode as well as the option "Room". The <Option> node is used because Viator Supplier API does not have a specific field for "room", instead the <Option> node is used to provide this information.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<AvailabilityRequest xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992616</ExternalReference>
  <Timestamp>2013-07-25T13:29:52.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <StartDate>2014-10-30</StartDate>
  <EndDate>2014-10-31</EndDate>
  <SupplierProductCode>BLUE</SupplierProductCode>
  <TourOptions>
    <SupplierOptionCode>BASIC</SupplierOptionCode>
    <Option>
      <Name>Room</Name>
      <Value>dualocc</Value>
    </Option>
  </TourOptions>
  <AvailabilityHold>
    <Expiry />
  </AvailabilityHold>
  <TravellerMix>
    <Adult>1</Adult>
    <Child>1</Child>
    <Youth>0</Youth>
    <Infant>0</Infant>
    <Senior>0</Senior>
    <Total>2</Total>
  </TravellerMix>
</AvailabilityRequest>

JSON:

{
  "requestType":"AvailabilityRequest",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992616",
    "Timestamp": "2013-07-25T13:29:52.616+10:00",
    "Extension": {},
    "Parameter": {},
    "StartDate": "2014-10-30",
    "EndDate": "2014-10-31",
    "SupplierProductCode": "BLUE",
    "TourOptions": {
      "SupplierOptionCode": "BASIC",
      "Option": 
      [
        {
          "Name": "Room",
          "Value": "dualocc"
        }
      ]
    },
    "AvailabilityHold": {},
    "TravellerMix": {
      "Adult": "1",
      "Child": "1",
      "Youth": "0",
      "Infant": "1",
      "Senior": "0",
      "Total": "3"
    }
  }
}

Availability response¶

Tag	Parent Tag	Description	Optionality
`AvailabilityResponse`		Root element	Mandatory
`ApiKey`	`AvailabilityResponse`	String representing key used to identify the responder Note: this key is provided by Viator	Mandatory
`ResellerId`	`AvailabilityResponse`	Unique identifier for Viator.	Mandatory
`SupplierId`	`AvailabilityResponse`	Unique supplier identifier within Viator's systems.	Mandatory
`ExternalReference`	`AvailabilityResponse`	Unique transaction identifier - unique across all transactions. Matches number provided in request.	Optional
`Timestamp`	`AvailabilityResponse`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Examples: `2013-04-28T13:10:12.123Z` (UTC time) `2013-04-28T13:10:12.123+10:00`	Mandatory
`Extension`	`AvailabilityResponse`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only	Optional
`Parameter`	`AvailabilityResponse`	Parametrized extension point root element. Holds key/value-pair-based extension points. Used only when agreed to by Viator and supplier	Optional
`Name`	`Parameter`	String representing key of key/value pair	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing value of key/value pair	Mandatory (when `Parameter` element is used)
`RequestStatus`	`AvailabilityResponse`	Request status root element. Holds the status information for the requested transaction.	Mandatory
`Status`	`RequestStatus`	Status of the request. Valid values are: `SUCCESS`: a successful transaction, or `ERROR`: unsuccessful transaction (Note: Error node must be populated. Other root elements may be omitted in this case.)	Mandatory
`Error`	`RequestStatus`	Error root element	Optional (mandatory when status = error)
`ErrorCode`	`Error`	String representing the error code	Mandatory
`ErrorMessage`	`Error`	String representing the error message in friendly format	Optional
`ErrorDetails`	`Error`	String representing the technical error cause and details	Optional
`SupplierProductCode`	`AvailabilityResponse`	String representing suppliers unique product (tour) code (identifier) that will be used across multiple API calls. Note: Maximum length: 50 characters	Mandatory
`TourAvailability`	`AvailabilityResponse`	Tour availability root element. Holds availability for each product (tour) or product option (tour option). For products with more than one option, multiple `TourAvailability` elements will be provided in the response, one for each option. If a product has no options, then a single `TourAvailability` element will be provided in the response with no `SupplierOptionCode`.	Mandatory
`Date`	`TourAvailability`	Date for which tour availability is being supplied. The date should be in date format: YYYY-MM-DD. Example: 2000-01-31	Mandatory
`TourOptions`	`TourAvailability`	Tour option root element. Holds details pertaining to each of the tour options (including default if no tour options exist).	Optional
`BookingCutoff`	`TourAvailability`	Booking cut-off root element; contains information about the point in time after which the tour option may become unavailable, referred to as the 'booking cut-off'. It is mandatory to provide one of the three child element options listed below – `DateTime`, `ProductDateTime` or `NotApplicable`	Mandatory
`DateTime`	`BookingCutoff`	Datetime string that must include the time-zone that describes absolutely when the booking cut-off is. Examples: `2021-11-07T12:13:14+10:30` `2021-11-07T22:22:11.000-10:00` We would prefer that you provide a datetime adjusted to UTC; however, we will accept any legitimate time-zone offset; our systems will adjust accordingly.	Optional
`ProductDateTime`	`BookingCutoff`	Datetime string that must not include a time-zone or 'Z' (UTC) offset that describes when the booking cut-off is in the time-zone of the product. Use this element instead of the `DateTime` element if you are unable to provide the full datetime string with time-zone included. Examples: `2021-11-08T12:13:14` `2021-11-08T11:22:33.000`	Optional
`NotApplicable`	`BookingCutoff`	'True' if a booking cut-off does not exist for this product option. If set, our systems will attempt to make any sale until we receive an `AvailabilityStatus` of `UNAVAILABLE`; or, the present moment has advanced beyond the product's start time. Boolean field: `true` or `false`.	Optional
`SupplierOptionCode`	`TourOptions`	String representing suppliers tour option code (identifier). An option is a version of the tour and each option must have a unique code. Examples: A tour that is conducted by a Spanish guide and also by an English guide has two options. A tour that has a luxurious version and a cheaper version is considered to have two options. A list of the suppliers product options can be provided by Viator for mapping purposes.	Optional
`SupplierOptionName`	`TourOptions`	String representing the product option (tour option) name (name associated with supplier option code).	Optional
`TourDepartureTime`	`TourOptions`	Time of tour departure. Values should be in time format. Example: `09:00:00`. Note: A tour that runs three times throughout the day (as the same tour option) will have three different `TourDepartureTime` elements.	Optional
`Option`	`TourOptions`	Option root element. Contains additional information used to aid with the mapping of Viator tour options to supplier products when an supplier option code is not available.	Optional
`Name`	`Option`	String representing the option name	Mandatory (when `Option` element used)
`Value`	`Option`	String representing the option value.	Mandatory (when `Option` element used)
`AvailabilityHold`	`TourAvailability`	Availability hold root element. Availability hold is sent with an availability request only if a Viator customer proceeds to checkout high probability of confirmed sale). To be provided in response if `AvailabilityHold` feature is supported by the supplier.	Optional (mandatory when `AvailabilityHold` is supported)
`Expiry`	`AvailabilityHold`	Duration after which the availability hold will expire for the current request. This is either the same value as provided by Viator in the request or a value determined by the supplier. Expiry value must be positive and provided in duration format: PnYnMnDTnHnMnS. Example: PT300S (5 minutes).	Mandatory (when `AvailabilityHold` is used)
`Reference`	`AvailabilityHold`	String representing the availability hold reference assigned by the supplier. The reference will be used in a subsequent booking request to advise the supplier that the booking is related to the prior availability hold request. Response scoped.	Mandatory (when `AvailabilityHold` is used)
`AgeBand`	`Item`	Age band of traveller. Valid values include: Adult Child Youth Infant Senior Traveller age bands are based on supplier provided age ranges.	Mandatory
`AvailabilityStatus`	`TourAvailability`	Availability status root element. Holds the availability status for given product (tour) or product option (tour option).	Mandatory
`Status`	`AvailabilityStatus`	Status of availability. Valid values include: AVAILABLE - when product is available for the given `Date` and `TravellerMix`. UNAVAILABLE - when product is not available for the given `Date` and `TravellerMix`.	Mandatory
`UnavailabilityReason`	`AvailabilityStatus`	Reason why product is not available. Valid values include: SOLD_OUT - when the product (tour)/ product option (tour option) is sold out. When this reason code is received, the product or product option become unavailable for sale on Viator systems. BLOCKED_OUT - when the product (tour) / product option (tour option) has been blocked out (not taking place on this date). When this reason code is received, the product or product option become unavailable for sale on Viator systems. INACTIVE - when the product (tour) / product option (tour option) is no longer active. When this reason code is received, the product or product option become unavailable for sale on Viator systems. PAST_CUTOFF_DATE - when the booking cut-off date has been reach for this product (tour)/ product option (tour option). When this reason code is received, the product or product option become unavailable for sale on Viator systems. TRAVELLER_MISMATCH - when the required combination of travellers for this product (tour) / product option (tour option) is not met or when the number of requested passengers cannot be fulfilled, but a lower number can (i.e. availability status for three people is unavailable, but availability status for two is available). NO_EVENT - This event is not longer valid. When this reason code is received, the product or product option become unavailable for sale on Viator systems	Optional (mandatory when `Status` = UNAVAILABLE)
`TravellerMixAvailablibity`	`AvailabilityStatus`	Traveller mix availability root element. Holds availability information for each age band.	Optional
`Adult`	`TravellerMixAvailablibity`	True if availability exists for adult age band. Boolean field: `true` or `false`	Optional
`Child`	`TravellerMixAvailablibity`	True if availability exists for child age band. Boolean field: `true` or `false`	Optional
`Youth`	`TravellerMixAvailablibity`	True if availability exists for youth age band. Boolean field: `true` or `false`	Optional
`Infant`	`TravellerMixAvailablibity`	True if availability exists for infant age band. Boolean field: `true` or `false`	Optional
`Senior`	`TravellerMixAvailablibity`	True if availability exists for senior age band. Boolean field: `true` or `false`	Optional
`Capacity`	`TourAvailability`	Capacity root element. Allows for capacity-management by communicating the remaining places available for Viator to book for this product. The system allows for all or only certain agebands to draw down on the available places, to allow, for example, infants to be excluded and thereby not affect the remaining capacity. See How to use the Capacity element for more information.	Mandatory
`Simple`	`Capacity`	Simple capacity root element. Contains elements for remaining places and which ageband(s) (if applicable) consume these places	Mandatory
`Remaining`	`Simple`	Numeric value representing number of remaining places	Mandatory
`ConsumedBy`	`Simple`	Name of ageband that can consume the remaining places; one of `"ADULT"`, `"CHILD"`, `"INFANT"`, `"YOUTH"`, `"SENIOR"`	Optional
`VersionTag`	`TourAvailability`	Version tag root element. Version tagging allows availability responses to be tagged with one of: a time-stamp, a text-string, or a numeric identifier. Attaching this tag will allow our systems to determine which availability response should be taken as the most recent in the event that multiple availability responses for the same product arrive with differing information. Our systems will consider the availability response with the most recent timestamp, or highest textual or numeric value as the authoritative response.	Optional
`Timestamp`	`VersionTag`	Timestamp to determine the order in which this availability response was generated; e.g. `2021-12-02T12:34:56.789012345Z`	Optional
`Textual`	`VersionTag`	Text string of your choosing. Our systems will consider the highest-value string to be that which was sent most recently. E.g., `20121202-V000000231434`	Optional
`Numeric`	`VersionTag`	Numeric value of your choosing. Our systems will consider the highest number to be that which was sent most recently. E.g., `553957349573498`	Optional

Availability response sample¶

Single date response¶

The sample below is the response provided by the supplier system for a single date availability request. In this response the option (BASIC) of the tour (BLUE) is available on October 31 2014. The response provides a reference number (optional) for the availability hold that was requested in the call (see availability request sample), the reference will be used in the subsequent booking request (optional). The availability response also provides availability information for all age bands for the date and product of the request - allowing Viator systems to track availability for other age bands and reduce the number of calls to the supplier.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<AvailabilityResponse xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992616</ExternalReference>
  <Timestamp>2013-07-25T13:29:52.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <RequestStatus>
    <Status>SUCCESS</Status>
  </RequestStatus>
  <SupplierProductCode>BLUE</SupplierProductCode>
  <TourAvailability>
    <Date>2014-10-31</Date>
    <BookingCutoff>
        <NotApplicable>true</NotApplicable>
    </BookingCutoff>
    <TourOptions>
      <SupplierOptionCode>BASIC</SupplierOptionCode>
      <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
      <TourDepartureTime>09:00:00</TourDepartureTime>
      <Option>
        <Name>Room</Name>
        <Value>dualocc</Value>
      </Option>
    </TourOptions>
    <AvailabilityStatus>
      <Status>AVAILABLE</Status>
      <TravellerMixAvailability>
        <Adult>true</Adult>
        <Child>true</Child>
        <Youth>true</Youth>
        <Infant>true</Infant>
        <Senior>true</Senior>
      </TravellerMixAvailability>
    </AvailabilityStatus>
    <AvailabilityHold>
      <Expiry>PT300S</Expiry>
      <Reference>1K883383K2S12K883383K2S57K883383K2</Reference>
    </AvailabilityHold>
    <VersionTag> 
      <Textual>20130705-V000000231434</Textual>
    </VersionTag>
  </TourAvailability>
</AvailabilityResponse>

JSON:

{
  "responseType": "AvailabilityResponse",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992616",
    "Timestamp": "2013-07-25T13:29:52.616+10:00",
    "Extension": {},
    "Parameter": {},
    "RequestStatus": {
      "Status": "SUCCESS"
    },
    "SupplierProductCode": "BLUE",
    "TourAvailability": [
      {
        "Date": "2014-10-31",
        "BookingCutoff": {
            "NotApplicable": "true"
        },
        "TourOptions": {
          "SupplierOptionCode": "BASIC",
          "SupplierOptionName": "Basic Shared Accommodation",
          "TourDepartureTime": "09:00:00",
          "Option": [
            {
              "Name": "Room",
              "Value": "dualocc"
            }
          ]
        },
        "AvailabilityStatus": {
          "Status": "AVAILABLE",
          "TravellerMixAvailability": {
            "Adult": "true",
            "Child": "true",
            "Youth": "true",
            "Infant": "true",
            "Senior": "true"
          }
        },
        "AvailabilityHold": {
          "Expiry": "PT300S",
          "Reference": "1K883383K2S12K883383K2S57K883383K2"
        },
        "VersionTag": {
          "Textual": "20130705-V000000231434"
        }
      }
    ]
  }
}

Date range response¶

The sample below is the response provided by the supplier system for a date range availability request. In this response the product is available on 2014-10-30 but sold out on 2014-10-31.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<AvailabilityResponse xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992616</ExternalReference>
  <Timestamp>2013-07-25T13:29:52.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <RequestStatus>
    <Status>SUCCESS</Status>
  </RequestStatus>
  <SupplierProductCode>BLUE</SupplierProductCode>
  <TourAvailability>
    <Date>2014-10-30</Date>
    <BookingCutoff>
        <NotApplicable>true</NotApplicable>
    </BookingCutoff>
    <TourOptions>
      <SupplierOptionCode>BASIC</SupplierOptionCode>
      <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
      <TourDepartureTime />
      <Option>
        <Name>room</Name>
        <Value>dualocc</Value>
      </Option>
    </TourOptions>
    <AvailabilityStatus>
      <Status>AVAILABLE</Status>
    </AvailabilityStatus>
    <AvailabilityHold>
      <Expiry />
      <Reference />
    </AvailabilityHold>
    <VersionTag> 
      <Textual>20130705-V000000231435</Textual>
    </VersionTag>
  </TourAvailability>
  <TourAvailability>
    <Date>2014-10-31</Date>
    <BookingCutoff>
        <NotApplicable>true</NotApplicable>
    </BookingCutoff>
    <TourOptions>
      <SupplierOptionCode>BASIC</SupplierOptionCode>
      <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
      <TourDepartureTime />
      <Option>
        <Name>room</Name>
        <Value>dualocc</Value>
      </Option>
    </TourOptions>
    <AvailabilityStatus>
      <Status>UNAVAILABLE</Status>
      <UnavailabilityReason>SOLD_OUT</UnavailabilityReason>
    </AvailabilityStatus>
    <AvailabilityHold>
      <Expiry />
      <Reference />
    </AvailabilityHold>
    <VersionTag> 
      <Textual>20130705-V000000231436</Textual>
    </VersionTag>
  </TourAvailability>
</AvailabilityResponse>

JSON:

{
  "responseType": "AvailabilityResponse",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992616",
    "Timestamp": "2013-07-25T13:29:52.616+10:00",
    "Extension": {},
    "Parameter": {},
    "RequestStatus": {
      "Status": "SUCCESS"
    },
    "SupplierProductCode": "BLUE",
    "TourAvailability": [
      {
        "Date": "2014-10-30",
        "BookingCutoff": {
            "NotApplicable": "true"
        },
        "TourOptions": {
          "SupplierOptionCode": "BASIC",
          "SupplierOptionName": "Basic Shared Accommodation",
          "TourDepartureTime": "",
          "Option": 
          [
            {
              "Name": "room",
              "Value": "dualocc"
            }
          ]
        },
        "AvailabilityStatus": {
          "Status": "AVAILABLE"
        },
        "AvailabilityHold": {},
        "VersionTag": {
          "Textual": "20130705-V000000231435"
        }
      },
      {
        "Date": "2014-10-31",
        "BookingCutoff": {
            "NotApplicable": "true"
        },
        "TourOptions": {
          "SupplierOptionCode": "BASIC",
          "SupplierOptionName": "Basic Shared Accommodation",
          "TourDepartureTime": "",
          "Option": 
          [
            {
              "Name": "room",
              "Value": "dualocc"
            }
          ]
        },
        "AvailabilityStatus": {
          "Status": "UNAVAILABLE",
          "UnavailabilityReason": "SOLD_OUT"
        },
        "AvailabilityHold": {},
        "VersionTag": {
          "Textual": "20130705-V000000231436"
        }
      }
    ]
  }
}

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:

By the supplier's system in the contents of the BookingCutoff element of the Availability response
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-28</Date>
    <TourOptions/>
    <AvailabilityStatus>
        <Status>AVAILABLE</Status>
    </AvailabilityStatus>
    <BookingCutoff>
        <DateTime>2021-11-07T22:22:11.000-10:00</DateTime>
    </BookingCutoff>
</TourAvailability>
<TourAvailability>
    <Date>2021-11-29</Date>
    <TourOptions/>
    <AvailabilityStatus>
        <Status>AVAILABLE</Status>
    </AvailabilityStatus>
    <BookingCutoff>
        <ProductDateTime>2021-11-08T11:22:33.000</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 prod

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 capcity 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.

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 titled “Suggested Price Option Mapping”

Note: We require systems to send RetailPrice data; however, we understand that this is dependent on the values held in your system.

Batch pricing request¶

Tag	Parent Tag	Description	Optionality
`BatchPricingRequest`		Root element	Mandatory
`ApiKey`	`BatchPricingRequest`	String representing the API key used to identify the requester - API key is provided by the supplier	Mandatory
`ResellerId`	`BatchPricingRequest`	Unique identifier for Viator	Mandatory
`SupplierID`	`BatchPricingRequest`	Unique supplier identifier within Viator's systems	Mandatory
`ExternalReference`	`BatchPricingRequest`	Unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`BatchPricingRequest`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/ time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`BatchPricingRequest`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only.	Optional
`Parameter`	`BatchPricingRequest`	Parametrized extension point root element. Holds key/ value pair based extension points. Used only when agreed to by Viator and supplier.	Optional
`Name`	`Parameter`	String representing key of key/value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing value of key/value pair.	Mandatory (when `Parameter` element is used)
`StartDate`	`BatchPricingRequest`	The date should be in date format: YYYY-MM-DD.	Mandatory
`EndDate`	`BatchPricingRequest`	The date should be in date format: YYYY-MM-DD.	Mandatory
`SupplierProductCode`	`BatchPricingRequest`	Array of strings specifying the supplier's unique product codes. These codes will be used across multiple API calls.	Optional

Batch pricing request sample¶

The sample below represents a request for prices from 2020-06-20 to 2020-06-21.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BatchPricingRequest xmlns="http://toursgds.com/api/01">
  <ApiKey>ZDNycnlSdWwzcw</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992617</ExternalReference>
  <Timestamp>2019-06-26T20:40:55.375Z</Timestamp>
  <StartDate>2020-06-20</StartDate>
  <EndDate>2020-06-21</EndDate>
  <SupplierProductCode>BLUE</SupplierProductCode>
</BatchPricingRequest>

JSON:

{
  "requestType":"BatchPricingRequest",
  "data": {
    "ApiKey": "ZDNycnlSdWwzcw",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992617",
    "Timestamp": "2019-06-26T20:40:55.375Z",
    "StartDate": "2020-06-20",
    "EndDate": "2020-06-21",
    "SupplierProductCode": ["BLUE"]
  }
}

Batch pricing response¶

Tag	Parent Tag	Description	Optionality
`BatchPricingRequest`		Root element	Mandatory
`ApiKey`	`BatchPricingResponse`	String representing the API key used to identify the requester - API key is provided by the supplier	Mandatory
`ResellerId`	`BatchPricingResponse`	Unique identifier for Viator	Mandatory
`SupplierID`	`BatchPricingResponse`	Unique supplier identifier within Viator's systems	Mandatory
`ExternalReference`	`BatchPricingResponse`	Unique transaction identifier - unique across all transactions. Matches number provided in request.	Optional
`Timestamp`	`BatchPricingResponse`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`BatchPricingResponse`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and Supplier only.	Optional
`Parameter`	`BatchPricingResponse`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and the supplier.	Optional
`Name`	`Parameter`	String representing key of key/value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing value of key/value pair.	Mandatory (when `Parameter` element is used)
`RequestStatus`	`BatchPricingResponse`	Request status root element. Holds the status information for the requested transaction.	Mandatory
`Status`	`RequestStatus`	Status of the request. Valid values are: SUCCESS for a successful transaction, or ERROR for unsuccessful transaction. (Error node must be populated. Other root elements may be omitted in this case.)	Mandatory
`Error`	`RequestStatus`	Error root element	Optional (mandatory when status = error)
`ErrorCode`	`Error`	String representing the error code.	Mandatory (when `Error` element is used
`ErrorMessage`	`Error`	String representing the error message in friendly format.	Optional
`ErrorDetails`	`Error`	String representing the technical error cause and details.	Optional
`CurrencyCode`	`BatchPricingResponse`	Currency code for this pricing information. ISO 4217 three-letter currency code associated with the booking price. ISO 4217 three-letter currency code associated with the booking price. ISO 4217 is the International Standard for currency codes. For more information visit iso.org.	Mandatory
`BatchTourPricing`	`BatchPricingResponse`	`BatchTourPricing` root element. Holds pricing information for the requested product for a specific date and tour option. Each date in the requested range must have at least one `BatchTourPricing` element.	Optional
`Date`	`BatchTourPricing`	Date for which tour pricing is being supplied. The date should be in date format: YYYY-MMDD. Example: 2000-01-31	Mandatory
`SupplierProductCode`	`BatchTourPricing`	String representing the supplier's unique product (tour) code (identifier). This code will be used across multiple API calls.	Mandatory
`TourOptions`	`BatchTourPricing`	Tour option root element. Holds details pertaining to each of the tour options (including default if no tour options exist).	Optional
`TourDepartureTime`	`TourOptions`	Time of tour departure. Values should be in time format. Example: 09:00:00. Note: A tour that runs three times throughout the day (as the same tour option) will have three different TourDepartureTime elements.	Optional
`BatchPrice`	`BatchTourPricing`	`BatchPrice` root element. Holds pricing information (supplier and reseller prices) for each available age band of the given product (tour).	Optional
`Item`	`BatchPrice`	Single price information retrieved from the supplier API	Mandatory
`SupplierPrice`	`Item`	Stores the price to be paid to the supplier for the booking on the tour for the given age band.	Optional (however, it is mandatory to include at least one of `SupplierPrice` or `RetailPrice`)
`RetailPrice`	`Item`	Stores the recommended price for which the booking should be made on the shop by the customer	Optional (however, it is mandatory to include at least one of `SupplierPrice` or `RetailPrice`)
`AgeBand`	`Traveller`	Age band of traveller. Valid values include: Adult Child Youth Infant Senior Traveller age bands are based on supplier provided age ranges.	Mandatory
`AvailabilityStatus`	`BatchTourPricing`	Availability status root element. Holds the availability status for given product (tour) or product option (tour option).	Mandatory
`Status`	`AvailabilityStatus`	Status of availability. Valid values include: AVAILABLE - when product is available for the given `Date` and `TravellerMix`. UNAVAILABLE - when product is not available for the given `Date` and `TravellerMix`.	Mandatory
`UnavailabilityReason`	`AvailabilityStatus`	Reason why product is not available. Valid values include: SOLD_OUT - when the product (tour)/ product option (tour option) is sold out. When this reason code is received, the product or product option become unavailable for sale on Viator systems. BLOCKED_OUT - when the product (tour) / product option (tour option) has been blocked out (not taking place on this date). When this reason code is received, the product or product option become unavailable for sale on Viator systems. INACTIVE - when the product (tour) / product option (tour option) is no longer active. When this reason code is received, the product or product option become unavailable for sale on Viator systems. PAST_CUTOFF_DATE - when the booking cut-off date has been reach for this product (tour)/ product option (tour option). When this reason code is received, the product or product option become unavailable for sale on Viator systems. NO_EVENT - This event is not longer valid. When this reason code is received, the product or product option become unavailable for sale on Viator systems	Optional (mandatory when `Status` = UNAVAILABLE)
`TravellerMixAvailablibity`	`AvailabilityStatus`	Traveller mix availability root element. Holds availability information for each age band.	Optional
`Adult`	`TravellerMixAvailablibity`	True if availability exists for adult age band. Boolean field: `true` or `false`	Optional
`Child`	`TravellerMixAvailablibity`	True if availability exists for child age band. Boolean field: `true` or `false`	Optional
`Youth`	`TravellerMixAvailablibity`	True if availability exists for youth age band. Boolean field: `true` or `false`	Optional
`Infant`	`TravellerMixAvailablibity`	True if availability exists for infant age band. Boolean field: `true` or `false`	Optional
`Senior`	`TravellerMixAvailablibity`	True if availability exists for senior age band. Boolean field: `true` or `false`	Optional

Batch Pricing Response Sample¶

The sample below represents a request for prices from 2020-06-20 to 2020-06-21. This is a partial extract of the response.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BatchPricingResponse xmlns="http://toursgds.com/api/01">
  <ApiKey>ZDNycnlSdWwzcw</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992617</ExternalReference>
  <Timestamp>2019-06-26T20:40:55.375Z</Timestamp>
  <RequestStatus>
    <Status>SUCCESS</Status>
  </RequestStatus>
  <CurrencyCode>USD</CurrencyCode>
  <BatchTourPricing>
    <Date>2020-06-20</Date>
    <SupplierProductCode>BLUE</SupplierProductCode>
    <TourOptions>
      <SupplierOptionCode>BASIC</SupplierOptionCode>
      <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
      <TourDepartureTime>17:00:00</TourDepartureTime>
    </TourOptions>
    <BatchPrice>
      <Item>
        <SupplierPrice>9.9</SupplierPrice>
        <RetailPrice>10.0</RetailPrice>
        <AgeBand>Infant</AgeBand>
      </Item>
      <Item>
        <SupplierPrice>9.9</SupplierPrice>
        <RetailPrice>10.0</RetailPrice>
        <AgeBand>Child</AgeBand>
      </Item>
      <Item>
        <SupplierPrice>9.9</SupplierPrice>
        <RetailPrice>10.0</RetailPrice>
        <AgeBand>Youth</AgeBand>
      </Item>
      <Item>
        <SupplierPrice>9.9</SupplierPrice>
        <RetailPrice>10.0</RetailPrice>
        <AgeBand>Adult</AgeBand>
      </Item>
      <Item>
        <SupplierPrice>9.9</SupplierPrice>
        <RetailPrice>10.0</RetailPrice>
        <AgeBand>Senior</AgeBand>
      </Item>
    </BatchPrice>
    <AvailabilityStatus>
      <Status>AVAILABLE</Status>
    </AvailabilityStatus>
  </BatchTourPricing>
  <BatchTourPricing>
    <Date>2020-06-20</Date>
    <SupplierProductCode>BLUE</SupplierProductCode>
    <TourOptions>
      <SupplierOptionCode>BASIC</SupplierOptionCode>
      <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
      <TourDepartureTime>17:00:00</TourDepartureTime>
    </TourOptions>
    <BatchPrice>
      <Item>
        <SupplierPrice>45.53</SupplierPrice>
        <RetailPrice>45.99</RetailPrice>
        <AgeBand>Infant</AgeBand>
      </Item>
      <Item>
        <SupplierPrice>45.53</SupplierPrice>
        <RetailPrice>45.99</RetailPrice>
        <AgeBand>Child</AgeBand>
      </Item>
      <Item>
        <SupplierPrice>45.53</SupplierPrice>
        <RetailPrice>45.99</RetailPrice>
        <AgeBand>Youth</AgeBand>
      </Item>
      <Item>
        <SupplierPrice>45.53</SupplierPrice>
        <RetailPrice>45.99</RetailPrice>
        <AgeBand>Adult</AgeBand>
      </Item>
      <Item>
        <SupplierPrice>45.53</SupplierPrice>
        <RetailPrice>45.99</RetailPrice>
        <AgeBand>Senior</AgeBand>
      </Item>
    </BatchPrice>
    <AvailabilityStatus>
      <Status>AVAILABLE</Status>
    </AvailabilityStatus>
  </BatchTourPricing>
  <!-- The remaining BatchTourPricing tags have been removed for the sake of brevity. -->
</BatchPricingResponse>

JSON:

{
  "responseType": "BatchPricingResponse",
  "data": {
    "ApiKey": "ZDNycnlSdWwzcw",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992617",
    "Timestamp": "2019-06-26T20:40:55.375Z",
    "RequestStatus": {
      "Status": "SUCCESS"
    },
    "CurrencyCode": "USD",
    "BatchTourPricing": [
      {
        "Date": "2020-06-20",
        "SupplierProductCode": "BLUE",
        "TourOptions": {
          "SupplierOptionCode": "BASIC",
          "SupplierOptionName": "Basic Shared Accommodation",
          "TourDepartureTime": "17:00:00"
        },
        "BatchPrice": {
          "Item": [
            {
              "SupplierPrice": "9.9",
              "RetailPrice": "10.0",
              "AgeBand": "Infant"
            },
            {
              "SupplierPrice": "9.9",
              "RetailPrice": "10.0",
              "AgeBand": "Child"
            },
            {
              "SupplierPrice": "9.9",
              "RetailPrice": "10.0",
              "AgeBand": "Youth"
            },
            {
              "SupplierPrice": "9.9",
              "RetailPrice": "10.0",
              "AgeBand": "Adult"
            },
            {
              "SupplierPrice": "9.9",
              "RetailPrice": "10.0",
              "AgeBand": "Senior"
            }
          ]
        },
        "AvailabilityStatus": {
          "Status": "AVAILABLE"
        }
      },
      {
        "Date": "2020-06-20",
        "SupplierProductCode": "BLUE",
        "TourOptions": {
          "SupplierOptionCode": "BASIC",
          "SupplierOptionName": "Basic Shared Accommodation",
          "TourDepartureTime": "17:00:00"
        },
        "BatchPrice": {
          "Item": [
            {
              "SupplierPrice": "45.53",
              "RetailPrice": "45.99",
              "AgeBand": "Infant"
            },
            {
              "SupplierPrice": "45.53",
              "RetailPrice": "45.99",
              "AgeBand": "Child"
            },
            {
              "SupplierPrice": "45.53",
              "RetailPrice": "45.99",
              "AgeBand": "Youth"
            },
            {
              "SupplierPrice": "45.53",
              "RetailPrice": "45.99",
              "AgeBand": "Adult"
            },
            {
              "SupplierPrice": "45.53",
              "RetailPrice": "45.99",
              "AgeBand": "Senior"
            }
          ]
        },
        "AvailabilityStatus": {
          "Status": "AVAILABLE"
        }
      }
    ]
  }
}

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 suppliers 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.

The following sections provide details regarding the request and response formats.

Booking request¶

Tag	Parent Tag	Description	Optionality
`BookingRequest`		Root element	Mandatory
`ApiKey`	`BookingRequest`	String representing key used to identify the requester - key is provided by supplier	Mandatory
`ResellerId`	`BookingRequest`	Unique identifier for Viator.	Mandatory
`SupplierId`	`BookingRequest`	Unique supplier identifier within Viator's systems.	Mandatory
`ExternalReference`	`BookingRequest`	Unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`BookingRequest`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`BookingRequest`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only.	Optional
`Parameter`	`BookingRequest`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and supplier.	Optional
`Name`	`Parameter`	String representing key of key/value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing value of key/value pair.	Mandatory (when `Parameter` element is used)
`BookingReference`	`BookingRequest`	String representing a unique booking identifier within Viator's systems.	Mandatory
`TravelDate`	`BookingRequest`	The date of travel for the itinerary item. Date should be in date format YYYY-MM-DD. Example: 2000-01-31	Mandatory
`SupplierProductCode`	`BookingRequest`	String representing suppliers unique product (Tour) code (identifier). This code will be used across multiple API calls. Maximum length: 50 characters	Mandatory
`Location`	`BookingRequest`	String representing the city and country that the tour is in. Example: Sydney, Australia	Optional
`TourOptions`	`BookingRequest`	Tour option root element. Holds details pertaining to each of the tour options (including default if not tour options exist).	Optional
`SupplierOptionCode`	`TourOptions`	String representing suppliers tour option code (identifier). An option is a version of the tour and each option must have a unique code. Examples: A tour that is conducted by a Spanish guide and also by an English guide has two options. A tour that has a luxurious version and a cheaper version is considered to have two options. A list of the supplier's product options can be provided by Viator for mapping purposes	Optional
`SupplierOptionName`	`TourOptions`	String representing the product option (tour option) name (name associated with supplier option code).	Optional
`TourDepartureTime`	`TourOptions`	Time of tour departure. Values should be in time format. Example: `09:00:00`. Note: A tour that runs three times throughout the day (as the same tour option) will have three different `TourDepartureTime` elements.	Optional
`Option`	`TourOptions`	Option root element. Contains additional information used to aid with the mapping of Viator tour options to supplier products when an supplier option code is not available.	Optional
`Name`	`Option`	String representing the option name.	Mandatory (when `Parameter` element is used)
`Value`	`Option`	String representing the option value.	Mandatory (when `Parameter` element is used)
`Inclusions`	`BookingRequest`	Root element for inclusions. Contains inclusions in the product (tour) / product option (tour option) offering.	Optional
`Inclusion`	`Inclusions`	String representing an inclusion of the product offering.	Optional
`CurrencyCode`	`BookingRequest`	ISO 4217 three-letter currency code associated with the booking price. ISO 4217 is the International Standard for currency codes. For more information visit iso.org.	Optional
`Amount`	`BookingRequest`	Numeric value for the booking net price paid to the supplier; e.g., "550.00"	Optional
`Traveller`	`BookingRequest`	Root element for traveller. Contains traveller information for the booking.	Mandatory
`TravellerIdentifier`	`Traveller`	Integer representing unique identifier per traveller for the booking.	Mandatory
`TravellerTitle`	`Traveller`	String representing the title of the traveller.	Optional
`GivenName`	`Traveller`	String representing the traveller's given name.	Mandatory
`Surname`	`Traveller`	String representing the travellers surname.	Mandatory
`AgeBand`	`Traveller`	Age band of traveller. Valid values include: Adult Child Youth Infant Senior Traveller age bands are based on supplier provided age ranges.	Mandatory
`LeadTraveller`	`Traveller`	Boolean value ('true' or 'false') that specifies whether this traveller should be considered the 'lead traveller'.	Optional
`TravellerMix`	`BookingRequest`	Traveller mix root element. Holds the number of travellers at each age band for which availability is being requested. If not specified, then overall availability is requested. Traveller age bands are based on supplier	Optional
`Adult`	`TravellerMix`	Number of adults.	Optional
`Child`	`TravellerMix`	Number of children.	Optional
`Youth`	`TravellerMix`	Number of youths.	Optional
`Infant`	`TravellerMix`	Number of infants.	Optional
`Senior`	`TravellerMix`	Number of seniors.	Optional
`Total`	`TravellerMix`	Total number of travellers.	Optional
`RequiredInfo`	`BookingRequest`	Required information root element. Holds both question and answers of supplier required information.	Optional
`QuestionText`	`RequiredInfo`	String representing the question asked to the customer to obtain required information.	Mandatory (when `Question` element used)
`QuestionAnswer`	`RequiredInfo`	String representing the customers answer to the question.	Mandatory (when `Question` element used)
`SpecialRequirement`	`BookingRequest`	String representing a special requirement from the customer (max. 169 characters including spaces)	Optional
`Question`	`RequiredInfo`	Question root element. Holds question and answer text.	Optional
`PickupPoint`	`BookingRequest`	String representing the customer pickup point for the tour. Only pickup points previously agreed to supplier are allowed.	Optional
`ContactDetail`	`BookingRequest`	Contact detail root element. Holds customer contact information.	Optional
`ContactType`	`ContactDetail`	Type of contact used for contacting customer while travelling. The only valid value is: ALTERNATE	Mandatory (when `ContactDetail` element used)
`ContactName`	`ContactDetail`	String representing the name of the contact.	Mandatory (when `ContactDetail` element used)
`ContactValue`	`ContactDetail`	String representing the contact information (i.e phone number, email, etc)	Mandatory (when `ContactDetail` element used)
`ContactEmail`	`BookingRequest`	String representing a traveller-protected contact email address that expires 30 days after travel date (maximum 85 characters); e.g: `MSG-8b17fa92-7b35-4fdb-9f18-f8a69252e019+BR-999999999@expmessaging.tripadvisor.com`	Optional
`AvailabilityHoldReference`	`BookingRequest`	String representing the availability hold reference assigned by the supplier during an availability call. To be used by the supplier to 'use' the availability that was held.	Optional
`Retry`	`BookingRequest`	Boolean value of whether the request is a retry of a previously erred attempt. If omitted should be considered false as a new booking request.	Optional

Booking request sample¶

The sample below is a booking request for two people, 1 adult and 1 child, travelling on October 31, 2014. The booking is for a product (BLUE) for the BASIC option. Supplier required information is provided in the <RequiredInfo> node. An <AvailabilityHoldReference> is passed in the booking to use the hold previously set by the availability request (see availability request sample).

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BookingRequest xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992645</ExternalReference>
  <Timestamp>2013-07-25T13:30:52.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <BookingReference>999999999</BookingReference>
  <TravelDate>2014-10-31</TravelDate>
  <SupplierProductCode>BLUE</SupplierProductCode>
  <Location>Sydney, Australia</Location>
  <TourOptions>
    <SupplierOptionCode>BASIC</SupplierOptionCode>
    <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
    <TourDepartureTime>09:00:00</TourDepartureTime>
    <Option>
      <Name>Room</Name>
      <Value>dualocc</Value>
    </Option>
  </TourOptions>
  <Inclusions>
    <Inclusion>Bottle of Champagne</Inclusion>
    <Inclusion>Hotel Pickup</Inclusion>
  </Inclusions>
  <CurrencyCode>AUD</CurrencyCode>
  <Amount>550.00</Amount>
  <Traveller>
    <TravellerIdentifier>1</TravellerIdentifier>
    <TravellerTitle>Mrs</TravellerTitle>
    <GivenName>Turonga</GivenName>
    <Surname>Leela</Surname>
    <AgeBand>Adult</AgeBand>
    <LeadTraveller>true</LeadTraveller>
  </Traveller>
  <Traveller>
    <TravellerIdentifier>2</TravellerIdentifier>
    <TravellerTitle>Ms</TravellerTitle>
    <GivenName>Tamy</GivenName>
    <Surname>Leela</Surname>
    <AgeBand>Child</AgeBand>
    <LeadTraveller>false</LeadTraveller>
  </Traveller>
  <TravellerMix>
    <Adult>1</Adult>
    <Child>1</Child>
    <Youth>0</Youth>
    <Infant>0</Infant>
    <Senior>0</Senior>
    <Total>2</Total>
  </TravellerMix>
  <RequiredInfo>
    <Question>
      <QuestionText>Passport No.</QuestionText>
      <QuestionAnswer>L99999</QuestionAnswer>
    </Question>
    <Question>
      <QuestionText>Weight</QuestionText>
      <QuestionAnswer>50 Kg</QuestionAnswer>
    </Question>
  </RequiredInfo>
  <SpecialRequirement>Vegetarian Meal</SpecialRequirement>
  <PickupPoint>Hilton Sydney</PickupPoint>
  <ContactDetail>
    <ContactType>ALTERNATE</ContactType>
    <ContactName>Turonga Leela</ContactName>
    <ContactValue>US+1 999999999</ContactValue>
  </ContactDetail>
  <ContactEmail>MSG-8b17fa92-7b35-4fdb-9f18-f8a69252e019+BR-999999999@expmessaging.tripadvisor.com</ContactEmail>
  <AvailabilityHoldReference>1K883383K2S12K883383K2S57K883383K2</AvailabilityHoldReference>
</BookingRequest>

JSON:

{
  "requestType":"BookingRequest",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992645",
    "Timestamp": "2013-07-25T13:30:52.616+10:00",
    "Extension": {},
    "Parameter": {},
    "BookingReference": "999999999",
    "TravelDate": "2014-10-31",
    "SupplierProductCode": "BLUE",
    "Location": "Sydney, Australia",
    "TourOptions": {
      "SupplierOptionCode": "BASIC",
      "SupplierOptionName": "Basic Shared Accommodation",
      "TourDepartureTime": "09:00:00",
      "Option": [{}]
    },
    "Inclusions": {
      "Inclusion": [
        "Bottle of Champagne",
        "Hotel Pickup"
      ]
    },
    "CurrencyCode": "AUD",
    "Amount": "550.00",
    "Traveller": [
      {
        "TravellerIdentifier": "1",
        "TravellerTitle": "Mrs",
        "GivenName": "Turonga",
        "Surname": "Leela",
        "AgeBand": "Adult",
        "LeadTraveller": "true"
      },
      {
        "TravellerIdentifier": "2",
        "TravellerTitle": "Ms",
        "GivenName": "Tamy",
        "Surname": "Leela",
        "AgeBand": "Child",
        "LeadTraveller": "false"
      }
    ],
    "TravellerMix": {
      "Adult": "1",
      "Child": "1",
      "Youth": "0",
      "Infant": "0",
      "Senior": "0",
      "Total": "2"
    },
    "RequiredInfo": {
      "Question": [
        {
          "QuestionText": "Passport No.",
          "QuestionAnswer": "L99999"
        },
        {
          "QuestionText": "Weight",
          "QuestionAnswer": "50 Kg"
        }
      ]
    },
    "SpecialRequirement": "Vegetarian Meal",
    "PickupPoint": "Hilton Sydney",
    "ContactDetail": {
      "ContactType": "ALTERNATE",
      "ContactName": "Turonga Leela",
      "ContactValue": "US+1 999999999"
    },
    "ContactEmail": "MSG-8b17fa92-7b35-4fdb-9f18-f8a69252e019+BR-999999999@expmessaging.tripadvisor.com",
    "AvailabilityHoldReference": "1K883383K2S12K883383K2S57K883383K2"
  }
}

Booking response¶

Tag	Parent tag	Description	Optionality
`BookingResponse`		Root element	Mandatory
`ApiKey`	`BookingResponse`	String representing key used to identify the requester - key is provided by supplier	Mandatory
`ResellerId`	`BookingResponse`	Unique identifier for Viator.	Mandatory
`SupplierId`	`BookingResponse`	String representing unique supplier identifier within Viator's systems.	Mandatory
`ExternalReference`	`BookingResponse`	String representing unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`BookingResponse`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`BookingResponse`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only.	Optional
`Parameter`	`BookingResponse`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and supplier.	Optional
`Name`	`Parameter`	String representing key of key value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing value of key /value pair.	Mandatory (when `Parameter` element is used)
`RequestStatus`	`BookingResponse`	Request status root element. Holds the status information for the requested transaction	Mandatory
`Status`	`RequestStatus`	Status of the request. Valid values are: SUCCESS for a successful transaction, or ERROR for unsuccessful transaction. (Error node must be populated. Some root elements may be omitted in this case, e.g. `TransactionStatus`, `SupplierConfirmationNumber`)	Mandatory
`Error`	`RequestStatus`	Error root element.	Optional (Mandatory when `Status` = Error)
`ErrorCode`	`Error`	String representing the error code.	Mandatory (when `Error` element is used)
`ErrorMessage`	`Error`	String representing the error message in friendly format.	Optional
`ErrorDetails`	`Error`	String representing the technical error cause and details.	Optional
`BookingReference`	`BookingResponse`	String representing a unique booking identifier within the Viator's systems.	Optional
`SupplierCommentCustomer`	`BookingResponse`	String representing a supplier's comment for the customer.	Optional
`TourBarcode`	`BookingResponse`	String representing the supplier desired barcode on the customers voucher. The code is printed as per prior agreement with the supplier. Barcode is at itinerary level (single barcode irrespective of number of passengers).	Optional
`Traveller`	`BookingResponse`	Traveller root element. Contains booking confirmation details at traveller level.	Optional
`TravellerIdentifier`	`Traveller`	Integer representing unique identifier per traveller for the booking.	Mandatory (when `Traveller` element used)
`TravellerSupplierConfirmationNumber`	`Traveller`	String representing the supplier's booking confirmation number per traveller. Number is at traveller level and is unique amongst travellers in the booking. The `TravellerSupplierConfirmationNumber` value can be used to print per person barcodes on vouchers (if previously agreed with supplier).	Optional
`TravellerBarcode`	`Traveller`	String representing the supplier desired barcode on the customer voucher for a specific traveller. The code is printed as per prior agreement with the supplier. Barcode is at itinerary/traveller level (each traveller will have individual barcode).	Optional
`TravellerSeat`	`Traveller`	String representing the seat number assigned to the traveller. The full representation of the seat should be used, this includes any gate, row and seat information that must appear on the travellers voucher or ticket. This information should clearly instruct the traveller of the seat location.	Optional
`TransactionStatus`	`BookingResponse`	Transaction status root element. Holds information about the status of the booking; i.e., whether it is confirmed or rejected, and why.	Mandatory (unless `RequestStatus` is ERROR)
`Status`	`TransactionStatus`	Status of the transactions. Valid values are: CONFIRMED REJECTED	Mandatory
`RejectionReasonDetails`	`TransactionStatus`	String representing the extended details pertaining to the reason the transaction was rejected and additional information (i.e. alternatives).	Optional (mandatory when `Status` = REJECTED)
`RejectionReason`	`TransactionStatus`	Reason transaction was rejected. Valid values are: NOT_OPERATING - tour is not operating on the date for which the booking was made. BOOKED_OUT_ALT_DATES - tour is booked out but alternative dates will be provided in the `RejectionReasonDetails` BOOKED_OUT_ALT_TIMES - tour is booked out but alternative times will be provided in the `RejectionReasonDetails`. OTHER - Any other reason. Details must be provided in `RejectionReasonDetails`.	Optional (mandatory when `Status` = REJECTED)
`SupplierConfirmationNumber`	`BookingResponse`	String representing the supplier's booking confirmation number per booking itinerary. Number is at itinerary level (single confirmation number irrespective of number of passengers). The `SupplierConfirmationNumber` is used in all subsequent requests pertaining to the booking (i.e. amendments, cancellations, etc.) to identify the booking in the suppliers system.	Mandatory (optional when `Status` = REJECTED or `RequestStatus` is ERROR)
`TourTicket`	`BookingResponse`	The ticket for this booking	Optional
`MimeType`	`TourTicket`	The MIME type for this ticket URL. Valid values are: application/pdf	Mandatory
`Url`	`TourTicket`	The URL for the ticket itself	Mandatory

Booking response sample with barcode¶

The sample below represents the supplier response for the booking request described in the Booking Request sample. Note that this supplier returns a barcode for each traveller. It is also possible to return a barcode at the itinerary level. Supplier confirmation number is provided at the itinerary level for this supplier.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BookingResponse xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992645</ExternalReference>
  <Timestamp>2013-07-25T13:30:53.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <RequestStatus>
    <Status>SUCCESS</Status>
  </RequestStatus>
  <BookingReference>999999999</BookingReference>
  <SupplierCommentCustomer>Customer is advised that space for large luggage will cost and additional AUD20.00</SupplierCommentCustomer>
  <TourBarcode />
  <Traveller>
    <TravellerIdentifier>1</TravellerIdentifier>
    <TravellerSupplierConfirmationNumber />
    <TravellerSeat />
    <TravellerBarcode>9990009990009999000</TravellerBarcode>
  </Traveller>
  <Traveller>
    <TravellerIdentifier>2</TravellerIdentifier>
    <TravellerSupplierConfirmationNumber />
    <TravellerSeat />
    <TravellerBarcode>9990009990009999001</TravellerBarcode>
  </Traveller>
  <TransactionStatus>
    <Status>CONFIRMED</Status>
  </TransactionStatus>
  <SupplierConfirmationNumber>CN123456</SupplierConfirmationNumber>
</BookingResponse>

JSON:

{
  "responseType": "BookingResponse",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992645",
    "Timestamp": "2013-07-25T13:30:53.616+10:00",
    "Extension": {},
    "Parameter": {},
    "RequestStatus": {
      "Status": "SUCCESS"
    },
    "BookingReference": "999999999",
    "SupplierCommentCustomer": "Customer is advised that space for large luggage will cost and additional AUD20.00",
    "Traveller": [
      {
        "TravellerIdentifier": "1",
        "TravellerSupplierConfirmationNumber": "",
        "TravellerSeat": "",
        "TravellerBarcode": "9990009990009999000"
      },
      {
        "TravellerIdentifier": "2",
        "TravellerSupplierConfirmationNumber": "",
        "TravellerSeat": "",
        "TravellerBarcode": "9990009990009999001"
      }
    ],
    "TransactionStatus": {
      "Status": "CONFIRMED"
    },
    "SupplierConfirmationNumber": "CN123456"
  }
}

Booking response sample with barcode¶

The sample below represents the supplier response for the booking request described in the Booking Request sample. Note that this supplier returns a ticket for the tour. The supplier confirmation number is provided at the itinerary level for this supplier.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BookingResponse xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992645</ExternalReference>
  <Timestamp>2013-07-25T13:30:53.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <RequestStatus>
    <Status>SUCCESS</Status>
  </RequestStatus>
  <BookingReference>999999999</BookingReference>
  <SupplierCommentCustomer>Customer is advised that space for large luggage will cost and additional AUD20.00</SupplierCommentCustomer>
  <TourBarcode />
  <Traveller>
    <TravellerIdentifier>1</TravellerIdentifier>
    <TravellerSupplierConfirmationNumber />
    <TravellerSeat />
  </Traveller>
  <Traveller>
    <TravellerIdentifier>2</TravellerIdentifier>
    <TravellerSupplierConfirmationNumber />
    <TravellerSeat />
  </Traveller>
  <TransactionStatus>
    <Status>CONFIRMED</Status>
  </TransactionStatus>
  <SupplierConfirmationNumber>CN123456</SupplierConfirmationNumber>
  <TourTicket>
    <MimeType>application/pdf</MimeType>
    <Url>http://example.org/9990009990009999000/ticket.pdf</Url>
  </TourTicket>
</BookingResponse>

JSON:

{
  "responseType": "BookingResponse",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992645",
    "Timestamp": "2013-07-25T13:30:53.616+10:00",
    "Extension": {},
    "Parameter": {},
    "RequestStatus": {
      "Status": "SUCCESS"
    },
    "BookingReference": "999999999",
    "SupplierCommentCustomer": "Customer is advised that space for large luggage will cost and additional AUD20.00",
    "Traveller": [
      {
        "TravellerIdentifier": "1",
        "TravellerSupplierConfirmationNumber": "",
        "TravellerSeat": ""
      },
      {
        "TravellerIdentifier": "2",
        "TravellerSupplierConfirmationNumber": "",
        "TravellerSeat": ""
      }
    ],
    "TransactionStatus": {
      "Status": "CONFIRMED"
    },
    "SupplierConfirmationNumber": "CN123456",
    "TourTicket": {
      "MimeType": "application/pdf",
      "Url": "http://example.org/9990009990009999000/ticket.pdf"
    }
  }
}

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 suppliers system and return a success message to Viator systems. Each API call is always for an amendment to a single booking only.

The following sections provide details regarding the request and response formats.

Booking amendment request¶

Tag	Parent Tag	Description	Optionality
`BookingAmendmentRequest`		Root element	Mandatory
`ApiKey`	`BookingAmendmentRequest`	String representing key used to identify the requester - key is provided by supplier	Mandatory
`ResellerId`	`BookingAmendmentRequest`	Unique identifier for Viator.	Mandatory
`SupplierId`	`BookingAmendmentRequest`	String representing unique supplier identifier within Viator's systems.	Mandatory
`ExternalReference`	`BookingAmendmentRequest`	String representing unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`BookingAmendmentRequest`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`BookingAmendmentRequest`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only.	Optional
`Parameter`	`BookingAmendmentRequest`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and supplier.	Optional
`Name`	`Parameter`	String representing key of key/value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing value of key/value pair.	Mandatory (when `Parameter` element is used)
`BookingReference`	`BookingAmendmentRequest`	String representing a unique booking identifier within the Viator's systems.	Mandatory
`TravelDate`	`BookingAmendmentRequest`	The date of travel for the itinerary item. Date should be in date format YYYY-MM-DD. Example: 2000-01-31	Mandatory
`SupplierProductCode`	`BookingAmendmentRequest`	String representing supplier's unique product (tour) code (identifier). This code will be used across multiple API calls. Maximum length: 50 characters	Mandatory
`Location`	`BookingAmendmentRequest`	String representing the city and country that the tour is in.	Optional
`TourOptions`	`BookingAmendmentRequest`	Tour option root element. Holds details pertaining to each of the tour options (including default if not tour options exist).	Optional
`SupplierOptionCode`	`TourOptions`	String representing supplier's tour option code (identifier). An option is a version of the tour and each option must have a unique code. Examples: A tour that is conducted by a Spanish guide and also by an English guide has two options. A tour that has a luxurious version and a cheaper version is considered to have two options. A list of the supplier's product options can be provided by Viator for mapping purposes	Optional
`SupplierOptionName`	`TourOptions`	String representing the product option (tour option) name (name associated with supplier option code).	Optional
`TourDepartureTime`	`TourOptions`	Time of tour departure. Values should be in time format. Example: `09:00:00`. Note: A tour that runs three times throughout the day (as the same tour option) will have three different `TourDepartureTime` elements.	Optional
`Option`	`TourOptions`	Option root element. Contains additional information used to aid with the mapping of Viator tour options to supplier products when an supplier option code is not available.	Optional
`Name`	`Option`	String representing the option name.	Mandatory (when `Option` element used)
`Value`	`Option`	String representing the option value.	Mandatory (when `Option` element used)
`Inclusions`	`BookingAmendmentRequest`	Root element for inclusions. Contains inclusions in the product (tour) / product option (tour option) offering.	Optional
`Inclusion`	`Inclusions`	String representing an inclusion of the product offering.	Optional
`CurrencyCode`	`BookingAmendmentRequest`	ISO 4217 three-letter currency code associated with the booking price. ISO 4217 is the International Standard for currency codes. For more information visit iso.org.	Optional
`Amount`	`BookingAmendmentRequest`	Numeric value for the booking net price paid to the supplier; e.g., "550.00"	Optional
`Traveller`	`BookingAmendmentRequest`	Root element for traveller. Contains traveller information for the booking.	Mandatory
`TravellerIdentifier`	`Traveller`	Integer representing unique identifier per traveller for the booking.	Mandatory
`TravellerTitle`	`Traveller`	String representing the title of the traveller.	Optional
`GivenName`	`Traveller`	String representing the traveler's given name.	Mandatory
`Surname`	`Traveller`	String representing the traveler's surname.	Mandatory
`AgeBand`	`Traveller`	Age band of traveler. Valid values include: Adult Child Youth Infant Senior Traveler age bands are based on supplier provided age ranges.	Mandatory
`LeadTraveller`	`Traveller`	Boolean value ('true' or 'false') that specifies whether this traveller should be considered the 'lead traveller'.	Optional
`TravellerMix`	`BookingAmendmentRequest`	Traveler mix root element. Holds the number of travelers at each age band for which availability is being requested. If not specified, then overall availability is requested. Traveler age bands are based on supplier	Optional
`Adult`	`TravellerMix`	Number of adults.	Optional
`Child`	`TravellerMix`	Number of children.	Optional
`Youth`	`TravellerMix`	Number of youths.	Optional
`Infant`	`TravellerMix`	Number of infants.	Optional
`Senior`	`TravellerMix`	Number of seniors.	Optional
`Total`	`TravellerMix`	Total number of travellers.	Optional
`RequiredInfo`	`BookingAmendmentRequest`	Required information root element. Holds both question and answers of supplier required information.	Optional
`Question`	`RequiredInfo`	Question root element. Holds question and answer text.	Optional
`QuestionText`	`RequiredInfo`	String representing the question asked to the customer to obtain required information.	Mandatory (when `Question` element used)
`QuestionAnswer`	`RequiredInfo`	String representing the customers answer to the question.	Mandatory (when `Question` element used)
`SpecialRequirement`	`BookingAmendmentRequest`	String representing a special requirement from the customer (max. 169 characters including spaces)	Optional
`PickupPoint`	`BookingAmendmentRequest`	String representing the customer pickup point for the tour. Only pickup points previously agreed to supplier are allowed.	Optional
`SupplierNote`	`BookingAmendmentRequest`	String representing a note to the supplier about the booking.	Optional
`AdditionalRemarks`	`BookingAmendmentRequest`	Additional remarks root element. Holds additional remarks to customers.	Optional
`Remark`	`AdditionalRemarks`	Remarks related to the booking. i.e: pricing rule	Optional
`ContactDetail`	`BookingAmendmentRequest`	Contact detail root element. Holds customer contact information.	Optional
`ContactType`	`ContactDetail`	Type of contact used for contacting customer while travelling. Valid values include: MOBILE ALTERNATE EMAIL NOT_CONTACTABLE	Mandatory (when `ContactDetail` element used)
`ContactName`	`ContactDetail`	String representing the name of the contact.	Mandatory (when `ContactDetail` element used)
`ContactValue`	`ContactDetail`	String representing the contact information (i.e phone number, email, etc).	Mandatory (when `ContactDetail` element used)
`SupplierConfirmationNumber`	`BookingAmendmentRequest`	String representing the supplier's booking confirmation number per booking itinerary. Number is at itinerary level (single confirmation number irrespective of number of passengers). The `SupplierConfirmationNumber` is used in all subsequent requests pertaining to the booking (i.e. amendments, cancellation, etc.) to identify the booking in the suppliers system.	Mandatory

Booking amendment request sample¶

The sample below is an amendment to the booking request sample. This amendment changes the booking from two people to a single person. Note that the amendment request contains the supplier confirmation number generated by the supplier when the booking was initially confirmed.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BookingAmendmentRequest xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992700</ExternalReference>
  <Timestamp>2013-07-26T13:30:52.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <BookingReference>999999999</BookingReference>
  <TravelDate>2014-12-10</TravelDate>
  <SupplierProductCode>BLUE</SupplierProductCode>
  <Location>Sydney, Australia</Location>
  <TourOptions>
    <SupplierOptionCode>BASIC</SupplierOptionCode>
    <SupplierOptionName>Basic Shared Accommodation</SupplierOptionName>
    <TourDepartureTime>09:00:00</TourDepartureTime>
    <Option>
      <Name>Room</Name>
      <Value>dualocc</Value>
    </Option>
  </TourOptions>
  <Inclusions>
    <Inclusion>Bottle of Champagne</Inclusion>
    <Inclusion>Hotel Pickup</Inclusion>
  </Inclusions>
  <CurrencyCode>AUD</CurrencyCode>
  <Amount>225.00</Amount>
  <Traveller>
    <TravellerIdentifier>1</TravellerIdentifier>
    <TravellerTitle>Mrs</TravellerTitle>
    <GivenName>Turonga</GivenName>
    <Surname>Leela</Surname>
    <AgeBand>Adult</AgeBand>
    <LeadTraveller>true</LeadTraveller>
  </Traveller>
  <TravellerMix>
    <Adult>1</Adult>
    <Child>0</Child>
    <Youth>0</Youth>
    <Infant>0</Infant>
    <Senior>0</Senior>
    <Total>1</Total>
  </TravellerMix>
  <RequiredInfo>
    <Question>
      <QuestionText>Passport No.</QuestionText>
      <QuestionAnswer>L99999</QuestionAnswer>
    </Question>
  </RequiredInfo>
  <SpecialRequirement>Vegetarian Meal</SpecialRequirement>
  <PickupPoint>Hilton Sydney</PickupPoint>
  <SupplierNote>Change to number of travellers. Customer reimbursed.</SupplierNote>
  <AdditionalRemarks>
    <Remark>Additional charges for large luggage may apply. To be advised at pickup.</Remark>
  </AdditionalRemarks>
  <ContactDetail>
    <ContactType>MOBILE</ContactType>
    <ContactName>Turonga Leela</ContactName>
    <ContactValue>US+1 999999999</ContactValue>
  </ContactDetail>
  <SupplierConfirmationNumber>CN123456</SupplierConfirmationNumber>
</BookingAmendmentRequest>

JSON:

{
  "requestType":"BookingAmendmentRequest",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992700",
    "Timestamp": "2013-07-26T13:30:52.616+10:00",
    "Extension": {},
    "Parameter": {},
    "BookingReference": "999999999",
    "TravelDate": "2014-12-10",
    "SupplierProductCode": "BLUE",
    "Location": "Sydney, Australia",
    "TourOptions": {
      "SupplierOptionCode": "BASIC",
      "SupplierOptionName": "Basic Shared Accommodation",
      "TourDepartureTime": "09:00:00",
      "Option": [
        {
          "Name": "Room",
          "Value": "dualocc"
        }
      ]
    },
    "Inclusions": {
      "Inclusion": [
        "Bottle of Champagne",
        "Hotel Pickup"
      ]
    },
    "CurrencyCode": "AUD",
    "Amount": "225.00",
    "Traveller": [
      {
        "TravellerIdentifier": "1",
        "TravellerTitle": "Mrs",
        "GivenName": "Turonga",
        "Surname": "Leela",
        "AgeBand": "Adult",
        "LeadTraveller": "true"
      }
    ],
    "TravellerMix": {
      "Adult": "1",
      "Child": "0",
      "Youth": "0",
      "Infant": "0",
      "Senior": "0",
      "Total": "1"
    },
    "RequiredInfo": {
      "Question": [
        {
          "QuestionText": "Passport No.",
          "QuestionAnswer": "L99999"
        }
      ]
    },
    "SpecialRequirement": "Vegetarian Meal",
    "PickupPoint": "Hilton Sydney",
    "SupplierNote": "Change to number of travellers. Customer reimbursed.",
    "AdditionalRemarks": {
      "Remark": "Additional charges for large luggage may apply. To be advised at pickup."
    },
    "ContactDetail": {
      "ContactType": "MOBILE",
      "ContactName": "Turonga Leela",
      "ContactValue": "US+1 999999999"
    },
    "SupplierConfirmationNumber": "CN123456"
  }
}

Booking amendment response¶

Tag	Parent tag	Description	Optionality
`BookingAmendmentResponse`		Root element	Mandatory
`ApiKey`	`BookingAmendmentResponse`	String representing key used to identify the requester - key is provided by supplier	Mandatory
`ResellerId`	`BookingAmendmentResponse`	Unique identifier for Viator.	Mandatory
`SupplierId`	`BookingAmendmentResponse`	String representing unique supplier identifier within Viator's systems.	Mandatory
`ExternalReference`	`BookingAmendmentResponse`	String representing unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`BookingAmendmentResponse`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`BookingAmendmentResponse`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only.	Optional
`Parameter`	`BookingAmendmentResponse`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and supplier.	Optional
`Name`	`Parameter`	String representing key of key/value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing value of key/value pair.	Mandatory (when `Parameter` element is used)
`RequestStatus`	`BookingAmendmentResponse`	Request status root element. Holds the status information for the requested transaction	Mandatory
`Status`	`RequestStatus`	Status of the request. Valid values are: SUCCESS for a successful transaction, or ERROR for unsuccessful transaction. (Error node must be populated. Some root elements may be omitted in this case, e.g. `TransactionStatus`)	Mandatory
`Error`	`RequestStatus`	Error root element.	Optional
`ErrorCode`	`Error`	String representing the Error code.	Mandatory (when `Error` element is used)
`ErrorMessage`	`Error`	String representing the error message in friendly format.	Optional
`ErrorDetails`	`Error`	String representing the technical error cause and details.	Optional
`BookingReference`	`BookingAmendmentResponse`	String representing a unique booking identifier within the Viator's systems.	Optional
`SupplierCommentCustomer`	`BookingAmendmentResponse`	String representing a supplier's comment for the customer.	Optional
`TourBarcode`	`BookingAmendmentResponse`	String representing the supplier's desired barcode on the customers voucher. The code is printed as per prior agreement with the supplier. Barcode is at itinerary level (single barcode irrespective of number of passengers).	Optional
`Traveller`	`BookingAmendmentResponse`	Traveller root element. Contains booking confirmation details at traveller level.	Optional
`TravellerIdentifier`	`Traveller`	Integer representing unique identifier per traveller for the booking.	Mandatory (when `Traveller` element used)
`TravellerSupplier`	`ConfirmationNumber`	Traveller string representing the supplier's booking confirmation number per traveller. Number is at traveller level and is unique amongst travellers in the booking.	Optional
`TravellerBarcode`	`Traveller`	String representing the supplier's desired barcode on the customer voucher for a specific traveller. The code is printed as per prior agreement with the supplier. Barcode is at itinerary/traveller level (each traveller will have individual barcode).	Optional
`TravellerSeat`	`Traveller`	String representing the seat number assigned to the traveller. The full representation of the seat should be used, this includes any gate, row and seat information that must appear on the travellers voucher or ticket. This information should clearly instruct the traveller of the seat location.	Optional
`TransactionStatus`	`BookingAmendmentResponse`	Transaction status root element. Holds information about the status of the booking; i.e., whether it is confirmed or rejected, and why.	Mandatory (unless `RequestStatus` is ERROR)
`Status`	`TransactionStatus`	Status of the transactions. Valid values are: CONFIRMED REJECTED	Mandatory
`RejectionReasonDetails`	`TransactionStatus`	String representing the extended details pertaining to the reason the transaction was rejected and additional information (i.e. alternatives).	Optional (mandatory when `Status` = REJECTED)
`RejectionReason`	`TransactionStatus`	Reason transaction was rejected. Valid values are: NOT_OPERATING - tour is not operating on the date for which the booking was made. BOOKED_OUT_ALT_DATES - tour is booked out but alternative dates will be provided in the `RejectionReasonDetails` BOOKED_OUT_ALT_TIMES - tour is booked out but alternative times will be provided in the `RejectionReasonDetails`. OTHER - Any other reason. Details must be provided in `RejectionReasonDetails`.	Optional (mandatory when `Status` = REJECTED)
`SupplierConfirmationNumber`	`BookingAmendmentResponse`	String representing the supplier's booking confirmation number per booking itinerary. Number is at itinerary level (single confirmation number irrespective of number of passengers). The `SupplierConfirmationNumber` is used in all subsequent requests pertaining to the booking (i.e. amendments, cancellations, etc.) to identify the booking in the suppliers system. NOTE: `SupplierConfirmationNumber` must be the same number the original booking response `SupplierConfirmationNumber`.	Optional

Booking amendment response sample¶

The sample below represents the supplier response to the booking amendment request created in the booking amendment request sample. Note the SupplierConfirmationNumber remains the same as that in the original booking confirmation.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BookingAmendmentResponse xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>9999</SupplierId>
  <ExternalReference>10051374722992700</ExternalReference>
  <Timestamp>2013-07-26T13:30:53.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <RequestStatus>
    <Status>SUCCESS</Status>
  </RequestStatus>
  <BookingReference>999999999</BookingReference>
  <SupplierCommentCustomer />
  <TourBarcode />
  <Traveller>
    <TravellerIdentifier>1</TravellerIdentifier>
    <TravellerSupplierConfirmationNumber />
    <TravellerSeat />
    <TravellerBarcode>9990009990009999000</TravellerBarcode>
  </Traveller>
  <TransactionStatus>
    <Status>CONFIRMED</Status>
  </TransactionStatus>
  <SupplierConfirmationNumber>CN123456</SupplierConfirmationNumber>
</BookingAmendmentResponse>

JSON:

{
  "responseType": "BookingAmendmentResponse",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "9999",
    "ExternalReference": "10051374722992700",
    "Timestamp": "2013-07-26T13:30:53.616+10:00",
    "Extension": {},
    "Parameter": {},
    "RequestStatus": {
      "Status": "SUCCESS"
    },
    "BookingReference": "999999999",
    "SupplierCommentCustomer": "",
    "TourBarcode": "",
    "Traveller": [
      {
        "TravellerIdentifier": "1",
        "TravellerSupplierConfirmationNumber": "",
        "TravellerSeat": "",
        "TravellerBarcode": "9990009990009999000"
      }
    ],
    "TransactionStatus": {
      "Status": "CONFIRMED"
    },
    "SupplierConfirmationNumber": "CN123456"
  }
}

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.

Booking cancellation request¶

Tag	Parent tag	Description	Optionality
`BookingCancellationRequest`		Root element	Mandatory
`ApiKey`	`BookingCancellationRequest`	String representing Key used to identify the requester - key is provided by supplier	Mandatory
`ResellerId`	`BookingCancellationRequest`	Unique identifier for Viator.	Mandatory
`SupplierId`	`BookingCancellationRequest`	String representing Unique supplier identifier within Viator system.	Mandatory
`ExternalReference`	`BookingCancellationRequest`	String representing unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`BookingCancellationRequest`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`BookingCancellationRequest`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only.	Optional
`Parameter`	`BookingCancellationRequest`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and supplier.	Optional
`Name`	`Parameter`	String representing key of key/value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing value of key/value pair.	Mandatory (when `Parameter` element is used)
`BookingReference`	`BookingCancellationRequest`	String representing a unique booking identifier within Viator's systems.	Mandatory
`SupplierConfirmationNumber`	`BookingCancellationRequest`	String representing the supplier's booking confirmation number per booking itinerary. Number is at itinerary level (single confirmation number irrespective of number of passengers) . The `SupplierConfirmationNumber` is used in all subsequent requests pertaining to the booking (i.e. amendments, cancellations, etc.) to identify the booking in the suppliers system.	Mandatory
`CancelDate`	`BookingCancellationRequest`	The date the cancellation was made. Date should be in date format. Example: 2000-01-31	Mandatory
`Author`	`BookingCancellationRequest`	String representing the person (or group) responsible for the cancellation.	Mandatory
`Reason`	`BookingCancellationRequest`	String representing the reason for the cancellation.	Mandatory
`SupplierNote`	`BookingCancellationRequest`	String representing a message (note) to the supplier.	Optional

Booking cancellation request sample¶

The sample below is a cancellation request for a previously confirmed booking (see booking request sample).

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BookingCancellationRequest xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992850</ExternalReference>
  <Timestamp>2013-12-01T13:30:53.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <BookingReference>999999999</BookingReference>
  <SupplierConfirmationNumber>CN123456</SupplierConfirmationNumber>
  <CancelDate>2013-12-01</CancelDate>
  <Author>Customer Service</Author>
  <Reason>No longer traveling</Reason>
  <SupplierNote>Refunded Customer</SupplierNote>
</BookingCancellationRequest>

JSON:

{
  "requestType":"BookingCancellationRequest",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992850",
    "Timestamp": "2013-12-01T13:30:53.616+10:00",
    "Extension": {},
    "Parameter": {},
    "BookingReference": "999999999",
    "SupplierConfirmationNumber": "CN123456",
    "CancelDate": "2013-12-01",
    "Author": "Customer Service",
    "Reason": "No longer traveling",
    "SupplierNote": "Refunded Customer"
  }
}

Booking cancellation response¶

Tag	Parent tag	Description	Optionality
`BookingCancellationResponse`		Root element	Mandatory
`ApiKey`	`BookingCancellationResponse`	String representing Key used to identify the requester - key is provided by supplier	Mandatory
`ResellerId`	`BookingCancellationResponse`	Unique identifier for Viator.	Mandatory
`SupplierId`	`BookingCancellationResponse`	String representing unique supplier identifier within Viator system.	Mandatory
`ExternalReference`	`BookingCancellationResponse`	String representing unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`BookingCancellationResponse`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`BookingCancellationResponse`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and supplier only.	Optional
`Parameter`	`BookingCancellationResponse`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and supplier.	Optional
`Name`	`Parameter`	String representing key of key/value pair.	Mandatory (when `Parameter` element is used)
`Value`	`Parameter`	String representing value of key/value pair.	Mandatory (when `Parameter` element is used)
`RequestStatus`	`BookingCancellationResponse`	Request status root element. Holds the status information for the requested transaction.	Mandatory
`Status`	`RequestStatus`	Status of the request. Valid values are: SUCCESS for a successful transaction, or ERROR for unsuccessful transaction. (Error node must be populated. Some root elements may be omitted in this case, e.g. `TransactionStatus`)	Mandatory
`Error`	`RequestStatus`	Error root element.	Optional (Mandatory when `Status` = Error)
`ErrorCode`	`Error`	String representing the error code.	Mandatory (when `Error` element is used)
`ErrorMessage`	`Error`	String representing the error message in friendly format.	Optional
`ErrorDetails`	`Error`	String representing the technical error cause and details.	Optional
`BookingReference`	`BookingCancellationResponse`	String representing a unique booking identifier within Viator's systems.	Optional
`SupplierConfirmationNumber`	`BookingCancellationResponse`	String representing the supplier's booking confirmation number per booking itinerary. Number is at itinerary level (single confirmation number irrespective of number of passengers) . The `SupplierConfirmationNumber` is used in all subsequent requests pertaining to the booking (i.e. amendments, cancellations, etc.) to identify the booking in the suppliers system.	Optional
`SupplierCancellationNumber`	`BookingCancellationResponse`	String representing the supplier's unique cancellation confirmation number. Number is at itinerary level (single cancellation number irrespective of number of passengers) and serves as a reference to the cancellation in the suppliers system.	Optional
`TransactionStatus`	`BookingCancellationResponse`	Transaction status root element. Holds information about the status of the booking; i.e., whether it is confirmed or rejected, and why.	Mandatory (unless `RequestStatus` is ERROR)
`Status`	`TransactionStatus`	Status of the transactions. Valid values are: CONFIRMED REJECTED	Mandatory
`RejectionReasonDetails`	`TransactionStatus`	String representing the extended details pertaining to the reason the transaction was rejected and additional information (i.e. alternatives).	Optional (mandatory when `Status` = REJECTED)
`RejectionReason`	`TransactionStatus`	Reason transaction was rejected. Valid values are: PAST_CANCEL_DATE - Allowed cancellation date is in the past. PAST_TOUR_DATE - tour date is in the past. TOUR_REDEEMED - tour has already been redeemed. OTHER - Any other reason. Details must be provided in `RejectionReasonDetails`.	Optional (mandatory when `Status` = REJECTED)

Booking cancellation response sample¶

The sample below represents the supplier response for a cancellation request. Note that a SupplierCancellationNumber has been provided.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<BookingCancellationResponse xmlns="http://toursgds.com/api/01">
  <ApiKey>cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>1004</SupplierId>
  <ExternalReference>10051374722992850</ExternalReference>
  <Timestamp>2013-12-01T13:30:54.616+10:00</Timestamp>
  <Extension>
    <any />
  </Extension>
  <Parameter>
    <Name />
    <Value />
  </Parameter>
  <RequestStatus>
    <Status>SUCCESS</Status>
  </RequestStatus>
  <BookingReference>999999999</BookingReference>
  <SupplierConfirmationNumber>CN123456</SupplierConfirmationNumber>
  <SupplierCancellationNumber>CANCEL78910</SupplierCancellationNumber>
  <TransactionStatus>
    <Status>CONFIRMED</Status>
  </TransactionStatus>
</BookingCancellationResponse>

JSON:

{
  "responseType": "BookingCancellationResponse",
  "data": {
    "ApiKey": "cdqu60CykKeca1Qc000VXwgchV000L2fNOOf0bv9gPp",
    "ResellerId": "1000",
    "SupplierId": "1004",
    "ExternalReference": "10051374722992850",
    "Timestamp": "2013-12-01T13:30:54.616+10:00",
    "Extension": {},
    "Parameter": {},
    "RequestStatus": {
      "Status": "SUCCESS"
    },
    "BookingReference": "999999999",
    "SupplierConfirmationNumber": "CN123456",
    "SupplierCancellationNumber": "CANCEL78910",
    "TransactionStatus": {
      "Status": "CONFIRMED"
    }
  }
}

Viator-built services¶

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.

Availability notification 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.

Note that for this API, the request is sent to Viator and the response is received from Viator.

Availability notification request¶

Tag	Parent tag	Description	Optionality
`AvailabilityNotification2Request`		Root element	Mandatory
`ApiKey`	`AvailabilityNotification2Request`	String representing Key used to identify the requester.	Mandatory
`ResellerId`	`AvailabilityNotification2Request`	Unique identifier for Viator.	Mandatory
`SupplierId`	`AvailabilityNotification2Request`	String representing the unique supplier identifier within Viator's systems.	Mandatory
`ExternalReference`	`AvailabilityNotification2Request`	String representing Unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`AvailabilityNotification2Request`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`AvailabilityNotification2Request`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and Supplier only.	Optional
`Parameter`	`AvailabilityNotification2Request`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and Supplier.	Optional
`Name`	`Parameter`	Parameter name. String representing Key of Key Value pair. i.e. the name/label/key to identify the parameter	Mandatory (when Parameter element is used)
`Value`	`Parameter`	Parameter value. String representing Value of Key Value pair. i.e. the value identified by the key	Mandatory (when Parameter element is used)
`VariantAvailability`	`AvailabilityNotification2Request`	Changed availability root element. This element contains a `SupplierProductCode`, associated `TourOptions` and a list of `DateAvailability` items.	Mandatory
`SupplierProductCode`	`VariantAvailability`	String representing the supplier's unique product (tour) code (identifier).	Mandatory
`TourOptions`	`VariantAvailability`	Tour option (product option) root element. This should be the same `TourOptions` as given in your `TourListResponse`. This is used to identify one sellable item.	Optional
`SupplierOptionCode`	`TourOptions`	String representing supplier's product (tour) option code (identifier). An option is a version of the tour and each option must have a unique code. Examples: A Tour that is conducted by a Spanish guide and also by an English guide has two options. A Tour that starts at 3 different times throughout the day may have three options. This could be because each start time is priced differently or because availability is limited for each starting time. A Tour that has a luxurious version and a cheaper version is considered to have two options. These are options that have the same availability status for the specified date.	Optional
`TourDepartureTime`	`TourOptions`	Time of Tour Departure. Values should be in time format. Example: 09:00:00	Optional
`Option`	`TourOptions`	Option root element. Contains additional information used to aid with the mapping of Viator tour options to supplier products when an supplier option code is not available.	Optional
`Name`	`Option`	String representing the Option Name.	Mandatory (when Option element used)
`Value`	`Option`	String representing the Option Value.	Mandatory (when Option element used)
`DateAvailability`	`VariantAvailability`	Contains the list of updated dates and their associated updated availability statuses.	Mandatory
`Date`	`DateAvailability`	The date for which the availability has changed. Date should be in date format. Example: 2000-01-31	Mandatory
`AvailabilityStatus`	`DateAvailability`	Availability status root element.	Mandatory
`Status`	`AvailabilityStatus`	Status of availability. Valid values include: AVAILABLE - when product is available UNAVAILABLE - when product is not available	Mandatory
`UnavailabilityReason`	`AvailabilityStatus`	Reason why product is not available. Valid values include: SOLD_OUT - when the product (Tour)/ product option (Tour Option) is sold out. When this reason code is received, the product or product option become unavailable for sale on Viator systems. BLOCKED_OUT - when the product (Tour)/ product option (Tour Option) has been blocked out (not taking place on this date). When this reason code is received, the product or product option become unavailable for sale on Viator systems. INACTIVE - when the product (Tour)/ product option (Tour Option) is no longer active. When this reason code is received, the product or product option become unavailable for sale on Viator systems. PAST_CUTOFF_DATE - when the booking cut-off date has been reach for this product (Tour)/ product option (Tour Option). When this reason code is received, the product or product option become unavailable for sale on Viator systems. TRAVELLER_MISMATCH - when the required combination of travellers for this product (Tour)/ product option (Tour Option) is not met or when the number of requested passengers cannot be fulfilled, but a lower number can (i.e. availability status for 3 people is unavailable, but availability status for 2 is available). NO_EVENT - This event is not longer valid. When this reason code is received, the product or product option become unavailable for sale on Viator systems.	Optional (mandatory when Status = UNAVAILABLE)
`VersionTag`	`DateAvailability`	Version tag root element. Specifies the version for each changed `DateAvailability`. Version tagging allows availability responses to be tagged with one of: a time-stamp, a text-string, or a numeric identifier. Attaching this tag will allow our systems to determine which availability response should be taken as the most recent in the event that multiple availability responses for the same product arrive with differing information. Our systems will consider the availability response with the most recent timestamp, or highest textual or numeric value as the authoritative response. Note: This should be when the availability change happened in your system, not when the notification is generated.	Optional
`Timestamp`	`VersionTag`	Timestamp for when the availability changed in your system; e.g. `2021-12-02T12:34:56.789012345Z`	Optional
`Textual`	`VersionTag`	Text string of your choosing. Our systems will consider the highest-value string to be the latest change. E.g., `20121202-V000000231434`	Optional
`Numeric`	`VersionTag`	Numeric value of your choosing. Our systems will consider the highest number to be the latest change. E.g., `553957349573498`	Optional

Availability notification request sample 1¶

XML:

<AvailabilityNotification2Request xmlns="http://toursgds.com/api/01">
    <ApiKey>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxx</ApiKey>
    <SupplierId>1431720</SupplierId>
    <ResellerId>1000</ResellerId>
    <ExternalReference>10061374722913835</ExternalReference>
    <Timestamp>2021-04-06T10:14:37.682Z</Timestamp>
    <VariantAvailability>
        <SupplierProductCode>6470</SupplierProductCode>
        <TourOptions>
            <SupplierOptionCode>r11811</SupplierOptionCode>
            <TourDepartureTime>09:00:00</TourDepartureTime>
            <Option>
                <Name/>
                <Value/>
            </Option>
        </TourOptions>
        <DateAvailability>
            <Date>2021-04-06</Date>
            <AvailabilityStatus>
                <Status>UNAVAILABLE</Status>
                <UnavailabilityReason>SOLD_OUT</UnavailabilityReason>
            </AvailabilityStatus>
            <VersionTag>
                <Timestamp>2021-04-06T10:14:37.682Z</Timestamp>
            </VersionTag>
        </DateAvailability>
    </VariantAvailability>
</AvailabilityNotification2Request>

JSON:

{
  "requestType":"AvailabilityNotification2Request",
  "data": {
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxx",
    "SupplierId": "1431720",
    "ResellerId": "1000",
    "ExternalReference": "10061374722913835",
    "Timestamp": "2021-04-06T10:14:37.682Z",
    "VariantAvailability": {
      "SupplierProductCode": "6470",
      "TourOptions": {
        "SupplierOptionCode": "r11811",
        "TourDepartureTime": "09:00:00"
      },
      "DateAvailability": [
        {
          "Date": "2021-04-06",
          "AvailabilityStatus": {
            "Status": "UNAVAILABLE",
            "UnavailabilityReason": "SOLD_OUT"
          },
          "VersionTag": {
            "Timestamp": "2021-04-06T10:14:37.682Z"
          }
        }
      ]
    }
  }
}

Availability notification request sample 2¶

XML:

<AvailabilityNotification2Request xmlns="http://toursgds.com/api/01">
    <ApiKey>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxx</ApiKey>
    <ResellerId>1000</ResellerId>
    <SupplierId>1431720</SupplierId>
    <ExternalReference>skwon+test@2</ExternalReference>
    <Timestamp>2021-03-15T10:14:37.682Z</Timestamp>
    <VariantAvailability>
      <SupplierProductCode>6482</SupplierProductCode>
      <TourOptions>
        <SupplierOptionCode>r11828</SupplierOptionCode>
        <TourDepartureTime>08:00:00</TourDepartureTime>
        <Option>
          <Name>pickup</Name>
          <Value>Y</Value>
        </Option>
      </TourOptions>
      <DateAvailability>
        <Date>2021-03-15</Date>
        <AvailabilityStatus>
          <Status>UNAVAILABLE</Status>
          <UnavailabilityReason>SOLD_OUT</UnavailabilityReason>
        </AvailabilityStatus>
        <VersionTag>
          <Textual>2021-03-15T10:14:37.682Z</Textual>
        </VersionTag>
      </DateAvailability>
    </VariantAvailability>
</AvailabilityNotification2Request>

JSON:

{
  "requestType":"AvailabilityNotification2Request",
  "data": {
    "VariantAvailability": {
      "SupplierProductCode":"6482",
      "TourOptions": {
        "SupplierOptionCode":"r11828",
        "TourDepartureTime":"08:00:00",
          "Option":[
             {
                "Name":"pickup",
                "Value":"Y"
             }
          ]
        },
        "DateAvailability": [ 
          {
              "Date":"2021-03-15",
              "AvailabilityStatus":{
                 "Status":"UNAVAILABLE",
                 "UnavailabilityReason":"SOLD_OUT"
              },
              "VersionTag":{
                 "Textual":"2021-03-15T10:14:37.682Z"
              }
           }
        ]
     },
    "ApiKey":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxx",
    "ResellerId":"1000",
    "SupplierId":"1431720",
    "ExternalReference":"test@2",
    "Timestamp":"2021-03-15T10:14:37.682Z"
  }
}

Availability notification response¶

Tag	Parent tag	Description	Optionality
`AvailabilityNotification2Response`		Root element	Mandatory
`ApiKey`	`AvailabilityNotification2Response`	String representing Key used to identify the requester.	Mandatory
`ResellerId`	`AvailabilityNotification2Response`	Unique identifier for Viator.	Mandatory
`SupplierId`	`AvailabilityNotification2Response`	String representing Unique Supplier identifier within Viator system.	Mandatory
`ExternalReference`	`AvailabilityNotification2Response`	String representing Unique transaction identifier - unique across all transactions. Used in the response to identify the initial request.	Optional
`Timestamp`	`AvailabilityNotification2Response`	The time of creation of request. Date/time (timestamp) that requires timezone information along with date/time. The date should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) or yyyy-MM-ddTHH:mm:ss.SSS[+/-]hh:mm Example: 2013-04-28T13:10:12.123Z (UTC time) 2013-04-28T13:10:12.123+10:00	Mandatory
`Extension`	`AvailabilityNotification2Response`	Extension point that allows the addition of arbitrary element nodes. Any such elements can be used upon agreement between Viator and Supplier only.	Optional
`Parameter`	`AvailabilityNotification2Response`	Parametrized extension point root element. Holds key/value pair based extension points. Used only when agreed to by Viator and Supplier.	Optional
`Name`	`Parameter`	String representing Key of Key Value pair.	Mandatory (when Parameter element is used)
`Value`	`Parameter`	String representing Value of Key Value pair.	Mandatory (when Parameter element is used)
`RequestStatus`	`AvailabilityNotification2Response`	Request Status root element. Holds the status information for the requested transaction.	Mandatory
`Status`	`RequestStatus`	Status of the request. Valid values are: SUCCESS - for a successful transaction ERROR - for unsuccessful transaction. (Error node must be populated) PENDING – change is pending	Mandatory
`Error`	`RequestStatus`	Error root element.	Optional (Mandatory when Status = ERROR)
`ErrorCode`	`Error`	String representing the Error code.	Mandatory (when Error element is used)
`ErrorMessage`	`Error`	String representing the error message in friendly format.	Optional
`ErrorDetails`	`Error`	String representing the technical error cause and details.	Optional
`PendingReason`	`RequestStatus`	Stipulates a reason for why the availability was marked as PENDING	Optional (Mandatory when Status = PENDING)
`RetryAfter`	`RequestStatus`	The time when the next booking retry should occur. Date/time that requires timezone information along with date/time. The element should be in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ (in UTC time) example: 2013-04-28T13:10:12.120Z

Availability notification response sample¶

XML:

<?xml version="1.0" encoding="UTF-8"?>
<AvailabilityNotification2Response xmlns="http://toursgds.com/api/01">
  <ApiKey>xxxxx_xxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</ApiKey>
  <ResellerId>1000</ResellerId>
  <SupplierId>2000220</SupplierId>
  <ExternalReference>test@3</ExternalReference>
  <Timestamp>2021-04-06T10:14:37.682Z</Timestamp>
  <RequestStatus>
    <Status>SUCCESS</Status>
  </RequestStatus>
</AvailabilityNotification2Response>

JSON:

{
    "responseType": "AvailabilityNotification2Response",
    "data": {
        "ApiKey": "xxxxx_xxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "ResellerId": "1000",
        "SupplierId": "2000220",
        "ExternalReference": "test@3",
        "Timestamp": "2021-04-06T10:14:37.682Z",
        "RequestStatus": {
            "Status": "SUCCESS"
        }
    }
}

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.

Support¶

For questions regarding this document and the information contained within it or for help with Viator's Supplier APIs please email Viator API support.

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.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 clarfication 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