In this guide, we’ll detail how API partners 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.
- an automated flow to retrieve all manually processed amendments (amendments processed through the API are not part of this flow).
What are supply-side events?
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 or amend 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 events (cancellations and amendments).
It is important to remember that because our tours and activities are operated by suppliers, a supplier may cancel a booking or request an amendment at any time.
Operational workflows for managing supply-side events
As a merchant partner, you are responsible for managing customer support and are required to inform travelers about supplier-initiated amendments and cancellations. Viator will never contact travelers directly in these cases – all communication must come from you.
Supplier-initiated amendments
When a supplier submits an amendment request, you will be notified via email at the customer service / booking support email address provided in your Partner Dashboard. As the merchant of record, you decide whether the request can be approved. Naturally, this requires you to share the proposal with your customer to confirm whether it can be accepted.
This process is handled fully manually via email. Once you approve an amendment and it is processed by the Viator support team, the confirmed amendment details will be sent to you via email, and the amendment status will also be returned in the /bookings/modified-since response. This allows you to automate internal and customer-facing reporting on your side.
Please note: Supplier-initiated amendment requests cannot be approved via the API, so manual email communication is required.
Supplier-initiated cancellations
When a supplier cancels a booking, Viator will send an email notification to you at the booking support email address we have on file. In addition, the /bookings/modified-since endpoint will return cancellation and refund details for bookings within the specified timeframe. 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.
It‘s essential to automate this flow so that notifications are passed on to your customers as quickly as possible, allowing them to make alternative arrangements.
To prevent duplicate communications, you can use the /bookings/modified-since/acknowledge endpoint to acknowledge the cancellation. Once acknowledged, Viator will not send the email notification.
If the partner would like to stop Viator’s automatic cancellation emails the process is as follows:
- 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 email address provided in the Partner dashboard for supplier cancellations.
Additional guidance for partners
- Merchant partners are required to automate the flow for supplier cancellations. This ensures timely traveler notifications, accurate internal reporting, and improved customer experience.
- While affiliate partners with booking access are not required to automate these flows, it is strongly recommended if customers can view Viator booking status on the partner platform in addition to email notifications from Viator. Automation reduces the risk of confusion, e.g., when a customer accepts a supplier amendment or a booking is canceled, but the partner’s platform continues displaying outdated or incorrect booking details.
- This endpoint also returns traveler cancellation events for cancellations initiated by the traveler and processed manually by the Viator support team (“eventType”: “CUSTOMER_CANCELLATION”). For merchant partners, this is a very rare scenario and may occur if the partner is unable to process the cancellation via the API due to a technical issue, or if the customer contacts Viator support directly and the support team reaches out to the merchant partner for approval to proceed with the cancellation. The standard process for traveler cancellations requires merchant partners to handle these through the API using the API cancellation workflow.
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 events
To automate your notifications to the traveler, you will need to implement the API endpoints mentioned. This process is quite similar to the process for ingesting and refreshing product and availability data:
Make a GET request to the /bookings/modified-since endpoint, with the modified-since parameter set to the date on which your API implementation went live, or by omitting the modified-since parameter entirely. This will enable you to ingest all supply-side events associated with your account. Be sure to save the value of the nextCursor field, as it will be needed for subsequent requests.
Please note:
- 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.
- Amendment notifications will be returned for bookings confirmed past September 1, 2025 MST (6 am UTC).
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 events.
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”
}
}
}, ….
Identity event types (amendment / cancellation / customer cancellation) using the eventType field from the endpoint response and trigger your internal processes accordingly.
Every time a response to a /bookings/modified-since request returns a new transactionRef with “eventType”: “CANCELLATION”, 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)
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 booking event notification
- 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
- campaignValue – Only affiliate partners with booking access: Specifies the campaign tracking identifier that was appended to the URL returned in productUrl as a query parameter.
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.
The /bookings/modified-since/acknowledge endpoint should not be used:
- for acknowledgement of eventTypes other than “CANCELLATION” – this is the only event type that requires acknowledgement in order to stop the cancellation email from Viator.
- by affiliate partners with booking access – based on the contractual agreement, Viator is obliged to inform the customer directly about the supplier cancellation and the associated refund details.