merchant api - viator partner api

Who is this guide for?

This article is designed to help merchant API partners using our V2 Merchant API correctly implement requirements for party sizes and passenger ages on their platforms.

Why correct implementation of age bands is important

Because Viator works with thousands of individual tour operators who offer unique experiences, our platform needs to be flexible enough to allow operators to set their own definitions for ages and acceptable party size/composition. These definitions are not uniform and often do not align with other travel products like hotels or flights.

What are age bands and passenger mix?

Age bands categorize travelers by age. For example, a museum tour may have separate rates for adults and children. Viator allows travelers to be classified as one of six age bands:

  • Adult
  • Child
  • Infant
  • Senior
  • Youth
  • Traveler (this is only used for products with per-unit pricing, like a boat or ATV rental)
age bands example

Passenger mix (also referred to as pax mix) is the party of travelers who make up a given booking. All products will have a minimum and maximum number of travelers allowed per booking, while some products set additional parameters, such as requiring at least one adult or senior present in order for a child to book.

Age bands and pax mix are set on a per product basis, meaning that they will have different definitions across different products. For example, product A may define an adult as a person aged 18-60, while product B considers an adult to be aged 12-99. In our APIs, the data for each product will include definitions of age bands, as well as parameters for acceptable passenger mixes.

Why do age bands and passenger mix need to be validated?

Tour operators may be unable to accommodate certain passenger mixes, while travelers may be under or over-charged if the price for their age group is incorrectly displayed on a partner’s platform. Invalid bookings will worsen the traveler’s experience.

How can you implement age bands and passenger mix?

Our merchant partners have developed a diverse array of platforms to suit their varied business models. Because different types of platforms will pose different UI requirements, the best way to implement age bands and passenger mix will depend on the particularities of your business. Broadly, partner implementations fall into two categories:

)

An experiences-only platform/vertical

This type of implementation is for a platform, or section of a larger platform, that is designed to handle only tours and activities, and includes the option to purchase only tours and activities. Viator.com is a great example of an experiences-only platform.

,

Adding experiences as part of a travel package

This type of implementation is for partners who need to include tours and activities as part of a larger travel package. Often, this package will include flights, hotels, and ground transport, along with tours and activities. Tripadvisor.com is an example of a site offering tours and activities as part of a larger package.

Age band and passenger mix on the front end

This section will outline how your API implementation should appear to the user.

)

Experiences-only platform

When designing the front end for an experiences-only platform, we recommend looking to the Viator.com site for best practices, as our platform has been thoroughly optimized.

Age bands and passenger mix should be selected on the product page, before checking the availability of the product. Valid age bands should be defined (eg. age 13-99), and the maximum number of total travelers and travelers of each age band should be displayed. Invalid passenger mixes should be unselectable, meaning that in the below example to the right, it should not be possible to to select more than nine travelers across all age bands.

Product search/selection: The user searches for and selects a product.

Product detail page: Once the user has selected a product, the full product details are displayed.

Select valid pax mix: On the product detail page, the user is prompted to select a valid passenger mix. 

Check real-time availability: Real-time availability is checked, to confirm that the tour/activity is available on the selected date for the selected passenger mix

Book: If the product is available, a booking is made, and booking confirmation and voucher are shared with the traveler.

,

Working with travel packages

When developing a platform to sell travel packages, it is important to remember that age bands and pax mix must be validated separately for each product. Optimally, this data should be collected and validated on the product detail page, but this can also be at the start if ages are specified.

At the experiences product level

If your system allows for it, we strongly recommend collecting and validating passenger mix on the product detail page. This type of implementation will follow the same user flow as an experiences-only platform, but the booking will then be added to a larger travel package. The user flow here could look something like this:

Select and book non-experiences offerings: The user will go through your standard processes to select and book non-experiences offerings, like flights, hotels, and ground transportation.

Product search/selection: The user searches for and selects a product.

Product detail page: Once the user has selected a product, the full product details are displayed.

Select valid pax mix: On the product detail page, the user is prompted to select a valid passenger mix.

Check real-time availability: Real-time availability is checked, to confirm that the tour/activity is available on the selected date for the selected passenger mix

Book: If the product is available, a booking is made, and booking confirmation and voucher are shared with the traveler.

Pre-selecting a party for all offerings

While we recommend collecting passenger mix on the product page, some partner platforms are designed in a way that requires users to input their party details before selecting any products. This can be good UX, as it reduces the number of actions needed from the user. If you are working with Viator (or any major tours and activities providers) experiences, you will need to collect the exact age of each traveler, and implement custom logic to match traveler ages to product age bands. The user flow for this type of implementation could look something like this:

Select pax mix: The user must input party information, including the exact ages of each traveler.

Select and book non-experiences offerings: The user will go through your standard processes to select and book non-experiences offerings, like flights, hotels, and ground transportation.

Product search/selection: The user searches for and selects a product.

Product detail page: Once the user has selected a product, the full product details are displayed.

Validate passenger mix: Once the user is ready to book, you will need to follow the steps below to ensure that their booking will be valid.

Check real-time availability: Real-time availability is checked, to confirm that the tour/activity is available on the selected date for the selected passenger mix

Book: If the product is available, a booking is made, and booking confirmation and voucher are shared with the traveler.

In order to work with Viator experiences, your platform must be able to assign each traveler an age band. This means that if you are collecting party information before the user selects a product, you will need to to collect the exact age of each traveler. Definitions of age bands differ between Viator products, so collecting broad information like “adult” and “child” is not sufficient.

Once the user is ready to book, you will need to validate the ages of the booking party against the product’s age bands and passenger mix requirements. Each traveler must be assigned a product-specific age-band, by validating their numeric age against the valid ranges for that product. Not all products will support all ages, so some products will not be bookable for certain parties. Once age bands have been assigned to each traveler for a given product, you must then follow the standard procedures to validate the passenger mix, before moving on to the booking stage.

Validating age band and passenger mix through the API

This section is a technical guide to validating age bands and passenger mix – it is important that age bands and passenger mix are validated correctly, since failure to do so may result in invalid bookings being sent to our tour operators.

Before you confirm a booking, you must ensure that the booker’s party consists of an acceptable combination of passengers and their respective age(s) for the product in question.

Validating passenger mix:

1
Locate the bookingRequirements object in the response from any of the product content endpoints.
2
Using the minTravelersPerBooking and maxTravelersPerBooking fields as reference, set upper and lower bounds on the total number of travelers your users may input when booking this product. The total number of travelers refers to the total number of travelers across all ageBands.
3
If a particular ageBand has requiresAdultForBooking set to true, at least one traveler with the ADULT or SENIOR ageBand must be included in the passenger mix. If requiresAdultForBooking is false, then the ageBand in question should be bookable without any other travelers present.

“bookingRequirements”: {

“minTravelersPerBooking”: 1,
“maxTravelersPerBooking”: 15,
“requiresAdultForBooking”: false

},

Z

Requirements

  1. Users must not be able to input a total number of travelers greater than the maxTravelersPerBooking value, or less than the minTravelersPerBooking value.
  2. If requiresAdultForBooking is true, users must not have the option to create a booking without an adult or senior traveler present.

Best practices

  1. Communicate the maximum and minimum travelers to the user. For example: “This experience is bookable by 2-15 travelers.”

  2. If an adult or senior traveler is required, communicate this to the user. For example: “At least one adult or senior per party is required.”

  3. Do not include the option to select invalid passenger mixes. From a UX perspective, preventing your users from selecting invalid mixes at all is preferable to displaying error messages.

Validating age bands:

1
Locate the ageBands array, found in the pricingInfo object in the response from any of the product content endpoints.
2
The ageBands array will contain information on the particular age bands this product offers. For each individual ageBandstartAge and endAge fields to communicate the appropriate age range to the user. For example, an ADULT ageBand with a startAge of 18 and an endAge of 60 may be displayed as “Adult (18-60).” The age range specified for a given ageBand is set by the tour operator and will vary between products, so this process must be performed on a per-product basis.
3

For each individual ageBand, refer to the minTravelersPerBooking and maxTravelersPerBooking fields to set upper and lower bounds on the number of travelers of that ageBand. The minTravelersPerBooking and maxTravelersPerBooking fields in the pricingInfo object must not be confused with the fields of the same name in the bookingRequirements object.

Note: The ageBand for products with per-unit pricing will always be TRAVELER.

“pricingInfo”: {

“type”: “PER_PERSON”,
“ageBands”: [

{
“ageBand”: “ADULT”,
“startAge”: 18,
“endAge”: 60,
“minTravelersPerBooking”: 0,
“maxTravelersPerBooking”: 9
},

]

},

Z

Requirements

  1. Partners must select the appropriate ageBand for each booker, based on the age of the traveler. This can be accomplished by displaying the age ranges for each ageBand, or by collecting the ages of each traveler, then selecting the appropriate ageBands.
    • If you choose to display the age ranges, the upper and lower bouts of each band must be clearly define. For example, “Child (ages 4-15).”
  2. Users must not be able to input a total number of travelers greater than the maxTravelersPerBooking value, or less than the minTravelersPerBooking value specified for each individual ageBand.

Best practices

  1. Avoid excluding products with specific age bands, as this will significantly limit your available inventory.

  2. Collect age bands on the product detail page, just before displaying tour options.

Validating age bands based on traveler ages:

Because acceptable passenger mix and age bands will still vary between different products, you will still need to validate age bands and pax mix for any product a party would like to book. This means that you must collect the numeric ages of all travelers, and validate them against the accepted ageBands for each product. For example, if a product returned the below ageBand, then any travelers with an age of 18, 60, or any integer in between would be considered an ADULT in the context of that product. Note: If a passenger’s numeric age is not listed in one of a product’s ageBands, then that product is not bookable by the party.
{ “ageBand”: “ADULT”, “startAge”: 18, “endAge”: 60, “minTravelersPerBooking”: 0, “maxTravelersPerBooking”: 9 }

Did you find this article useful?