Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Resolving Viator API Integration: iCal Polling vs. Certified Partners

When a third-party supplier integration hits a wall, it's often because the platform's public API doesn't match the operational model you've built. This post walks through debugging the Viator calendar sync issue, understanding their actual connectivity constraints, and the decision tree for moving forward.

The Problem: Viator's "Certified Partner" Requirement

A support ticket (t-ad4b92d7) came back from Viator's James Jimenez with a standard response: calendar integration requires using a "certified API partner." On the surface, this sounds straightforward. In practice, it created a blocker:

  • Every certified partner in Viator's ecosystem is a paid channel manager (Bókun, Rezdy, etc.)
  • We've already ruled out channel managers to avoid commission fees on direct bookings
  • Viator's public API documentation doesn't expose a self-serve iCal export or webhook for supplier availability
  • Manual blocking in supplier.viator.com for specific dates (like May 30) works, but doesn't scale

The issue manifested as: availability synced from Google Calendar → iCal feed → Viator dashboard showed AVAILABLE even after we blocked the date locally. The sync was working in one direction (Viator pulling our calendar), but we had no way to push updates back without committing to a paid intermediary.

Technical Investigation: What Viator Actually Exposes

Before escalating, we reviewed Viator's documented API surface:

  • POST /suppliers/{id}/availability — Available in certified partner integrations only; requires partner account type
  • GET /bookings/{id} — Read-only confirmed reservations; no calendar feed
  • iCal URL export — Not documented; James's reply suggested it exists only via certified partners' connectivity portal

The architectural decision Viator made is defensible: they want calendar data flowing through audited, PCI-compliant intermediaries. But it locks out operators who manage their own systems.

Immediate Fix: Manual Blocking in Viator Dashboard

For the May 30 conflict, we took a manual approach while investigating deeper:

  1. Navigate to supplier.viator.com/dashboard
  2. Select product 5653407P1 (Private Yacht Charters on Jada The Queen of San Diego)
  3. Go to Availability tab (calendar view)
  4. Click May 30 → Select Blocked (not "Unavailable" — this prevents any time slots from being offered)
  5. Save changes

This blocks the date immediately in Viator's inventory. The why: Viator's UI has two blocking mechanisms:

  • Blocked dates — No availability at any time; prevents slot selection entirely
  • Zero-out time slots — Sets traveler count to 0 for specific times; requires guest to see no capacity

For a charter operation, "Blocked" is cleaner—guests see the date as unavailable rather than a zero-capacity option.

Disconnecting Bókun: Removing the Automatic Sync

The chat agent noted that Viator is still connected to Bókun in the Product connection tab. Even though we ruled out Bókun as a primary channel, the connection was active and potentially conflicting with manual changes. Disconnecting it:

  1. Go to supplier.viator.com/dashboard → Account Settings
  2. Select Connectivity tab
  3. Find the Bókun connection (should show Status: Connected)
  4. Click Edit → Remove or Disconnect
  5. Confirm removal

Why disconnect? Once you remove an automated sync, manual changes stick. Leaving Bókun connected means the next sync pulls Bókun's calendar view and potentially overwrites what you blocked in Viator's native UI.

The Next Question: Undocumented iCal Feed

Before committing to a paid partner, we're sending a more targeted follow-up to James:

"Does Viator expose an iCal URL for confirmed supplier bookings 
that I can poll directly from my own systems? We've confirmed your 
public API requires certified partners, but some suppliers have found 
undocumented calendar feeds."

Why? Some platforms publish iCal URLs in their partner portal that don't show up in public docs. The ask is specific: we want to read confirmed bookings from Viator (one-way pull), not write availability (two-way sync). That's a lower-risk ask and sometimes has an undocumented solution.

Decision Tree: Path Forward

Three scenarios:

  • Scenario A: iCal feed exists — We build a scheduled poller (Lambda function on EventBridge, running every 15 minutes) that hits that URL, parses the feed, and updates our local booking state. Cost: near-zero.
  • Scenario B: iCal feed doesn't exist, commit to certified partner — FareHarbor is the only free option (they charge guests ~6%, not operators). We'd configure their Connectivity plugin in Viator's dashboard and map our product ID.
  • Scenario C: Both options fail — Viator becomes a manual-entry channel. We block dates in their UI as needed, but stop treating it as a live sync source. This is acceptable for a secondary channel but not scalable.

Infrastructure: If We Go iCal Route

Assuming James replies with a feed URL, here's the architecture:

  • CloudWatch Events rule — Triggers every 15 minutes
  • Lambda function — Located at /lambda/viator-ical-poller/index.js
    • Fetches iCal URL from Secrets Manager (encrypted)
    • Parses VEVENT entries using icalendar library
    • Compares against DynamoDB table viator-bookings (partition key: booking_id, sort key: booking_date)
    • Writes new/updated bookings; triggers SNS topic for conflicts
  • DynamoDB table — viator-bookings, TTL enabled (90 days)
  • SNS topic — viator-sync-alerts; publishes conflicts to ops team

What's Next

We're waiting on James's response. In the meantime:

  1. May 30 is blocked in Viator manually — immediate risk resolved
  2. Bókun connection is disconnected — removes sync conflicts
  3. We've asked a specific technical question about iCal export — this closes the information gap

Once we have his answer, the build path is clear. If iCal exists, we can have the poller live within