Viator Integration

EquipDash integrates with Viator on their V2 supplier API. The integration is bidirectional: Viator calls EquipDash inbound endpoints, and EquipDash pushes event notifications outbound when availability or pricing changes.

This page documents the inbound endpoints EquipDash hosts. Suppliers configure the integration from Settings → API & Integrations → Viator.

Authentication

Every Viator inbound request must include a Bearer token in the Authorization header. The token is the per-supplier inbound API key configured during setup.

Authorization: Bearer <inbound_api_key>

Invalid or missing tokens return 401 AUTHORIZATION_FAILURE.

Base Path

POST /viator/api/...

Endpoints

POST /viator/api/tourlist

Returns the supplier's mapped product catalogue, including tour options and departure times.

Response shape:

{
  "products": [
    {
      "SupplierProductCode": "EDX-KAYAK-001",
      "SupplierProductName": "Sunset Kayak Tour",
      "CountryCode": "AU",
      "DestinationCode": "AU-SYD",
      "TourOptions": [
        {
          "SupplierOptionCode": "EDX-KAYAK-001-ADULT",
          "SupplierOptionName": "Adult",
          "AgeBand": "ADULT",
          "TourDepartureTimes": ["09:00:00", "13:00:00", "16:00:00"]
        }
      ]
    }
  ]
}

DestinationCode is omitted if not configured on the connection.

POST /viator/api/v2/availability/check

Real-time availability check. Must respond in under 5 seconds per Viator SLA.

Request:

{
  "SupplierProductCode": "EDX-KAYAK-001",
  "TourOption": "ADULT",
  "TravelDate": "2026-06-15",
  "TourDepartureTime": "09:00:00",
  "Travellers": [
    {"ageBand": "ADULT", "count": 2},
    {"ageBand": "CHILD", "count": 1}
  ]
}

Response (AVAILABLE):

{
  "availability": "AVAILABLE",
  "capacity": 10,
  "remaining": 7,
  "bookingCutoff": "2026-06-15T07:30:00+00:00",
  "bookingCutoffHoursBefore": 1.5,
  "pricing": [
    {"ageBand": "ADULT", "price": 50.00, "currency": "USD"},
    {"ageBand": "CHILD", "price": 30.00, "currency": "USD"}
  ],
  "unavailabilityReason": null
}

Unavailable reasons: SOLD_OUT, PAST_CUTOFF.

POST /viator/api/v2/availability/calendar

Long-range availability (365+ days). Typically called once or twice a day.

Request:

{
  "SupplierProductCode": "EDX-KAYAK-001",
  "DateFrom": "2026-05-01",
  "DateTo": "2027-04-30"
}

Response: Array of per-slot availability entries with status, capacity, remaining, bookingCutoff, and pricing.

POST /viator/api/v2/reserve

Creates an AvailabilityHold — a temporary inventory hold while a traveller completes checkout. Default TTL is 600 seconds (10 minutes). An expired hold auto-releases capacity.

Response:

{
  "availabilityHold": {
    "reference": "HOLD-3f2a...",
    "expiresAt": "2026-06-15T07:25:00+00:00",
    "expiresIn": "PT600S"
  },
  "status": "CONFIRMED"
}

POST /viator/api/v2/booking

Confirms a booking. Include AvailabilityHold.Reference to honour a prior Reserve, and ContactEmail for the customer's email.

Request:

{
  "SupplierProductCode": "EDX-KAYAK-001",
  "TravelDate": "2026-06-15",
  "TourDepartureTime": "09:00:00",
  "AvailabilityHold": {"Reference": "HOLD-3f2a..."},
  "ContactEmail": "traveller@example.com",
  "ContactPhone": "+15551234567",
  "Travellers": [
    {"firstName": "John", "lastName": "Doe", "ageBand": "ADULT"}
  ],
  "ViatorBookingReference": "V-12345"
}

Response:

{
  "BookingReference": "ED-87321",
  "TransactionStatus": {"Status": "CONFIRMED"},
  "TravellerConfirmations": [
    {"travellerNumber": 1, "confirmation": "ED-87321-1"}
  ],
  "TourBarcode": "BASE64-ENCODED..."
}

Duplicate requests (same ViatorBookingReference, already confirmed) return the original booking — the endpoint is idempotent.

Common failures: HOLD_NOT_FOUND, HOLD_EXPIRED, NO_AVAILABILITY, VALIDATION_FAILURE.

POST /viator/api/v2/booking/cancel

Cancels an existing booking.

Request: { "BookingReference": "ED-87321", "CancellationReason": "Customer requested" }

Response: { "BookingReference": "ED-87321", "TransactionStatus": {"Status": "CANCELLED"} }

POST /viator/api/v2/booking/amend

Changes date, time, or travellers on an existing booking.

Request:

{
  "BookingReference": "ED-87321",
  "TravelDate": "2026-06-16",
  "TourDepartureTime": "13:00:00",
  "Travellers": [
    {"firstName": "John", "lastName": "Doe", "ageBand": "ADULT"},
    {"firstName": "Jane", "lastName": "Doe", "ageBand": "ADULT"}
  ]
}

Response: { "BookingReference": "ED-87321", "TransactionStatus": {"Status": "AMENDED"} }

Outbound Events

EquipDash pushes a debounced (30s) notification to Viator's event endpoint whenever the following happen on a mapped experience:

Change	Condition
Availability create / update / delete	push_availability_changes = true
Pricing create / update / delete	push_pricing_changes = true

Payload shape (POST to the configured Viator event URL):

{
  "supplierProductCode": "EDX-KAYAK-001",
  "changeType": "availability",
  "affectedDates": ["2026-06-15", "2026-06-16"]
}

Failed pushes are retried with exponential backoff (30s, 2m, 10m, 1h, 6h) up to 5 times.

Quality SLAs

Viator requires:

• Availability endpoint p95 < 5 seconds.
• Booking failure rate < 10%.

EquipDash measures both per-supplier every 24 hours. Results surface in the Settings → Viator → Health panel and raise internal alerts when thresholds are crossed.

Error Codes

Code	HTTP	Meaning
AUTHORIZATION_FAILURE	401	Missing / invalid inbound API key, or connection is inactive
INVALID_PRODUCT	404	SupplierProductCode not mapped
INVALID_BOOKING	404	Unknown BookingReference
VALIDATION_FAILURE	400	Missing / malformed fields
NO_AVAILABILITY	400	Slot sold out or past cutoff
HOLD_NOT_FOUND	400	Unknown AvailabilityHold.Reference
HOLD_EXPIRED	400	Hold TTL elapsed before booking
BOOKING_ALREADY_CANCELED	400	Cancellation of a cancelled booking
INTERNAL_SYSTEM_FAILURE	500	Unexpected error — payload logged