All you need to know about cancellations

Apr 26, 2021 | Merchant API, Travel Commerce Partners

In this guide, we cover:

Viator’s cancellation policies

Verifying refund amount in V.1 API

Verifying refund amount in V.2 API

Cancellation policy logic explained

Cancellation process

Partial refunds

Post-travel cancellations

Booking amendments

Supplier amendments & cancellations

Managing communications

Viator’s Cancellation Policies

Standard

Free cancellation up to 24 hours before the start time (local supplier time)

85% of products

Custom

The refund amount depends on how many days before the start time the cancellation is done

5% of products

All Sales Final

100% penalty for the cancellation at any time

10% of products

“Building a good customer experience does not happen by accident. It happens by design.”

– Clare Muscutt

Predict the unpredictable

Be prepared for unexpected, reassuring customers that you are on their side. We don’t know what the travel situation will be like in the future. That’s why we need more flexibility now than ever before. Relaxed cancellation policies and the possibility to make changes to the booking are currently the most important booking factors especially for bookings made far ahead. If you can provide this, customers will book with you.

Make it easy

Show the cancellation policy clearly on the website. Begin your relationship with customers by offering high-quality customer service. It matters not only what you do but also how quickly you do it. Meet customer’s expectations by replying promptly – use messaging tools such as ready templates, automatic replies, and online chat. Provide a self-cancellation service using the new Viator cancellation endpoints.

Offer support, create loyalty

Listen to your customers and resolve their problems. By being flexible and understanding of the customer’s needs, you will make them want to come back. Even if they find better deals somewhere else, they will prefer to book comfortably with you. They will also recommend you to their friends. Apply flexible cancellation policies, provide excellent customer support and see how great it works!

Technical operations – verifying the refund amount in V.1 API

Cancellation policy type: merchantTermsAndConditions.merchantTermsAndConditionsType

  • Standard cancellation policy = 1
  • Custom cancellation policy = 2
  • All sales final policy = 3

Cancellation policy in text format: merchantTermsAndConditions.termsAndConditions
Example: “termsAndConditions”: “For a full refund, cancel at least 24 hours in advance of the start time of the experience.”

Checking the refund amount: merchantTermsAndConditions.cancellationFromTourDate

  • dayRangeMin
  • dayRangeMax
  • percentageRefundable
  • policyStartTimestamp*
  • policyEndTimestamp*

*Returned only post booking – in response to /booking/book, /booking/pastbooking, /booking/mybookings

Viator Cancellation Policies - Partner API
Example response

“merchantTermsAndConditions”: {

“termsAndConditions”: “For a full refund, cancel at least 24 hours in advance of the start time of the experience.”,
“merchantTermsAndConditionsType”: 1,
“amountRefundable”: “USD 146.56”,
“cancellationFromTourDate”: [

{

“dayRangeMin”: 0,
“dayRangeMax”: 1,
“percentageRefundable”: 0,
“policyStartTimestamp”: 1616567400,
“policyEndTimestamp”: 1616653800

},
{

“dayRangeMin”: 1,
“dayRangeMax”: null,
“percentageRefundable”: 100,
“policyStartTimestamp”: null,
“policyEndTimestamp”: 1616567400

}

]

},

Technical operations – verifying the refund amount in V.2 API

Cancellation policy type: cancellationPolicy.type

  • Standard cancellation policy = “STANDARD”
  • Custom cancellation policy = “CUSTOM”
  • All sales final policy = “ALL_SALES_FINAL”

Cancellation policy in text format: cancellationPolicy.description

Example: “description”: “For a full refund, cancel at least 24 hours before the scheduled departure time.”

Checking the refund amount: merchantTermsAndConditions.cancellationFromTourDate

  • dayRangeMin
  • dayRangeMax
  • percentageRefundable
  • startTimestamp*
  • endTimestamp*

*Returned only post booking – in response to /bookings/book, /bookings/status

Viator Cancellation Policies - Partner API - v2
Example response

“cancellationPolicy”: {

“type”: “STANDARD”,

“description”: “For a full refund, cancel at least 24 hours before the scheduled departure time.”,
“cancelIfBadWeather”: false,
“cancelIfInsufficientTravelers”: false,
“refundEligibility”: [

{

“dayRangeMin”: 1,
“percentageRefundable”: 100,
“startTimestamp”: “2021-01-08T08:49:08Z”,
“endTimestamp”: “2021-04-03T22:59:59Z”

},
{

“dayRangeMin”: 0,
“dayRangeMax”: 1,
“percentageRefundable”: 0,
“startTimestamp”: “2021-04-03T23:00:00Z”,
“endTimestamp”: “2021-04-04T23:00:00Z”

}

]

},

Cancellation policy logic explained

Cancellation policy logic

Cancellation process

All booking cancellations (except for those requested after the date of travel, or those triggered by the tour operator) must now be performed via the API by following the steps listed below. A full breakdown of our cancellation workflow can be found in our API documentation.

Checking cancellation reasons

All cancellation reasons can be retrieved from the /bookings/cancel-reasons endpoint:

Request

curl –location –request GET ‘https://api.sandbox.viator.com/partner/bookings/cancel-reasons’ \
–header ‘Accept-Language: en-US’ \
–header ‘Accept: application/json;version=2.0’ \
–header ‘exp-api-key: xxxx’

Response

{

“reasons”: [

{

“cancellationReasonText”: “Unexpected medical circumstances”,
“cancellationReasonCode”: “Customer_Service.Unexpected_medical_circumstances”

},
{

“cancellationReasonText”: “Booked wrong tour date”,
“cancellationReasonCode”: “Customer_Service.Booked_wrong_tour_date”

},
{

“cancellationReasonText”: “The guide or driver didn’t show up”,
“cancellationReasonCode”: “Customer_Service.Supplier_no_show”

},
{

“cancellationReasonText”: “Chose a different/cheaper tour”,
“cancellationReasonCode”: “Customer_Service.Chose_a_different_cheaper_tour”

},
{

“cancellationReasonText”: “Significant global event”,
“cancellationReasonCode”: “Customer_Service.Significant_global_event”

},
{

“cancellationReasonText”: “I canceled my entire trip”,
“cancellationReasonCode”: “Customer_Service.I_canceled_my_entire_trip”

},
{

“cancellationReasonText”: “Duplicate Booking”,
“cancellationReasonCode”: “Customer_Service.Duplicate_Booking”

},
{

“cancellationReasonText”: “Weather”,
“cancellationReasonCode”: “Customer_Service.Weather”

}

]

}

We recommend refreshing the list of cancellation reasons weekly. If you would like to use a placeholder cancellation reason, we request that you use “I canceled my entire trip”, as using other reasons may trigger internal processes with our suppliers.

Verifying the refund amount

The /bookings/{booking-reference}/cancel-quote endpoint should be used before processing the cancellation in order to get a cancellation quote – the exact amount that will be refunded in case of a cancellation.

The booking-reference used for this request is generated in the response to /bookings/book service (bookingRef) and it has the following format: BR-123456789.

 

Request

curl –location –request GET ‘https://api.sandbox.viator.com/partner/bookings/BR-585476618/cancel-quote’ \
–header ‘Content-Type: application/json’ \
–header ‘Accept: application/json;version=2.0’ \
–header ‘Accept-Language: en-US’ \
–header ‘exp-api-key: xxxx’

Response

{

“bookingId”: “BR-585476618”,
“refundDetails”: {

“itemPrice”: 93.83,
“refundAmount”: 0.00,
“refundPercentage”: 0.00,
“currencyCode”: “GBP”

},
“status”: “CANCELLABLE”

}

The response above indicates that the booking can be canceled, however a refund will not be provided (“refundAmount”: 0.00,“refundPercentage”: 0.00,).

Please note:

  • It is possible to cancel booking requests made for manual confirmation type products where the booking status is “PENDING”. However, in case of bookings with the “PENDING” status, the following fields will return a value of 0: itemPrice, refundAmount and refundPercentage. This is because no fees have been charged for bookings that have not been “CONFIRMED” yet.
  • The response will always return “status”: “CANCELLABLE” if it’s before the activity start time however this doesn’t mean that the booking is refundable. In order to check if the refund will be provided it’s necessary to verify values returned for the refundAmount and refundPercentage.

Canceling a booking

Once the refund amount has been verified and agreed, the cancellation must be processed using the /bookings/{booking-reference}/cancel endpoint:

Request (must include a valid reasonCode)

curl –location –request POST ‘https://api.sandbox.viator.com/partner/bookings/BR-585476618/cancel’ \
–header ‘Content-Type: application/json’ \
–header ‘Accept: application/json;version=2.0’ \
–header ‘Accept-Language: en-US’ \
–header ‘exp-api-key: xxxx’ \
–data-raw ‘{“reasonCode”:”Customer_Service.Chose_a_different_cheaper_tour”}’

Response

{

“bookingId”: “BR-585476618”,
“status”: “ACCEPTED”

}

The booking has been canceled only when the “ACCEPTED” status has been returned in the response to this endpoint.

In case of a “DECLINED” status returned in the response, a relevant reason why the cancellation has been declined will be provided as well:

  • “ALREADY_CANCELLED”: The booking has already been canceled
  • “NOT_CANCELLABLE”: The booking cannot be canceled because the product start time was in the past (see post-travel cancellations section)

See this section of our API documentation for additional information.

Partial refunds

In case of partial refunds (custom cancellation policy), it’s essential to verify the refund due based on values returned under dayRangeMin and dayRangeMax and relevant percentageRefundable.

Please note: percentageRefundable might be returned as 0 which means that no refund can be provided (this is usually the case when it’s close to the start time, or when the product has a non-refundable policy).

Post-travel cancellations

In some situations, customers might request a refund post travel date.

For example, the supplier might have cancelled the tour last minute due to weather conditions; or the customer might be unsatisfied with the tour.

In order to process post-travel cancellations, please contact our support team at dpsupport@viator.com including “CANCEL” and the booking reference number in the subject line as well as a detailed description of the issue.

post-travel-cancellations email

Booking amendments

At the moment we don’t have the functionality to amend bookings via the API. There are a few ways to make changes to an existing booking:

Cancel it and re-book (please always verify the cancellation policy on the booking prior to cancelling it; price and availability are subject to change).

Contact our support team at dpsupport@viator.com to request the change.If you require urgent support on your travelers’ bookings within 24 hours of travel, please call the support phone lines:

  • Europe +44 2072923158
  • USA +1 8337642167
  • Australia +61 291654336

Please note: the above contact details should be used for amendments only. Booking cancellations must be processed using the API.

Once the change is confirmed by the Viator team you will need to share the new updated voucher with the customer. You will receive it in an email sent by the support team or you can use the API services to get it (/booking/mybookings endpoint in V.1 API or the /bookings/status endpoint in V.2 API).

We will not be able to process amendments when:

  • we receive the request to amend the booking(s) less than 48 hours prior to the time of travel – please advise your customer to call the supplier directly to negotiate any changes;
  • the booking is non-cancellable – non-cancellable bookings are non-transferable and cannot be amended i.e., the name of the traveling party cannot be changed post-purchase;
  • the amendment results in a price difference – the original booking will need to be cancelled using the API and a new booking will have to be made, customer should receive a new voucher from you;
  • the supplier doesn’t allow the change.

Contact the supplier directly, using the Supplier’s contact information that can be found on the Viator voucher.

Supplier amendments and cancellations

There might be situations when the booking gets amended/cancelled by the supplier due to operational issues, weather, scheduling changes, etc.

We will advise you of the service change via email and it’s your responsibility to inform your customer about the same and confirm back to us whether the amendment has been accepted by the customer. When accepted, we will update the voucher details so that you can reissue a new voucher to your customer using API services. When the amendment is not accepted, we will cancel the booking and you will need to process the refund.

You can use API services to create an automated process to inform customers about supplier-driven cancellations, instead of relying on emails sent by Viator. In order to automate this process, it is necessary to use the /bookings/modified-since and /bookings/modified-since/acknowledgement endpoints.

The /bookings/modified-since endpoint enables a proactive process, by which you will regularly poll for updates on your existing bookings, including post-travel cancellations. This endpoint will return cancellation and refund details for bookings within a specified timeframe. You can then use the /bookings/modified-since/acknowledge API endpoint to acknowledge that you have processed the cancellation(s). This acknowledgement will prevent Viator from triggering email notifications.

The workflow used to pull supplier-side cancellations is explained in detail in this article.

We recommend using API services periodically for booking status checks:

booking status

Managing communications

Please see below specific scenarios when Viator communicates with direct Viator travelers in regards to their bookings. We highly recommend that our merchant partners create the same communication flow for their customers.

Under the column with notifications for the customer/merchant/supplier you can see when Viator sends communication to the relevant party about bookings made by merchant partners.

Managing communications
* Merchant partners do not receive any communication from Viator with the booking confirmation as this information should be retrieved by the partner using the API services.

** The scenario illustrated here refers to the situation when the customer initiates the cancellation directly with Viator. The Viator Customer Service team will contact the merchant partner to advise of the same and will process the cancellation when approved by the merchant partner. However the expectation is that the customer will contact the merchant partner directly in order to amend or cancel the booking.

*** The table illustrates the process applied to V.2 API – where partners don’t receive copies of emails sent to customers. Partners using the V.1 API receive a copy of the CLC email sent to the email address provided in the booking request.

Please note: Closed Loop Communication (CLC) is enabled by the merchant partner when customer’s contact details are sent in the booking request.

  • V.1 API: email and either homePhone or cellphone +cellPhoneCountryCode in the booker object in the request body when making a call to /booking/book service.
  • V.2 API: email and phone in the communication object in the request body when making a call to /bookings/book service.

When Closed Loop Communication (CLC) is enabled, the supplier will be able to contact the end customer directly with any questions or additional information about the booking. When it’s disabled, the merchant partner will be contacted by the supplier and responsible for passing the message to the customer (and forwarding the response to the supplier when necessary).

All cancellation policies described above are in the local supplier time.

For additional information please check our Merchant API partner guide or contact us at affiliateapi@tripadvisor.com

Did you find this article useful?