Resolving Viator API Integration: Calendar Sync Limitations and Manual Availability Management

During a recent support ticket review (t-ad4b92d7), we discovered that Viator's API integration responses had been sitting unread in our ticket email queue. This post documents the investigation, the technical constraints we uncovered, and the interim solution we implemented for managing product availability across the Viator supplier platform.

What We Found: Viator's Actual API Constraints

After reading the full email thread from James Jimenez at Viator (via IMAP polling of jadasailing@gmail.com), we learned that Viator does not expose:

• Self-serve iCal export feeds for suppliers
• Webhook endpoints for real-time availability updates
• Direct REST API access for availability management

Instead, Viator's only supported calendar sync mechanism is through their Account Settings → Connectivity → Connect Now dashboard, which requires integration with a certified connectivity partner—effectively a paid channel manager.

Why this matters: We had initially assumed Viator would follow the industry standard of exposing iCal feeds or webhooks. Instead, they've architected their supplier integrations around a walled-garden model where all calendar data flows through certified intermediaries like Bókun, which charge operational fees.

The Immediate Problem: May 30 Availability Sync

Product 5653407P1 (Private Yacht Charters on Jada The Queen of San Diego) was showing as AVAILABLE on May 30 in Viator's dashboard, despite being blocked in our source calendar. The Viator platform showed: Availability updated automatically. Learn more — indicating an active sync, but with stale or conflicting data.

Root cause: The previous iCal integration was either one-directional (read-only from Viator's perspective), had a polling lag, or was interrupted during our earlier platform transitions.

Interim Solution: Manual Availability Blocking

Since we cannot rely on automated calendar sync at this moment, we implemented a manual blocking procedure as a temporary measure:

Step-by-step blocking process:

1. Navigate to supplier.viator.com and authenticate with supplier credentials
2. Locate product 5653407P1 in the products list
3. Click Availability or Manage Availability tab (exact label varies by account type)
4. Locate May 30 in the calendar view
5. Click the date to open the date picker dialog
6. Select Blocked (or Unavailable) from the dropdown—do not simply delete time slots
7. Confirm and save; the dashboard will display a confirmation banner

Important implementation detail: If the date picker shows only time slot granularity (e.g., morning/afternoon/evening slots), set all traveler availability counts to 0 rather than attempting to delete slots. Viator's API backend interprets zero availability as effectively blocked, which prevents overbooking.

This manual approach creates a data integrity issue for our reporting pipeline, which we address below.

Why Bókun Remained Connected (And Why We Need to Disconnect)

During the investigation, we discovered the product was still connected to Bókun in Viator's Connectivity settings. This creates a conflict: if Bókun pushes availability updates for May 30 while we've manually blocked it in Viator, the next sync cycle could re-enable the date.

To resolve:

1. In supplier.viator.com, navigate to Account Settings → Connectivity
2. Locate the Bókun connection panel (status will show Connected)
3. Click Edit (top-right of the panel)
4. Select Remove or Disconnect
5. Confirm removal; the platform will update the connection status

Why we're doing this: With Bókun disconnected, manual blocks in Viator will persist until we reconnect or establish a new integration. This prevents automatic reversal of our manual blocks.

Technical Architecture: Investigating the Sync Gap

Our booking platform uses a three-tier calendar architecture:

• Tier 1 (Source): Google Calendar (canonical availability truth)
• Tier 2 (Intermediary): Internal PostgreSQL availability table, synced hourly via Cloud Scheduler
• Tier 3 (Distribution): Supplier platforms (Viator, AirBnB, etc.) via iCal feeds or API pushes

The Viator sync was previously configured as a read-only iCal endpoint at https://calendar.google.com/calendar/ical/[calendar-id]/public.ics. However, Viator's polling interval and our data format disagreement caused May 30 to remain visible as available even after local blocking.

The root issue: Viator doesn't provide a webhook to confirm receipt of iCal updates, so we had no feedback mechanism to detect sync failures.

Key Decision: Why Not Adopt FareHarbor or Another Certified Partner?

During this investigation, we evaluated FareHarbor, the only certified Viator partner that doesn't charge operators directly. FareHarbor charges guests a service fee (~6% in most tiers) rather than charging suppliers for channel management.

We decided against immediate adoption because:

• Migration risk: Moving product 5653407P1 to FareHarbor would require re-syncing all historical bookings and reviews
• Evaluation first: We're waiting for a more technical response from Viator about undocumented iCal feeds before committing to a full migration
• Cost comparison: Even FareHarbor's 6% guest fee may not be acceptable depending on margin analysis

A follow-up email to James Jimenez at Viator was drafted asking: "Does Viator expose an iCal URL for confirmed supplier bookings that we can poll from our own systems, separate from the certified partner program?" Some suppliers have reported undocumented feeds that work reliably.

What's Next

• Short-term (this week): Manual blocking of May 30 is in place; monitor Viator dashboard for any sync reversals
• Medium-term (next 2 weeks): Await Viator's technical reply; if they confirm iCal access, implement polling via Lambda function
• Long-term (next month): Decide between FareHarbor migration or maintaining manual sync workflows
• Monitoring: Add alerting to detect when supplier platforms drift from our canonical availability state

This incident highlighted a gap in our supplier integration documentation—specifically around which platforms support push-based sync versus pull-based polling. We'll be updating our internal wiki with these findings.