In this guide, we’ll detail how merchant partners using the V.2 API can implement an automated read-and-acknowledge notification system for supplier-driven cancellations, in which you will have 5 minutes to acknowledge supplier-driven cancellations. If you do not acknowledge a cancellation within this time, Viator will trigger an email to the support contact details we have on file.
What are supply-side cancellations?
Viator sources tours and activities from our network of suppliers – thousands of independent in-destination tour operators. Our suppliers use Viator to make and manage bookings, but manage their own operations.
Occasionally, a supplier needs to cancel a booking made through Viator. This could be due to issues like inclement weather, insufficient participants for a group activity, or an operational issue. Collectively, these are considered supply side cancellations.
It is important to remember that because our tours and activities are operated by suppliers, a supplier may cancel a booking at any time.
Operational workflows for managing supply side cancellations
As a merchant partner, you are responsible for managing customer support and may prefer to share notifications directly through your own system. After a five minute grace period, Viator will automatically send an email notification, using the support contact details we have on file. You can prevent Viator’s automatic message and trigger your own communication to the traveler, using the /bookings/modified-since and /bookings/modified-since/acknowledge API 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.
Note: This is a fully optional workflow. If you do not integrate with the supplier cancellation API endpoints, Viator will continue to send cancellation emails. If you would like Viator to continue to send notifications via email, no development work is needed.
If you would like to use the API to trigger cancellation emails to the traveler:
- The supplier cancels a booking
- You learn of this cancellation through an automated request to /bookings/modified-since
- Within 5 minutes of the booking being canceled, you acknowledge the transaction using /bookings/modified-since/acknowledge
- You notify the customer of the cancellation
If you would like Viator to notify your support team of supplier cancellations (default)
- The supplier cancels a booking
- You do not acknowledge receipt of the cancellation
- After the 5 minute grace period has elapsed, Viator notifies you of the cancellation, using the support contact details we have on file
Please note: Viator will never send cancellation emails to your end customer. As a merchant of record you are responsible for informing customers about cancellations and processing refunds.
API workflow for managing supply side cancellations
To automate your cancellation notifications to the traveler, you will need to automate requests to the two API endpoints mentioned. This process is quite similar to the process for ingesting and refreshing product and availability data:
Please note that when performing this initial ingestion, Viator will already have triggered email sends for all bookings canceled more than 5 minutes after, the time indicated by the acknowledgeBy field.
Request sample
Response sample
“bookings”: [
{
“transactionRef” : “1234”,
“eventType”: “CANCELLATION”,
“acknowledgeBy”: “2022-04-08T09:22:48Z”,
“bookingRef”: “BR-204104077”,
“partnerBookingRef”: “BK2041040771234567”,
“lastUpdated”: “2022-04-07T13:25:00Z”,
“bookedItem”: {
“productCode”: “281620P2”,
“productOptionCode”: “TG1”,
“travelDate”: “2022-05-12”,
“travelTime”: “09:30”
},
“cancellation”: {
“cancellationReasonCode”: “Supplier_Service.Significant_global_event”,
“refundDetails”: {
“itemPrice”: 59.40,
“refundAmount”: 59.40,
“refundPercentage”: 100.00,
“currencyCode”: “AUD”
}
}
}, ….
No more frequently than once every 10 seconds, make a GET request to the /bookings/modified-since endpoint, using the nextCursor value from the previous request’s response as the cursor parameter. Repeat this process indefinitely.
Please note each /bookings/modified-since request will return up to 50 supplier cancellations.
Request sample
GET /bookings/modified-since?cursor=MTY0OTM5NTUwOXwxMjM0NTY3ODkK
Response sample
“bookings”: [
{
“transactionRef” : “1234”,
“eventType”: “CANCELLATION”,
“acknowledgeBy”: “2022-04-08T09:22:48Z”,
“bookingRef”: “BR-204104077”,
“partnerBookingRef”: “BK2041040771234567”,
“lastUpdated”: “2022-04-07T13:25:00Z”,
“bookedItem”: {
“productCode”: “281620P2”,
“productOptionCode”: “TG1”,
“travelDate”: “2022-05-12”,
“travelTime”: “09:30”
},
“cancellation”: {
“cancellationReasonCode”: “Supplier_Service.Significant_global_event”,
“refundDetails”: {
“itemPrice”: 59.40,
“refundAmount”: 59.40,
“refundPercentage”: 100.00,
“currencyCode”: “AUD”
}
}
}, ….
Every time a response to a /bookings/modified-since request returns a new transactionRef, make a POST request to the /bookings/modified-since/acknowledge API endpoint, including every new transactionRef in the request body. If you have followed steps one and two, every new transactionRef should fall within the timeframe specified in the acknowledgeBy field, and will require acknowledgement.
Please note for your initial /bookings/modified-since request, a /bookings/modified-since/acknowledge request should only be made if there is at least one transactionRef with an acknowledgeBy time that is in the future. This request should only include every transactionRef with an upcoming acknowledgeBy time.
Request sample
POST /bookings/modified-since/acknowledge{ “transactionRefs”: [ “TM5NTUw”,”TM5NTUt” ] }
Response sample
HTTP 200 success
(a successful request will not have a response body)
/bookings/modified-since specs
Request samples:
| Get all modified bookings | GET /bookings/modified-since |
| Get all modified bookings since the last request | GET /bookings/modified-since?cursor=MTY0OTM5NTUwOXwxMjM0NTY3ODkK |
| Get all modified bookings since the specified time | GET /bookings/modified-since?modified-since=2022-04-07T00%3A00%3A00Z |
Response sample
“bookings”: [
{
“transactionRef” : “1234”,
“eventType”: “CANCELLATION“,
“acknowledgeBy”: “2022-04-08T09:22:48Z”,
“bookingRef”: “BR-204104077”,
“partnerBookingRef”: “BK2041040771234567”,
“lastUpdated”: “2022-04-07T13:25:00Z”,
“bookedItem”: {
“productCode”: “281620P2”,
“productOptionCode”: “TG1”,
“travelDate”: “2022-05-12”,
“travelTime”: “09:30”
},
“cancellation”: {
“cancellationReasonCode”: “Supplier_Service.Significant_global_event”,
“refundDetails”: {
“itemPrice”: 59.40,
“refundAmount”: 59.40,
“refundPercentage”: 100.00,
“currencyCode”: “AUD”
}
}
}, ….
Field definitions
- transactionRef – Unique id for a given cancelation
- eventType – Type of transaction
- bookingRef – Viator booking item reference
- partnerBookingRef – Partners booking item ref.
- lastUpdate – date/time transaction was updated
- acknowledgeBy – date/time at which Viator trigger an email to the partner
- bookedItem – bookable item attributes
- cancellationReasonCode – cancellation reason id
- cancellationReasonText – cancellation reason description
- itemPrice – price at time of booking
- refundAmount – total amount refunded
- refundPercentage – % of total booking amount refunded
- currencyCode – currency for amounts returned
Request sample
POST /bookings/modified-since/acknowledge
{ “transactionRefs”: [ “TM5NTUw”,”TM5NTUt” ] }
Response sample
HTTP 200 status code
(no response body)
Note that a successful response will not include a response body. If the request returns an HTTP 200 status, the request should be considered successful. Failed requests will include a response body with an error message.