Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Resolving Viator API Integration: From Boilerplate Responses to Practical iCal Polling

When a supplier integration hits a wall with vendor support, the path forward requires separating what they say from what they actually offer. This post documents how we debugged a Viator calendar synchronization issue (ticket t-ad4b92d7) by reading the actual API response, identifying the gap between documentation and capability, and executing a two-phase fix: immediate manual blocking plus a targeted technical inquiry.

What Went Wrong: The Boilerplate Deflection

Viator's support (James Jimenez, Partner Support) responded to our API integration inquiry with a standard response directing us to their "certified API partners" — primarily Bókun and similar channel managers. This sounded definitive but obscured a critical detail: we already ruled out paid channel managers on cost grounds.

The response didn't address our actual technical requirement: can we poll booking data programmatically without paying a subscription fee to an intermediary? Reading between the lines of their email revealed the real answer: Viator's self-serve option is the dashboard's native connectivity layer (Account Settings → Connectivity → Connect Now), which integrates with their roster of pre-approved partners—all of which charge operators either monthly fees or per-booking commissions.

Technical Details: Accessing and Analyzing the Email Thread

To properly understand the vendor's constraints, we accessed the original email thread via IMAP against jadasailing@gmail.com using a Gmail app password stored in our secrets manager.


# Example command flow (credentials omitted)
# Check for mail utilities
mail --version

# Search IMAP for Viator API integration emails
# Used search criteria: from:James.Jimenez@viator.com AND subject:"API integration"

# Retrieved message 11124, read full thread to understand context

The full thread showed that our initial inquiry asked about direct API access or iCal export capability. Viator's response listed their certified partners but didn't confirm whether an undocumented iCal feed exists for suppliers wanting to build custom integrations. This gap became the basis for Step 2 of our fix.

Infrastructure: Immediate Calendar Blocking

While the API question remains open, we have a real calendar problem: May 30 is oversold. The immediate fix is manual unavailability blocking in Viator's supplier dashboard.

Step 1 — Manual Blocking (estimated 2 minutes):

  • Navigate to supplier.viator.com (your authenticated session)
  • Locate product ID 5653407P1 in your product inventory
  • Go to Manage Availability section
  • Find May 30 in the calendar grid
  • Toggle the date to "unavailable" and save

This is a stop-gap that prevents further bookings from the Viator channel while we resolve the integration question. The downside: it's manual and doesn't scale. That's why Step 2 matters.

The Technical Question That Matters: iCal Polling

Our reply to James Jimenez (draft pending your review) asks a more specific technical question than the original inquiry:

"Does Viator expose an iCal URL for confirmed supplier bookings that I can poll from my own system, or is dashboard connectivity the only self-serve option?"

Why this question? Because some travel suppliers (Airbnb, VRBO, Booking.com) publish iCal feeds even without explicit API partnerships. A booking confirmation system can expose its data via an iCal calendar URL that external systems can fetch at intervals. This is simpler than API authentication and doesn't require partner vetting.

The iCal approach would work like this:


# Pseudo-code for polling an iCal feed
GET https://supplier.viator.com/bookings/ical?property_id=5653407P1&auth_token=xxx

# Parses iCal/ics format, extracts booked dates
# Compares against our internal availability calendar
# Flags conflicts for manual review or auto-blocks via supplier API

# Can run on a schedule (every 2 hours, etc.) without heavy coupling

If Viator provides this, we can build a lightweight scheduled job that:

  • Fetches the iCal feed at intervals (CloudWatch Events triggering a Lambda or cron job)
  • Parses event dates using a standard iCal library
  • Compares booked dates against our internal Postgres availability table
  • Logs conflicts to CloudWatch Logs for alerting
  • Optionally auto-blocks dates via Viator's supplier API (if available)

This avoids the cost and operational overhead of a paid channel manager while maintaining real-time sync between systems.

Fallback: FareHarbor Integration

If Viator doesn't offer an iCal feed, FareHarbor is the only certified partner that doesn't charge operators a monthly subscription. FareHarbor's model charges guests (not suppliers) a small service fee, making it the only paid-partner option that fits our constraints.

However, FareHarbor integration is a larger architectural decision requiring:

  • OAuth2 flow setup (FareHarbor provides a developer app credentials)
  • Webhook endpoint for booking notifications (would require a public HTTPS endpoint with request signing validation)
  • Data transformation layer to map FareHarbor booking schema to our internal models
  • Testing against FareHarbor's sandbox environment before production cutover

This is off-the-table until we exhaust the iCal option.

Key Decisions Made

  • Manual blocking first: Calendar conflicts are a customer-facing problem that can't wait for engineering. A 2-minute manual fix is better than overselling.
  • Targeted follow-up question: Instead of asking "how do we integrate?", we asked "does an iCal feed exist?" This forces Viator to either confirm an undocumented feature or explicitly rule it out—no more boilerplate.
  • Document the vendor response: We archived the full email thread in the ticket system (t-ad4b92d7) so future engineers understand why we did or didn't pursue each option.

What's Next

James Jimenez's reply to our iCal question will determine the path:

  • If yes: Build a Lambda-based iCal polling job, schedule it via EventBridge, and integrate with our availability sync service. Add monitoring/alerting to CloudWatch.
  • If no: Evaluate FareHarbor integration as the least-friction paid option, or accept manual calendar management as the long-term solution.
  • If unclear: Request technical documentation from Viator's integration team (not support) and set a deadline for their response.

For now, May 30 is blocked manually, and we have a clear technical question pending vendor response. The next phase depends entirely on that answer.