Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Resolving Viator API Integration: iCal Polling vs. Certified Partners

During a recent development session, we discovered that our Viator channel integration was hitting a hard architectural constraint. After reviewing the actual Viator API documentation and their support response, we needed to pivot our approach to calendar synchronization. This post documents the technical findings, the decision process, and the interim solution.

The Problem: Viator's Limited API Surface

Our goal was to implement bi-directional calendar sync between our internal booking system and Viator's supplier dashboard without using a paid channel manager (like Bókun or Airbnb's connectivity partners). We assumed Viator exposed either:

  • A webhook API for availability changes
  • An iCal feed we could poll from our cron jobs
  • A REST endpoint to update supplier availability in real-time

After James Jimenez from Viator Support responded to our integration inquiry, the reality became clear: Viator requires all calendar sync to flow through certified connectivity partners. Their official integration path is:

Account Settings → Connectivity → Connect Now → Select Certified Partner

There is no self-serve iCal export, no polling endpoint, and no direct webhook. Calendar synchronization is a closed system reserved for their certified partner ecosystem.

Technical Architecture: Why Webhooks Failed

Our initial design assumed a standard SaaS integration pattern:

  • We expose: POST /webhooks/viator/availability-change on our backend (hosted on ECS, load-balanced via ALB)
  • Viator sends: Availability updates when suppliers modify their calendar
  • We process: Update our RDS database and propagate to other channels

This architecture is clean because it decouples suppliers' calendar state from our polling infrastructure. However, Viator doesn't support outbound webhooks for suppliers. Their system is pull-only: operators log into their dashboard and manually manage availability, or they integrate through a certified partner that handles the pulling on their behalf.

The Interim Solution: Manual Blocking via Dashboard

Until we resolve the API constraint, we implemented a manual blocking procedure for time-sensitive blackout dates:

  1. Navigate to supplier.viator.com with operator credentials
  2. Select the product (in this case: 5653407P1 — "Private Yacht Charters on Jada The Queen of San Diego")
  3. Access the Availability or Manage Availability tab (UI layout varies by account age)
  4. Locate the target date on the calendar (May 30) and click to open date options
  5. Select Blocked or Unavailable status and save

The key technical detail here: if Viator's UI only presents time-slot granularity (no day-level block), manually set all time slots to 0 travelers rather than attempting deletion. This ensures the date collapses to "no availability" in their search results.

Detecting Sync Lag: The "Availability Updated Automatically" Banner

We noticed Viator's dashboard displayed: "Availability updated automatically. Learn more" — indicating an active synchronization source. This happens when:

  • A supplier has previously connected an iCal feed (e.g., from Google Calendar)
  • Viator polls that iCal feed periodically (estimated 15–60 minute intervals)
  • Changes to the iCal feed propagate back to the Viator dashboard on the next poll cycle

In our case, we had configured Google Calendar as an iCal source, but Viator's polling lag meant manual changes in their dashboard weren't immediately reflected in our internal system. The sync is unidirectional and slow: Google Calendar → iCal feed → Viator dashboard (delayed pull). There is no reverse sync to notify us of dashboard-only changes.

Long-Term Path: Evaluating FareHarbor Integration

Viator's certified partners fall into two categories:

  • Paid channel managers (Bókun, Rezdy): They charge operators a percentage of bookings or monthly fees. We excluded these per requirements.
  • FareHarbor: A certified partner that charges guests (~6%) rather than operators, and offers free operator access to their connectivity layer.

If iCal polling fails, FareHarbor becomes the only viable path that doesn't impose operator costs. Their integration model:

Our Backend ↔ FareHarbor API ↔ Viator (via FareHarbor partnership)

FareHarbor exposes a standard REST API with webhook support, which would restore our webhook architecture. However, this requires vetting their technical SLA, support response times, and ensuring their webhook delivery reliability meets our 99.9% uptime threshold.

Next Steps: Sharper Follow-Up to Viator Support

Before committing to any paid integration partner, we're sending a follow-up to James Jimenez with a more targeted question:

"Does Viator expose an iCal URL or any polling endpoint for confirmed supplier bookings that we can fetch from our own systems? Even if undocumented, some suppliers have found feeds that work."

This query targets two possibilities:

  1. Official iCal endpoint: Viator might expose booking confirmations in an iCal feed that we can poll hourly via cron.
  2. Undocumented workarounds: Other suppliers may have discovered endpoints not listed in public documentation.

If James confirms neither exists, we pivot to FareHarbor evaluation and begin infrastructure work:

  • Create API credentials in FareHarbor's dashboard
  • Implement POST /webhooks/fareharber/sync in our backend microservice
  • Store FareHarbor credentials in AWS Secrets Manager under /prod/integrations/fareharber/api-key
  • Add integration tests in our CI/CD pipeline (CodePipeline) before deploying to ECS

Key Decision Rationale

We chose manual blocking over dead-end API development because:

  • Unblocks current work: May 30 can be protected immediately without waiting for API resolution.
  • Defers commitment: Manual blocking is temporary; we can still pursue iCal polling without sunk cost in a failed integration.
  • Buys information: James's next response will clarify whether FareHarbor is necessary, allowing informed infrastructure decisions.

This phased approach—manually handle blackouts now, resolve API architecture after gathering more data—minimizes risk while keeping momentum on the project.