Viator Viator APIs API

openapi: 3.2.0
info:
  title: Viator Reservation System Viator APIs API
  x-logo:
    url: resources/img/sapi/Viator_Logo_RGB_Green.png
    altText: Viator
    href: https://www.viator.com
  contact:
    name: API Integrations Support
    email: supplierAPI@viator.com
  version: ''
  description: "<style>\n/* ----------------------------------------------------------------------\n   Stripe-inspired look & feel for the Viator Reservation System API docs.\n   Layout (3-panel nav/content/code) is provided by Redoc; this layer adds\n   typography, spacing and accent polish using Viator brand colors.\n   Accent teal #00876A · dark code rail #0a2a2e · light sidebar #f6f8f8\n   Type matches Stripe's scale (16px/400 body, weight-500 headings) and\n   uses Stripe's own font stack (Söhne -> system fallback) set in redocly.yaml.\n   ---------------------------------------------------------------------- */\n\n/* Logo: Viator wordmark, top-left of the sidebar (Stripe-style placement) */\nimg[alt=\"Viator\"] {\n    height: 30px;\n    width: auto;\n    max-width: 80%;\n    margin: 16px 0 10px 16px;\n    display: block;\n}\n\n/* Smoother text rendering, closer to Stripe's docs */\nbody,\n.redoc-wrap,\n[data-component-id] {\n    -webkit-font-smoothing: antialiased;\n    -moz-osx-font-smoothing: grayscale;\n    text-rendering: optimizeLegibility;\n}\n\n/* Headings: match Stripe's type scale (weight 500, generous sizes, tight\n   tracking). Scoped to .api-content with !important to win over Redoc's\n   built-in heading sizes. */\n.api-content h1, .api-content h2, .api-content h3,\n.api-content h4, .api-content h5 {\n    font-weight: 500 !important;\n}\n.api-content h1 {\n    font-size: 38px !important;\n    line-height: 48px !important;\n    letter-spacing: -0.02em !important;\n}\n.api-content h2 {\n    font-size: 28px !important;\n    line-height: 36px !important;\n    letter-spacing: -0.018em !important;\n}\n.api-content h3 {\n    font-size: 20px !important;\n    line-height: 28px !important;\n    letter-spacing: -0.012em !important;\n}\n.api-content h4, .api-content h5 {\n    font-weight: 600 !important;\n    letter-spacing: -0.006em !important;\n}\n\n/* Links: teal with a subtle hover underline */\na, a:visited {\n    color: #00876A;\n    text-decoration: none;\n}\na:hover {\n    color: #00694f;\n    text-decoration: underline;\n}\n\n/* Sidebar: light, airy, Stripe-like with a thin divider */\n.menu-content {\n    border-right: 1px solid #e3eae9;\n}\n.menu-content label[role=\"menuitem\"]:hover,\n.menu-content li[role=\"menuitem\"]:hover {\n    background-color: #eef3f2;\n}\n\n/* Active nav item: teal accent bar */\n.menu-content label.active,\n.menu-content li.active > label {\n    color: #00876A;\n    box-shadow: inset 3px 0 0 0 #00876A;\n}\n\n/* Search box: rounded, soft border to match Stripe's input style */\n[role=\"search\"] input,\n.search-input {\n    border: 1px solid #d7e0df !important;\n    border-radius: 8px !important;\n}\n\n/* Center and add border to all images (preserved from original) */\np img {\n    border-radius: 4px;\n    border: 1px solid #ddd;\n    margin-left: auto;\n    margin-right: auto;\n    display: block;\n    margin-bottom: 28px;\n}\n</style>\n\n# Introduction\nThese API specifications detail the technical requirements for integrating operator reservation systems with Viator. This guide is intended for developers and technical teams to ensure a standardized implementation and reliable data exchange.\n\n# Prerequisites\nAccess is restricted to operators registered with Viator and their authorized reservation system providers. Integration workflows may only proceed following technical evaluation and formal approval by Viator.\n\nFurthermore, development **may only commence** if Viator registered operators are using the reservation system. For operator onboarding details, please refer to the [supplier sign-up page](https://supplier.viator.com/sign-up-info).\n\n# Getting Started\nReview the following core components to begin your implementation:\n\n- [What’s new](#tag/What's-new)\n- [Connectivity overview](#tag/Connectivity-overview)\n- [API overview](#tag/API-overview)\n- [Implementation approach](#tag/Implementation-approach)\n- [Frequently asked questions](#tag/FAQs)\n\nAdherence to these specifications is crucial for successful integration, guaranteeing optimal performance, data integrity, and a superior user experience for both operators and Viator customers. \n\nIf at any point you need clarification or help, please don’t hesitate to [contact us here](#tag/Contact-us).\n"
servers:
- url: https://your-reservation-system.example.com
  description: Placeholder for the reservation system's own server — replace with your actual domain. Viator calls this host for all operations except event and special offer notifications, which are sent by the reservation system to Viator instead (see below).
tags:
- name: Viator APIs
  description: 'This section describes the Viator built API(s) available for reservation system consumption.


    **Note**: For these APIs, the request is sent **to** Viator and the response is received **from** Viator.'
paths:
  /v2/notification/events:
    post:
      summary: Event Notification
      operationId: eventNotification
      x-codeSamples:
      - lang: curl
        label: cURL
        source: "curl -X POST \"https://api.viator.com/v2/notification/events\" \\\n  -H \"X-Api-Key: <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"supplierId\": 123,\n  \"updateType\": [\n    \"AVAILABILITY\",\n    \"PRICING\"\n  ],\n  \"productOptionIds\": [\n    \"r1172330\",\n    \"r1172331\"\n  ],\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-12-31\"\n}'\n"
      - lang: JavaScript
        label: Node.js
        source: "const response = await fetch(\"https://api.viator.com/v2/notification/events\", {\n  method: \"POST\",\n  headers: {\n    \"X-Api-Key\": \"<YOUR_API_KEY>\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n  \"supplierId\": 123,\n  \"updateType\": [\n    \"AVAILABILITY\",\n    \"PRICING\"\n  ],\n  \"productOptionIds\": [\n    \"r1172330\",\n    \"r1172331\"\n  ],\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-12-31\"\n})\n});\nconst data = await response.json();\nconsole.log(data);\n"
      - lang: Python
        label: Python
        source: "import json\nimport requests\n\npayload = json.loads('''{\n  \"supplierId\": 123,\n  \"updateType\": [\n    \"AVAILABILITY\",\n    \"PRICING\"\n  ],\n  \"productOptionIds\": [\n    \"r1172330\",\n    \"r1172331\"\n  ],\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-12-31\"\n}''')\n\nresponse = requests.post(\n    \"https://api.viator.com/v2/notification/events\",\n    headers={\n        \"X-Api-Key\": \"<YOUR_API_KEY>\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=payload,\n)\nprint(response.json())\n"
      - lang: PHP
        label: PHP
        source: "<?php\n$payload = <<<'JSON'\n{\n  \"supplierId\": 123,\n  \"updateType\": [\n    \"AVAILABILITY\",\n    \"PRICING\"\n  ],\n  \"productOptionIds\": [\n    \"r1172330\",\n    \"r1172331\"\n  ],\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-12-31\"\n}\nJSON;\n\n$ch = curl_init(\"https://api.viator.com/v2/notification/events\");\ncurl_setopt($ch, CURLOPT_POST, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n    \"X-Api-Key: <YOUR_API_KEY>\",\n    \"Content-Type: application/json\",\n]);\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n$response = curl_exec($ch);\ncurl_close($ch);\necho $response;\n"
      tags:
      - Viator APIs
      description: "The event notifications endpoint allows reservation systems to inform Viator of changes to events that affect salability, pricing, or capacity for a given date range. This endpoint ensures rapid synchronization of event updates with Viator.\n\nViator prioritizes callbacks for Event notifications based on the `updateType`. \n- \"AVAILABILITY\" and \"PRICING\" notifications receive the highest priority. \n- \"CAPACITY\" notifications are prioritized using several factors, including the proximity to the travel date.\n\nNOTE: If both \"AVAILABILITY\" and \"CAPACITY\" types are received in the same notification, the \"CAPACITY\" priority is used. \n\n**Automated Event Notification Enablement**\n\nNotifications must be sent only for **already connected product options**. Therefore, Event Notifications **must be enabled** for a product option immediately after a [Calendar API](#tag/Reservation-system-APIs/operation/calendar) request is received for that product option.\n\n**Automated Event Notification Disablement** \n\nNotifications for a product option must be disabled if a **422 Unprocessable Content** or **207 Multiple-status response** HTTP status code is received with any of the following errors:\n- INVALID_SUPPLIER\n- INVALID_PRODUCT_OPTION\n\nDisabling event notifications for affected product options will prevent further failed requests and increased error rates.\n\n**NOTE**: If a calendar request is subsequently received for a previously disabled product option, notifications **must be re-enabled**.\n\nThe event notifications endpoint replaces the existing V1.0 [Availability Notification 2 API](#tag/Deprecated/operation/availabilityNotification2).\n"
      security:
      - ApiKeyHeader: []
      servers:
      - url: https://api.viator.com
        description: Placeholder for Viator's API host. This operation is sent by the reservation system to Viator, unlike most other operations, which use the reservation system's own host above.
      x-badges:
      - name: New
        color: '#00876A'
        position: after
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventNotificationRequest'
            examples:
              eventNotificationRequest:
                $ref: '#/components/examples/eventNotificationRequest'
      responses:
        '204':
          description: Success
        '207':
          description: Multi-status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventNotificationResponse'
              examples:
                eventNotificationResponse:
                  $ref: '#/components/examples/eventNotificationResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '408':
          description: Request Timeout
        '415':
          description: Unsupported Media Type
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventNotificationUnprocessableContentResponse'
              examples:
                eventNotificationUnprocessableResponse:
                  $ref: '#/components/examples/eventNotificationUnprocessableResponse'
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'
              examples:
                error500:
                  $ref: '#/components/examples/error500'
        '503':
          description: Service Unavailable
  /v2/notification/special-offers:
    post:
      x-badges:
      - name: New
        color: '#00876A'
        position: after
      summary: Special Offers Notification
      operationId: specialOffersNotification
      x-codeSamples:
      - lang: curl
        label: cURL
        source: "curl -X POST \"https://api.viator.com/v2/notification/special-offers\" \\\n  -H \"X-Api-Key: <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"supplierId\": 3456,\n  \"specialOfferIds\": [\n    \"A Unique id\",\n    \"A-unique-id-2\"\n  ]\n}'\n"
      - lang: JavaScript
        label: Node.js
        source: "const response = await fetch(\"https://api.viator.com/v2/notification/special-offers\", {\n  method: \"POST\",\n  headers: {\n    \"X-Api-Key\": \"<YOUR_API_KEY>\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n  \"supplierId\": 3456,\n  \"specialOfferIds\": [\n    \"A Unique id\",\n    \"A-unique-id-2\"\n  ]\n})\n});\nconst data = await response.json();\nconsole.log(data);\n"
      - lang: Python
        label: Python
        source: "import json\nimport requests\n\npayload = json.loads('''{\n  \"supplierId\": 3456,\n  \"specialOfferIds\": [\n    \"A Unique id\",\n    \"A-unique-id-2\"\n  ]\n}''')\n\nresponse = requests.post(\n    \"https://api.viator.com/v2/notification/special-offers\",\n    headers={\n        \"X-Api-Key\": \"<YOUR_API_KEY>\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=payload,\n)\nprint(response.json())\n"
      - lang: PHP
        label: PHP
        source: "<?php\n$payload = <<<'JSON'\n{\n  \"supplierId\": 3456,\n  \"specialOfferIds\": [\n    \"A Unique id\",\n    \"A-unique-id-2\"\n  ]\n}\nJSON;\n\n$ch = curl_init(\"https://api.viator.com/v2/notification/special-offers\");\ncurl_setopt($ch, CURLOPT_POST, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n    \"X-Api-Key: <YOUR_API_KEY>\",\n    \"Content-Type: application/json\",\n]);\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n$response = curl_exec($ch);\ncurl_close($ch);\necho $response;\n"
      description: "The special offers notifications endpoint allows reservation systems to inform Viator of new or updated special offers for a given date range. This endpoint ensures rapid synchronization of special offers details with Viator.\n\nSpecial Offers notification triggers Viator to request additional details via the [Special Offers](#tag/Reservation-system-APIs/operation/specialOffers) endpoint **if the special offer is associated with an already connected product option**. This association is determined via the [Calendar](#tag/Reservation-system-APIs/operation/calendar) or [Availability check](#tag/Reservation-system-APIs/operation/availabilityCheck) endpoints.\n\n**Automated Special Offers Notification Enablement**\n\nNotifications must be sent only for **already connected product options**. Therefore, Special Offers notifications **must be enabled** for a product option immediately after a [Calendar API](#tag/Reservation-system-APIs/operation/calendar) request is received for that product option.\n\n**Automated Special Offers Notification Disablement** \n\nNotifications for a product option must be disabled if a **422 Unprocessable Content** HTTP status code is received with any of the following errors:\n- INVALID_SUPPLIER\n\nDisabling Special Offers notifications for affected product options will prevent further failed requests and increased error rates.\n\n**NOTE**: If a calendar request is subsequently received for a previously disabled product option, notifications **must be re-enabled**.\n"
      security:
      - ApiKeyHeader: []
      servers:
      - url: https://api.viator.com
        description: Placeholder for Viator's API host. This operation is sent by the reservation system to Viator, unlike most other operations, which use the reservation system's own host above.
      tags:
      - Viator APIs
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecialOffersNotificationRequest'
            examples:
              specialOffersRequest:
                $ref: '#/components/examples/SpecialOffersRequest'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '408':
          description: Request Timeout
        '415':
          description: Unsupported Media Type
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentErrorResponse'
              examples:
                error422:
                  $ref: '#/components/examples/error422'
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'
              examples:
                error500:
                  $ref: '#/components/examples/error500'
        '503':
          description: Service Unavailable
components:
  schemas:
    EventNotificationResponse:
      type: object
      description: Response object for multi-status Event Notification
      required:
      - results
      properties:
        results:
          type: array
          description: List of event notifications status
          items:
            type: object
            title: EventNotificationResult
            description: List of requested event notification status.
            required:
            - productOptionId
            - status
            properties:
              productOptionId:
                $ref: '#/components/schemas/ProductOptionId'
              status:
                type: integer
                description: HTTP status of the event notification request for the product option
                enum:
                - 200
                - 422
                example: 200
              error:
                type: string
                description: "Code representing the error reason\nOne of:\n  - INVALID_PRODUCT_OPTION - The productOptionID in the request is not valid or does not exist for the supplier.\n"
                enum:
                - INVALID_PRODUCT_OPTION
                example: INVALID_PRODUCT_OPTION
    SpecialOffersNotificationRequest:
      type: object
      description: Request object for the Special Offers Notification Operation.
      required:
      - supplierId
      - specialOfferIds
      properties:
        supplierId:
          $ref: '#/components/schemas/SupplierId'
        specialOfferIds:
          type: array
          description: 'List of reservation system special offer identifiers for which additions or changes are being notified.


            Must be valid identifiers returned in the special offers endpoint.

            '
          items:
            type: string
            description: Unique identifier for the special offer.
            example: A Unique id
    ContentErrorResponse:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          type: string
          description: "Code representing error reason. \n\nOne of:\n  - INVALID_SUPPLIER - the requested supplier is not valid.\n  - API_DISABLED - API endpoint is not enabled for the requested supplier.\n"
          example: INVALID_SUPPLIER
        message:
          type: string
          description: Human readable description of the error reason
          example: Wrong Supplier ID
    InternalErrorResponse:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          type: string
          description: "Code representing error reason. One of:\n  - INTERNAL_ERROR\n"
          example: INTERNAL_ERROR
        message:
          type: string
          description: Human readable description of the error reason
          example: Unknown Error
    SupplierId:
      type: integer
      description: Viator’s unique Supplier identifier.
      example: 3456
    BaseRequest:
      type: object
      description: Base request object.
      required:
      - supplierId
      properties:
        supplierId:
          $ref: '#/components/schemas/SupplierId'
    EventNotificationUnprocessableContentResponse:
      type: object
      description: Response object for Unprocessable Content Event Notification
      required:
      - error
      properties:
        error:
          type: string
          description: "Code representing error reason. \n\nOne of:\n- INVALID_SUPPLIER - The supplier in the request is not valid or does not exist.\n- API_DISABLED - API endpoint is not enabled for the requested supplier.\n- INVALID_PRODUCT_OPTION - All productOptionIds in the request are invalid or do not exist for the supplier.\n- INVALID_DATE_RANGE - The requested date range is invalid.\n"
          enum:
          - INVALID_SUPPLIER
          - API_DISABLED
          - INVALID_PRODUCT_OPTION
          - INVALID_DATE_RANGE
          example: INVALID_PRODUCT_OPTION
        message:
          type: string
          description: Human readable description of the error reason
          example: All product options are invalid
    EventNotificationRequest:
      allOf:
      - $ref: '#/components/schemas/BaseRequest'
      - type: object
        description: Request object for Event Notification
        required:
        - updateType
        - productOptionIds
        - startDate
        - endDate
        properties:
          updateType:
            type: array
            description: "List of Machine-interpretable values to specify notification types. \n\nOne of:\n- AVAILABILITY - Used when the remaining capacity for any ticket type associated to the event has either become:\n  - **Unavailable** for sale from previously being available (i.e. ticket type capacity becomes 0). \n  - **Available** for sale from previously being unavailable for sale. (i.e. ticket type capacity becomes greater than 0)\n- PRICING - Used when the retail price of any relevant ticket type for an event changes (inclusive of new special offers or discounts). For operators with a specific Viator agreement to use net price, a change to the net price also requires notification.\n- CAPACITY - Used when any capacity changes not covered by an \"AVAILABILITY\" update occur.\n"
            items:
              type: string
              title: EventUpdateType
              enum:
              - AVAILABILITY
              - PRICING
              - CAPACITY
          productOptionIds:
            type: array
            description: 'List of reservation system product option identifiers for which AVAILABILITY, PRICING, or CAPACITY changes are being notified.

              '
            items:
              $ref: '#/components/schemas/ProductOptionId'
          startDate:
            type: string
            format: date
            description: 'The start date for the notification. Value is in date format **YYYY-MM-DD**.

              '
            example: '2026-01-21'
          endDate:
            type: string
            format: date
            description: 'The end date for the notification. Value is in date format **YYYY-MM-DD**.

              '
            example: '2026-01-25'
    ProductOptionId:
      type: string
      description: "Unique reservation system product option identifier. \nThis identifier is sourced from the [Tour List API](#operation/tourList) response.\n"
      example: r1172330
  examples:
    eventNotificationUnprocessableResponse:
      value:
        error: INVALID_PRODUCT_OPTION
        message: All product options are invalid
    error500:
      summary: Internal Server Error
      value:
        error: INTERNAL_ERROR
        message: Unknown internal error
    error422:
      summary: Unprocessable Content error
      value:
        error: INVALID_SUPPLIER
        message: Invalid supplier ID
    SpecialOffersRequest:
      value:
        supplierId: 3456
        specialOfferIds:
        - A Unique id
        - A-unique-id-2
    eventNotificationResponse:
      value:
        results:
        - productOptionId: r1172330
          status: 200
        - productOptionId: r1172331
          status: 422
          error: INVALID_PRODUCT_OPTION
    eventNotificationRequest:
      value:
        supplierId: 123
        updateType:
        - AVAILABILITY
        - PRICING
        productOptionIds:
        - r1172330
        - r1172331
        startDate: '2025-01-01'
        endDate: '2025-12-31'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
x-tagGroups:
- name: Getting started
  tags:
  - What's new
  - Implementation approach
  - API overview
  - Connectivity overview
  - API configurations
- name: API reference
  tags:
  - Reservation system APIs
  - Viator APIs
  - Beta
- name: Reliability & testing
  tags:
  - SLAs
  - Circuit breakers
  - Contract testing
- name: Resources
  tags:
  - v2 migration guide
  - FAQs
  - Contact us
  - Appendices
- name: Deprecated
  tags:
  - Deprecated