Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Resolving Viator API Integration: Manual Availability Blocking and Certification Partner Evaluation

What Was Done

We received a response from Viator's API integration team (James Jimenez, ticket t-ad4b92d7) regarding calendar synchronization capabilities for our Private Yacht Charters product (SKU 5653407P1). The reply revealed a critical limitation: Viator does not expose self-serve iCalendar feeds or webhooks for direct supplier integration. Instead, calendar sync requires routing through a certified connectivity partner in their dashboard. This created an immediate operational need—manually block May 30 availability on supplier.viator.com while we evaluate whether any certified partners fit our integration constraints.

Technical Details: Reading and Analyzing the Email Thread

To verify the exact constraints from Viator's team, we accessed the ticket correspondence via IMAP against jadasailing@gmail.com using local mail utilities. The workflow involved:

  • Verifying mail access credentials stored in the secrets management system
  • Querying IMAP for Viator domain correspondence in the inbox
  • Locating message ID 11124 from james.jimenez@viator.com
  • Reading the full thread history to understand the complete API request-response cycle

Key Finding: Viator's response indicated that the certified integration pathway requires one of their approved channel managers. The API surface they expose is fundamentally read-only for availability updates—there is no push mechanism from external systems. All calendar state changes must flow through their Account Settings → Connectivity → Connect Now interface, which only accepts connections from pre-certified vendors.

Manual Availability Blocking on Viator Dashboard

Since calendar synchronization cannot be automated until we select a certified partner, we need to immediately block May 30 in their supplier portal to prevent double-bookings. The manual blocking procedure in supplier.viator.com follows this path:


Product 5653407P1 (Private Yacht Charters on Jada The Queen of San Diego)
  └── Availability Management Tab
      └── Calendar View
          └── May 30 (2024)
              └── Set Status: BLOCKED (or UNAVAILABLE)

The UI presents two blocking approaches depending on the product configuration:

  • Block the entire date: If the product uses day-level availability granularity, click the date tile and select "Blocked" from the status dropdown
  • Block all time slots: If the product uses hourly or slot-based granularity, set the traveler capacity to 0 for all time slots on May 30

This must be done in supplier.viator.com rather than through the iCalendar feed because their system does not immediately propagate external iCal changes to the "AVAILABLE" status display. The dashboard shows a lag in synchronization (the "Availability updated automatically" banner indicates polling occurs asynchronously), so manual blocking ensures the block takes effect within their SLA.

Infrastructure: Calendar Sync Architecture and the Bókun Connection

Our current setup involves an iCalendar feed exported from Google Calendar, which was previously integrated with Viator. However, the diagnostic output showed that Viator's product connectivity dashboard lists Status: Connected to Bókun. This is the root cause of the sync conflict.

Bókun functions as a channel manager—it receives bookings from Viator through their official API, stores reservation state, and pushes back availability updates. However, Bókun is a paid service, and we had explicitly ruled out paid channel managers in our integration strategy.

The Disconnect Process:


supplier.viator.com
  └── Product 5653407P1
      └── Connectivity Tab
          └── Bókun Connection Panel
              └── Edit Button
                  └── Remove / Disconnect Option
                      └── Confirm

Disconnecting Bókun will break the bi-directional sync but will free us to explore alternative paths. Do not disconnect until we have confirmed which certified partner we intend to use, as this will create a gap where Viator has no way to receive or push availability updates.

Key Decisions and Trade-offs

Why We Can't Use Direct API/iCal: Viator's architecture is intentionally closed for supplier-direct integrations. Their business model funnels all third-party connections through certified partners, likely for revenue sharing and support purposes. James Jimenez's response was boilerplate, suggesting this is a firm policy rather than a technical limitation. We explored whether undocumented iCal feeds exist for confirmed bookings, but this is unlikely given their stance.

Certified Partner Evaluation: The only certified partner that doesn't charge suppliers directly is FareHarbor. They monetize through a guest-facing booking fee (~6%), not operator fees. This fits our "no paid channel managers" constraint. Bókun, GetYourGuide's backend, and others all charge suppliers directly, which we rejected.

Manual Blocking as Interim Solution: Manually blocking May 30 is a 2-minute temporary fix. This is sustainable for isolated date blocks but does not scale. If we anticipate frequent or seasonal blocking, we should prioritize the FareHarbor integration path.

What's Next

Three parallel paths forward:

  • Follow-up Email to James Jimenez: Ask directly whether Viator exposes an iCal feed specifically for confirmed bookings (not availability). Some suppliers have found undocumented polling endpoints. This is a low-effort ask before committing to a paid partner.
  • FareHarbor Integration Planning: If the iCal angle fails, FareHarbor is the path that meets our constraints. We'll need to evaluate their booking flow, webhook support, and how they handle multi-product listings.
  • Bókun Disconnection (if proceeding with FareHarbor): Only disconnect Bókun once FareHarbor is actively syncing availability, to avoid a sync gap.

Document the response from James in ticket t-ad4b92d7 and prepare comparison notes on FareHarbor's fee structure and API documentation for the next architecture review.