Overview
This guide explains how partners can use Viator’s APIs to build custom booking reporting that supports operational efficiency and real-time marketing optimization.
Partners can:
- Access real-time booking notifications (confirmation, cancellation, amendment, rejection)*.
- Map bookings to campaigns for marketing performance analysis**.
- Automate ingestion of updates for scalable, reliable reporting.
* EventTypes returned may vary depending on your API access level. Merchant partners and affiliate partners with booking access do not receive:
– Booking confirmation or rejection notifications for their own API-initiated bookings.
– Amendment confirmations for amendments they themselves processed via the API.
– Cancellation notifications for cancellations they themselves processed via the API.
** The campaignValue parameter is available only to Affiliate API partners. Merchant partners can implement their own campaign tracking process by storing identifiers in their systems when generating product links.
This is especially critical for partners using SEM, content-driven marketing, and affiliates who want to optimize ad spend continuously.
Endpoints used for booking reporting
/bookings/modified-since
- Returns all booking-event notifications since a point in time.
- The endpoint supports two primary polling methods:
– Timestamp: A specific date and time from which to pull events.
– Pagination cursor: Recommended method, as it ensures all updates are pulled correctly, even in cases of intermittent failures
- Accessible to all partner types: Basic Affiliates, Full Affiliates, Booking Affiliates, and Merchants.
- Must be polled regularly:
– Hourly for most scenarios.
– Every 5 minutes for supplier cancellations (Merchants only).
- Always retry failed calls with the last cursor value to prevent data loss.
Event types returned:
- CONFIRMATION – booking confirmed
- REJECTION – booking rejected by supplier
- AMENDMENT – booking amended (excludes API-initiated amendments)
- CANCELLATION – booking cancelled by the supplier
- CUSTOMER_CANCELLATION – booking cancelled by the customer
Initial Integration Guidance
When integrating with the /bookings/modified-since endpoint for the first time, partners who wish to retrieve all bookings since the beginning of time should not include either the cursor or modified-since parameters in their initial request. Instead, use only pagination to iterate through the results.
For Basic and Full Access Affiliates, the “beginning of time” is defined as September 1, 2025 MST (6 am UTC).
For Merchants and Booking Access Affiliates, amendment notifications will be returned only for bookings made from September 1, 2025 MST (6 am UTC).
Please note:
By default, the response will not include events initiated via the API (e.g., bookings, cancellations, and amendments made through a partner’s system). This is because the partner’s system already has this information, making the notification redundant.
This means:
- Confirmations of API bookings are not returned.
- Rejections of API bookings are not returned.
- API cancellations or amendments are not returned.
Examples:
- If a partner cancels or amends a booking via the API → the platform is API (event not included).
- If a traveler books or cancels through Viator website, or Viator CS modifies the booking → the platform is not API (event included).
Additional event types or fields may be added in the future – design ingestion logic to be flexible.
/bookings/modified-since/acknowledge
- Used to acknowledge supplier cancellations and take ownership of customer communication responsibilities (Merchants only).
- Call /bookings/modified-since/acknowledge for supplier cancellations before the acknowledgeBy timestamp to stop the cancellation emails.
- This endpoint should not be used by non-merchant partners.
- This 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.
Application by partner type
| Usage | Affiliates | Merchants |
| Poll /bookings/modified-since regularly | ✅ Hourly | ✅ Every 2–5 min if using /bookings/modified-since/acknowledge, otherwise hourly |
| Acknowledge supplier cancellations | ❌ | ✅ Must poll every 5 minutes and acknowledge via /bookings/modified-since/acknowledge |
| Cache and store events for reporting purposes | ✅ | ✅ |
| Sync booking events with internal systems (keep itineraries up to date, reduce CS overload) | ✅ | ✅ |
| Use booking event data to reconcile with financial systems | ✅ | ✅ |
| Marketing optimization / campaign tracking | ✅ Use campaignValue to tie bookings to campaigns and optimize spend | ❌ (no campaignValue available, merchants can use booking event data to create internal campaign tracking and performance reporting) |
| Requirement level | Best practice | Mandatory |
Data mapping for reports
When ingesting /bookings/modified-since responses, store and map key fields into your reporting tables:
| Field | Description | Use Case |
| transactionRef | Unique booking identifier | Primary reference for booking reporting |
| campaignValue | Partner campaign ID (basic & full access affiliates only) | Campaign attribution and reporting on campaign success |
| eventType | Booking event type | Status reporting, operational updates |
| productCode | Viator product identifier | Product-level sales reporting |
| travelDate | Date of travel | Forecasting, reconciliation |
| lastUpdated | Last modified timestamp | Reporting accuracy, troubleshooting |
| cancellationReasonCode* | Reason for cancellation | Customer operations analysis |
| totalPrice | Total booking price | Revenue reporting |
| currency | Currency of booking | Financial reconciliation |
* Returned only for merchant partners and booking access affiliates
Reporting examples
Marketing optimization report (Basic & Full Access Affiliates)
- Objective: Understand which campaigns deliver the most confirmed bookings.
- Data needed:
– campaignValue
– eventType
– bookingRef
– partnerBookingRef - Sample output:
– Campaign A → 120 bookings confirmed → $12,000 revenue → ROI 150%
– Campaign B → 30 bookings cancelled → ROI negative
Operational monitoring report (Merchants)
- Objective: Track supplier-driven cancellations in real-time.
- Data needed:
– eventType = CANCELLATION
– cancellationReasonCode
– /acknowledge request submitted - Sample output:
– Automated cancellation notifications sent to travelers
– 12 cancellations last 24h → potential re-booking → follow up required
Sales report (all partners)
- Objective: Provide finance with confirmed bookings and associated revenue.
- Data needed:
– bookingRef, partnerBookingRef, productCode, travelDate, travelTime, totalPrice, currency, status, cancellationReasonCode, refundDetails - Sample output:
– Build SQL queries, dashboards, or booking reports based on the mapped fields. -
-
Examples:
Key benefits of custom booking reporting
- Real-time booking visibility
– Provides up-to-date information on all relevant booking events.
– Reduces reliance on manual reporting processes. - Marketing optimization (affiliate partners)
– Track bookings linked to campaigns using campaignValue.
– Identify and pause underperforming campaigns.
– Reallocate ad spend based on real-time results. - Comprehensive booking status tracking
– The new event types provide immediate insight into all booking status changes, including rejections, amendments, and cancellations, which helps to ensure the accuracy of a partner’s internal reporting and user-facing reporting.
– Ensures partners can easily retrieve all relevant changes in bookings except those initiated via their own API. - Data integrity and accurate reporting
– Immediate insight into booking status updates: confirmations, amendments, cancellations, and rejections.
– Supports accurate internal and user-facing reports. - Operational efficiency (merchant partners)
– Mandatory integration ensures backend systems stay synchronized.
– Improves process efficiency by fully automating booking status management and eliminating reliance on emails.
– Enhances customer experience by informing travelers of canceled bookings as soon as possible.
– Automates supplier cancellation handling with 2–5 minute polling, preventing unnecessary cancellation emails from Viator.
– Provides better visibility of manually amended bookings (through Viator Customer Support) to help partners update their systems and user interfaces accordingly. - Flexible integration
– Supports polling via timestamp or recommended pagination cursor.
– Allows partners to build custom reports tailored to their business needs.