Calculating Product Pricing

Pricing structure in the API

Structured pricing information is provided by the API via the availability schedules endpoints. It consists of the following elements:

offerStartDate and offerEndDate fields are returned to indicate the period during which the offer applies. For example, a special offer applies when you make the booking between 1 and 15 March, for any travel date

travelStartDate and travelEndDate fields are used to indicate the period during which the tour must be completed. For example, if you book for travel date between 1 and 15 March you get a discounted rate but the special pricing wouldn’t apply if you book after 15 March

fromPriceBeforeDiscount – if the product is presently discounted, this field shows what the value of fromPrice would be if no discount had been applied; otherwise, it will be absent.

extraChargesSummary – the summary of extra charges to be paid by the customer in destination for all bookable items, including mandatory charges broken down by item, number of units, amount per unit and the total amount – in the currency provided in the request and converted into the currency in destination (if different from request currency)

extraCharges – the maximum value of extra charges to be paid by the customer in destination

mandatory – object with all mandatory extra charges to be paid in destination, includes: charge name, number of units (number of times it has to be calculated, i.e. per person, per group), amount per unit, total amount – in the currency provided in the request and converted into the currency in destination (if different from request currency)

Based on the example above, the same product might offer different pricing depending on the productOptionCode, seasons, startTime, or ageBand.

↑ Back to top

Ingesting and updating pricing data

The data returned from the /availability/schedules endpoints should be ingested and used to display the initial pricing, for example in the calendar view before users select a specific date:

Please note:

• The /availability/check endpoint is not intended for bulk ingestion of availability and pricing data. It is designed for real-time checks only. 
• You shouldn’t expect to be invoiced based on the pricing returned with /availability/schedules endpoints as this is cached data. That’s why real-time availability and pricing checks with the /availability/check endpoint must be conducted prior to booking in order to get fully accurate pricing.

↑ Back to top

Per person and unit pricing

Viator pricing can be grouped into two categories: per person pricing and unit pricing – indicated in the pricingPackageType field of the product content response with the value either “PER_PERSON” or “UNIT”.

Per-person pricing

Per-person pricing is calculated based on the number of participants from each age band (to read more about the Viator age bands, check this article). The pricing is returned separately for each age band, as shown in the response example.

The same age band might have different pricing depending on the number of participants from that age band.

As illustrated in the example above for product 40856P10, the per-person pricing for an ADULT age band is much higher when only one adult is booked than in the scenario where multiple adults are booked.

The lowest per-person retail price for the product is returned as fromPrice in the response from the /availability/schedules/* endpoints (in the currency provided by the supplier). It’s calculated according to the price for a group of at least two standard participants (or, the smallest bookable group if more than two participants are required) for a period not exceeding 384 days into the future. This value can be used to advertise a ‘from’-price.

Unit pricing

Unit pricing is based on the number of groups (units) and types of groups (units) that could be either: “GROUP”, “ROOM”, “PACKAGE”, “VEHICLE”, “BIKE”, “BOAT”, or “AIRCRAFT” – all defined in the API documentation:

The pricing information can be retrieved from the /availability/schedules/* endpoints:

The price for two travelers would be exactly the same as the price for four travelers, because the price is based on the number of units and not the number of travelers.

In order to book this product for more than four travelers, a new booking request would need to be made (the API doesn’t support multiple bookings at the same time).

Please note: unit pricing is linked to only one age band – TRAVELER (this age band will not appear for products that have per-person pricing).

You can read more about per-person vs unit pricing in this section of the API documentation.

↑ Back to top

Special pricing

Some Viator suppliers offer discounted pricing for their products – this information is returned in the API under “special” pricing. Special pricing is valid only for a time period specified, and sometimes it applies to specific travel dates.

There are additional attributes linked to special pricing that must be used to validate the pricing correctly:

• offerStartDate and offerEndDate fields are returned to identify the period when the offer applies, for example a special offer applies when you make the booking between March 1st-15th, for any travel date
  
• travelStartDate and travelEndDate fields are used to indicate the period within which the tour should be completed, for example if you book for travel date between March 1st-15th you get a discounted rate but the special pricing won’t apply if your travel date is after 15 March

For example, the pricing schedule below for the product 195878P21 indicates that the special offer applies to the CHILD age band for bookings made between 2 April and 31 May 2022, for any travel date between 2 April and 31 October 2022.

Please note:

• You will always see the offerStartDate and offerEndDate returned for special pricing and depending on the supplier’s set up you may or may not see the travelStartDate and travelEndDate returned – this depends if the supplier wants to apply the offer to all future dates or only specific dates.
• Special pricing is defined on a per-age-band basis. It’s possible to get special pricing for the same product only for selected age bands (i.e. special pricing is returned for an adult age band but not for a child age band).

Unlocking the value of discounted rates

Special offers and discounts are effective tools for attracting customer attention and boosting sales. Leveraging them can significantly enhance customer engagement and conversion rates. It’s highly recommended to incorporate special offers, discounts, and promotions into your pricing strategy to drive more traffic and increase sales opportunities.

Additional tools for identifying discounted rates

• You can also identify products with permanently discounted rates using the Viator tags. For example:
  
• “tagId”: 12493 – “Discounted Pricing for Select Groups”
  
• “tagId”: 12461 – “Discounted Pricing for Children”
  
• “tagId”: 12462 – “Discounted Pricing for Seniors”
  
• “tagId”: 12463 – “Discounted Pricing for Students”
  
• “tagId”: 12464 – “Discounted Pricing for Veterans”

Feel free to read more about the Viator tags and how to use them to merchandise products in this article.

Pricing could be modified by the supplier at any time therefore it’s recommended to always verify if the product offers special pricing based on the pricing schedules returned in the API.

↑ Back to top

Low margin products (markup merchants)

You can easily check the price of the activity on Viator – it’s returned in the API as the recommendedRetailPrice.

However, in some rare cases the recommendedRetailPrice might be lower than the partnerTotalPrice (the total amount that you will be invoiced if you are a markup merchant). This means that selling a product at the recommended retail price without first confirming that the margin is acceptable could result in a net loss for that transaction. This would apply to low margin products on Viator and only to markup merchants (the value of partnerTotalPrice and partnerNetPrice will always be equal for commission merchants).

Therefore if you are a markup merchant, it’s important for you to have logic in place to compare the recommendedRetailPrice and the partnerTotalPrice and adjust the pricing if necessary to make sure that selling at the recommendedRetailPrice wouldn’t result in a loss.

For example, product 3328DISNEY returns the recommendedRetailPrice higher than the partnerTotalPrice for both ADULT and CHILD age bands:

To make sure that you make a profit on that product, you will need to adjust the pricing on your end so that it’s not lower than the partnerTotalPrice.

↑ Back to top

Currency conversion

The availability schedules endpoints return rates in the currency provided by the supplier. The following supplier currencies are supported: AED, AUD, BRL, CAD, CHF, CNY, DKK, EUR, FJD, GBP, HHL, HKD, IDR, INR, ISK, JPY, KRW, MXN, MYR, NOK, NZD, PLN, RUB, SEK, SGD, THB, TRY, TWD, USD, VND, ZAR.

If you don’t have your own exchange rate system, you must use the /exchange-rates endpoint to convert pricing into the currency you wish to be invoiced in (AUD, CAD, EUR, GBP, or USD). 

For example, in order to check the conversion rate from THB to USD, you need to make the following request:

In the response, you will receive:

The expiry field returns a timestamp (UTC) that indicates until when the conversion rate is valid. We request that you store the conversion rates data and refresh it periodically by checking the expiry timestamp. Currently, exchange rates are updated daily via the API, but this frequency may change in the future. The same conversion rate applies to all products, so there is no need to verify it for each booking separately. 

It’s also important to do the real-time availability check with the /availability/check endpoint in the correct currency (for example “currency”: “USD” must be sent in the request body). This way you will be able to verify the exact amount that Viator will invoice you based on Viator exchange rates.

↑ Back to top

The response returns all product options for the requested date and passenger mix:

↑ Back to top

Availability and pricing hold

We highly recommend using the /bookings/hold or the /bookings/cart/hold endpoint during the booking process in order to place a temporary hold on availability and price. This way customers will be given enough time to fill in all required information and book before the product gets sold out or the price changes.

Please note:

• It’s essential to verify the timestamps returned in the API response for availability and pricing holds. A new hold can be placed only once the previous hold expires.
• A booking hold should not be made until the user has indicated a strong intention to book. Typically, this means that it should not be called until immediately prior to the user entering their payment details.
• The /bookings/hold or the /bookings/cart/hold endpoint must never be used to check product availability.
• All data included in a booking request (passenger mix, travel date, booking questions, etc.) must be validated for the product in question before an availability or pricing hold or booking request is made.
  (See our certification requirements)

The response includes the booking reference that should be used in the /bookings/book request, the status of availability and pricing holds as well as timestamps for each one (validUntil) and the pricing information:

↑ Back to top

Invoicing

If you are a merchant API partner with the markup model, Viator will invoice you the amount returned under the partnerTotalPrice in the /bookings/book response in the currency sent in the booking request. It’s possible to make a booking in one of the following currencies: AUD, CAD, EUR, GBP, USD.

If you make multiple bookings using different currencies, you will receive separate invoices from Viator for each currency. If you would prefer to receive only one invoice, please make sure to specify the same currency in all your booking requests (this is recommended).

If you attempt to use a non-supported currency, you will receive this error message:

In case the booking needs to be amended and the change would result in a different price, the original booking needs to be canceled using the API and a new booking needs to be made. Viator will not invoice you for any canceled bookings as long as they have been canceled within the free cancellation window. This can be verified with the /bookings/{booking-reference}/cancel-quote endpoint (read more about the Viator cancellation policies and processes in this article).

For example, if you received the following response from the /bookings/{booking-reference}/cancel-quote endpoint, Viator would invoice you 50% of the booking amount if you were to cancel:

It’s recommended to store the logs with responses to the /bookings/{booking-reference}/cancel-quote and /bookings/{booking-reference}/cancel endpoints for canceled bookings for at least a month so that they can be used to dispute any invoicing discrepancies. If you’d like to open a dispute regarding your Viator invoice, please fill in this form.

Please note:

• You should not rely on the pricing returned from any of the availability schedule endpoints for invoicing, as this data is cached. To ensure accurate pricing, it’s important to perform a real-time check using the /availability/check endpoint before confirming the booking. If you use the hold endpoint to secure a price before the customer confirms the booking, make sure to verify the timestamp in the response, as it indicates how long the price will be held. If the booking request is not submitted within the specified time frame, the price may have changed. Following these steps is crucial to ensure the pricing is correct and to avoid discrepancies between the expected and invoiced amounts.

↑ Back to top

Extra charges

Some products come with extra charges that must be paid directly to the tour operator at the destination. These additional charges are not included in the price charged at the time the booking is confirmed.

Online travel agencies that must comply with the regulations imposed by California Legislation SB-478 are required to display the full product charges, excluding taxes. To ensure compliance, the “full price” must be displayed throughout the entire purchasing journey, including all fees.

Viator requests information about these additional charges from suppliers and shares it via the API to help our partners provide this information to their customers. If this legislation applies to your customer’s location, you can use the relevant API fields to convey all applicable fees and charges. Examples of additional charges include: admission charges, government fees, public transportation, and meals.

Disclaimer: Viator provides all relevant information through the API, but it is the partner’s responsibility to ensure full compliance with the rules and regulations applicable to their business. Prices payable to third parties are provided to us by the operator, and may be subject to change

The Viator API returns extra charges at 3 levels:

1. Product endpoints, to help you display exclusions applicable to each product based on the product content response:

• /products/modified-since
• /products/bulk
• /products/{product-code}

Extra charges can be found under “exclusions” and they are grouped by category (eg. “FEES_AND_TAXES”) and type (eg. “ADMISSION_CHARGE”). The typeDescription field contains the name of the extra charge in natural language, making it suitable for display to users. Suppliers may also provide supplementary details about the charge, which are returned as free text (description) and can be displayed on the front end to provide further information to customers. This content is translated into all languages supported in the API.

All inclusions and exclusions grouped by category and type are listed here. Please keep in mind that this list is subject to change.

2. Upper funnel endpoints, to help you display additional charges information on upper funnel pages (before a passenger mix is applied).

• /schedules/modified-since
• /availability/schedules/bulk
• /availability/schedules/{product-code}
• /products/search
• /search/freetext

The pricing.extraChargesSummary object returns the following fields with extra charges: fromPrice, fromPriceBeforeDiscount and extraCharges.

3. Lower funnel endpoints, to help you display the accurate extra charges for the selected pax mix and travel date to customers on the checkout page.

• /availability/check
• /bookings/cart/hold
• /bookings/hold

*Please note: the number of units is calculated differently for products with different pricing types:

• “PER_PERSON”: The number of units equals the number of travelers.
•  “UNIT”: The number of units equals the number of units (groups), regardless of the number of travelers in each unit. Currently, it is only possible to book for a single unit, so the number of units in this case is always 1.

Maximum extra charges vs. actual fees in destination

The extra charges returned in the API represent the maximum fees that a customer may incur at the destination.

For instance, if the maximum extra charge is $10 per person and the booking is for 2 adults and 3 children, the total maximum extra charge would be $50 (5 x $10). In practice, some charges may not apply to certain individuals, such as children, and the actual fees paid may be lower. For example, the attraction may not charge extra for children, reducing the total extra fees to $20 instead of the maximum $50.

Please be aware that these fees are subject to change, and the information provided reflects the details available at the time of booking. Factors such as currency exchange rates may affect the final amount the traveler pays at the destination.

Sharing this information with users helps set accurate expectations and minimize any surprises during their trip.

↑ Back to top