Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Resolving Viator API Integration: Manual Availability Blocking and iCal Sync Validation

What Was Done

During this development session, we diagnosed a calendar synchronization gap between our booking system and Viator's supplier dashboard. A Viator support ticket (t-ad4b92d7) revealed that their API integration doesn't expose a self-serve iCal feed or webhook mechanism for real-time availability updates. As an interim solution, we implemented manual date blocking on the Viator supplier portal while validating whether an undocumented iCal endpoint exists.

Technical Details: The Viator Integration Problem

Viator's certified connectivity model requires all suppliers to integrate through one of their approved channel management partners. When we reviewed James Jimenez's response from the Viator API team, it became clear that:

  • No direct iCal export exists: Viator doesn't expose a supplier-specific iCal URL that can be polled from external systems
  • No webhook/callback mechanism: Real-time availability updates aren't pushed to external systems
  • Dashboard-only connectivity: The only documented sync method requires connecting through Account Settings → Connectivity → Connect Now in the Viator supplier dashboard, which in turn requires using a certified partner (Bókun, FareHarbor, etc.)
  • Paid channel manager requirement: Most certified partners charge either the operator or the guest, conflicting with our "no paid channel managers" constraint

This created a circular dependency: to sync calendars with Viator, we'd need to use a paid channel manager, but those were already ruled out in the product requirements.

Manual Availability Blocking: Immediate Workaround

Since May 30 needed to be blocked immediately (pending the API resolution), the manual process in the Viator supplier portal is:


Viator Supplier Dashboard Flow:
1. Navigate to: supplier.viator.com
2. Select Product: 5653407P1 (Private Yacht Charters on Jada The Queen of San Diego)
3. Go to: Availability tab (or Manage Availability / Calendar view)
4. Locate: May 30 on the calendar grid
5. Click the date cell
6. Select status: Blocked (or Unavailable, depending on UI version)
7. Confirm and save changes

The critical observation here is that the dashboard showed "Availability updated automatically" — indicating an active synchronization mechanism. However, the sync direction and update frequency weren't immediately clear. We needed to determine whether:

  • Our Google Calendar iCal feed is pushing to Viator (push sync)
  • Viator is polling our iCal feed (pull sync)
  • The sync is bidirectional or one-way
  • What the polling interval is (immediate, hourly, daily?)

By manually blocking May 30 in the supplier dashboard, we ensured the date would be unavailable to guests while we investigated the sync mechanism further.

Investigating the Bókun Connection State

The chat agent noted that Viator appeared to still be connected to Bókun. When we checked the Product Connectivity panel in the supplier dashboard, the status showed:


Status: Connected (to Bókun)

This indicated a lingering connection that should be removed to avoid conflicting sync sources. The disconnection process:


Viator Dashboard Disconnection Flow:
1. Open: Product Connectivity tab (in product settings)
2. Locate: Bókun connection panel
3. Click: Edit button (top-right of panel)
4. Select: Remove or Disconnect option
5. Confirm removal to prevent ghost syncs

Why this matters: If two channel managers are connected to the same Viator product, availability rules could conflict, causing race conditions where one system marks a date as available while another marks it as blocked. Removing the Bókun connection eliminates this source of truth collision.

Key Decision: The iCal Validation Path

Rather than immediately committing to a paid channel manager like FareHarbor, we decided to ask Viator a more specific technical question before escalating. The follow-up email to James Jimenez should ask:


"Does Viator expose an iCal URL for confirmed supplier bookings that 
our system can poll directly? Some suppliers have found undocumented 
iCal feeds in your API. Could you confirm whether this endpoint exists, 
and if so, what the rate limits and authentication requirements are?"

Why this approach: Enterprise SaaS platforms often have undocumented integration points or legacy endpoints that don't appear in official API docs. Viator might expose an iCal feed for internal use or through a read-only API key. A direct question to their API team is faster than trial-and-error.

Fallback Architecture: FareHarbor Integration

If the iCal validation fails, FareHarbor is the only certified Viator partner that operates on a guest-side commission model (~6% to guests, not the operator). The integration would follow this architecture:

  • FareHarbor as sync source: Bókun would be fully disconnected; FareHarbor becomes the single channel manager
  • Booking flow: Guests book through Viator → Viator's inventory syncs via FareHarbor → our booking system receives webhooks
  • Availability feedback: Our system updates availability in FareHarbor's API → Viator's dashboard reflects changes
  • No direct Viator API calls needed: All communication goes through FareHarbor's REST API

This would require:

  • FareHarbor API credentials stored in AWS Secrets Manager (path: /prod/fareharbor/api-key)
  • New Lambda function: fareharbor-availability-sync (triggered by EventBridge on 15-min intervals)
  • DynamoDB table for tracking sync state: fareharbor_sync_log
  • CloudWatch alarms for sync failures (threshold: 2 consecutive failed polls)

What's Next

The immediate next steps are:

  1. Manual blocking confirmed: May 30 is blocked on Viator's supplier portal — this takes effect immediately
  2. Disconnect Bókun: Remove the legacy channel manager connection to prevent sync conflicts
  3. Email James Jimenez: Ask the targeted iCal endpoint question and wait for response (typically 1-2 business days)
  4. Monitor sync behavior: Watch whether May 30 remains unavailable in Viator's guest-facing portal. If it flips back to AVAILABLE, the iCal sync is overriding manual blocks, and we need to adjust our sync strategy
  5. Decide on FareHarbor: If Viator confirms no iCal endpoint, schedule the FareHarbor integration work and update project timelines

This phased approach minimizes immediate guest-facing impact (manual blocking works now) while validating architectural decisions before committing to paid integrations.