Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Resolving Third-Party Calendar Sync: Viator API Integration and Manual Availability Blocking

During a recent development session, we encountered a critical issue with Viator inventory synchronization: their API integration team provided a response that forced us to reconsider our calendar sync architecture. This post documents the technical investigation, the workaround we implemented, and the architectural decisions that led us here.

The Problem: Viator's Connectivity Constraints

Our system maintains a single source of truth for yacht charter availability across multiple distribution channels, including Viator. We had assumed Viator exposed a standard iCal feed or webhook mechanism for suppliers to push/pull calendar data programmatically. The reality was more constrained.

After reading ticket t-ad4b92d7 from James Jimenez (Viator Integration Services), we discovered that:

  • Viator does not expose a self-serve iCal export endpoint for suppliers
  • Viator does not provide webhook delivery for booking events
  • All calendar synchronization must route through one of Viator's certified connectivity partners (channel managers)
  • Every certified partner charges either the operator or the guest a percentage fee

This architectural constraint forced an immediate tactical decision: manually block unavailable dates on Viator's dashboard while we evaluate longer-term integration paths.

Immediate Fix: Manual Availability Blocking

For the specific case of Saturday, May 30, we needed to mark product 5653407P1 (Private Yacht Charters on Jada The Queen of San Diego) as unavailable without breaking the existing iCal sync that was already partially working.

Access Path:


supplier.viator.com
  → Dashboard
    → Your Products
      → 5653407P1 (Private Yacht Charters on Jada The Queen of San Diego)
        → Availability Tab
          → Calendar View

The blocking process is straightforward from the UI, but understanding the underlying sync mechanism is important for engineers:

  1. Navigate to the product's Availability management interface
  2. Locate May 30 in the calendar grid view
  3. Click the date to open the availability editor
  4. Change the state from AVAILABLE to BLOCKED or set all time slot inventories to 0
  5. Persist the change (Viator's dashboard will display "Availability updated automatically")

The "Availability updated automatically" confirmation message is somewhat misleading in this context. It indicates that Viator has recorded the change in their supplier product database. However, this is a push operation initiated by the supplier, not a pull operation from an external calendar source.

Technical Investigation: Why the iCal Approach Failed

Our original integration strategy relied on Viator's ability to poll a Google Calendar iCal feed. We had created a dedicated calendar at google.com/calendar (internal reference: jada-viator-sync@jadasailing.com) and attempted to provide Viator with the iCal URL in the format:


https://calendar.google.com/calendar/ical/[CALENDAR_ID]/public/basic.ics

While this URL is technically valid and Viator's dashboard showed a successful connection, the synchronization had several failure modes:

  • Polling Lag: Viator likely polls the iCal feed on a fixed schedule (possibly 12–24 hours), not in real-time
  • Feed Parsing: The iCal feed only reflects events explicitly created as "blocked" on the Google Calendar; availability is inferred as the absence of blocking events
  • Timezone Handling: iCal feeds are UTC-based by default; Viator's dashboard operates in the supplier's local timezone (Pacific Time for San Diego), creating potential off-by-one day errors
  • One-Way Sync: Viator bookings made through their platform are not reflected back to our Google Calendar, creating a divergence between systems

The core issue: iCal is a read-only, asynchronous, event-based format designed for consumer calendars, not real-time inventory management.

Current State: Bókun Connection and Disconnection

During the investigation, we discovered that the Viator product 5653407P1 was also connected to Bókun (a channel manager platform). This created a secondary synchronization path that could override our manual blocking efforts.

To disconnect Bókun from the Viator product:

  1. Go to supplier.viator.com → Product 5653407P1
  2. Navigate to the Product Connectivity tab (or Channels section)
  3. Locate the Bókun connection entry (Status: Connected)
  4. Click the Edit or Manage button on that connection panel
  5. Select Remove or Disconnect
  6. Confirm the disconnection request

Removing the Bókun connection is critical because channel managers maintain their own inventory state. If Bókun is still pushing availability updates to Viator, any manual blocks we set on 5653407P1 will be overwritten on the next sync cycle.

Key Architectural Decisions

Why we're not adopting a certified partner immediately:

Viator's certified partners include FareHarbor, Bókun, and several others. All charge either the operator or the guest. FareHarbor is the least expensive for operators (~6% guest fee, not charged to supplier), but it introduces another system of record. Adopting FareHarbor would require:

  • Migrating product data and availability calendars to FareHarbor's system
  • Establishing bidirectional sync between our internal booking database and FareHarbor
  • Replicating our business logic (pricing rules, time slot management, minimum lead times) in FareHarbor's configuration
  • Potential guest-facing changes (FareHarbor's booking flow may differ from Viator's native experience)

This is a significant engineering lift that should only be undertaken if manual blocking proves unsustainable.

Why we're asking about undocumented iCal feeds:

Before committing to a channel manager, we're drafting a follow-up email to James Jimenez asking: "Does Viator expose an iCal URL for confirmed supplier bookings that we can poll from our system?" Some Viator integration partners have reported accessing an undocumented supplier booking feed. If this exists and is performant, it could unlock a unidirectional sync that doesn't require a third-party system.

What's Next

The immediate action items are:

  1. Manual block May 30 on product 5653407P1 via the Viator dashboard (completed)
  2. Disconnect Bókun from the same product to prevent conflicting sync operations
  3. Send a sharper technical query to Viator asking specifically about iCal polling endpoints and undocumented booking feeds
  4. Evaluate