Viator APIs

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: '/* ----------------------------------------------------------------------

    Stripe-inspired look & feel for the Viator Reservation System API docs.'
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.


        Viator prioritizes callbacks for Event notifications based on the `updateType`.

        - "AVAILABILITY" and "PRICING" notifications receive the highest priority.

        - "CAPACITY" notifications are prioritized using several factors, including the proximity to the travel date.


        NOTE: If both "AVAILABILITY" and "CAPACITY" types are received in the same notification, the "CAPACITY" priority is used.


        **Automated Event Notification Enablement**


        Notifications must be sent only for **already connected product options**. Therefore, Event Notifications **must be enabled** for a product option immediately after a Calendar API request is received for that product option.


        **Automated Event Notification Disablement**


        Notifications 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:

        - INVALID_SUPPLIER

        - INVALID_PRODUCT_OPTION


        Disabling event notifications for affected product options will prevent further failed requests and increased error rates.


        **NOTE**: If a calendar request is subsequently received for a previously disabled product option, notifications **must be re-enabled**.


        The event notifications endpoint replaces the existing V1.0 Availability Notification 2 API.'
      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.


        Special Offers notification triggers Viator to request additional details via the Special Offers endpoint **if the special offer is associated with an already connected product option**. This association is determined via the Calendar or Availability check endpoints.


        **Automated Special Offers Notification Enablement**


        Notifications 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 request is received for that product option.


        **Automated Special Offers Notification Disablement**


        Notifications for a product option must be disabled if a **422 Unprocessable Content** HTTP status code is received with any of the following errors:

        - INVALID_SUPPLIER


        Disabling Special Offers notifications for affected product options will prevent further failed requests and increased error rates.


        **NOTE**: If a calendar request is subsequently received for a previously disabled product option, notifications **must be re-enabled**.'
      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
    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
    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
    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
    BaseRequest:
      type: object
      description: Base request object.
      required:
      - supplierId
      properties:
        supplierId:
          $ref: '#/components/schemas/SupplierId'
    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
    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
    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'
    SupplierId:
      type: integer
      description: Viator’s unique Supplier identifier.
      example: 3456
  examples:
    eventNotificationRequest:
      value:
        supplierId: 123
        updateType:
        - AVAILABILITY
        - PRICING
        productOptionIds:
        - r1172330
        - r1172331
        startDate: '2025-01-01'
        endDate: '2025-12-31'
    SpecialOffersRequest:
      value:
        supplierId: 3456
        specialOfferIds:
        - A Unique id
        - A-unique-id-2
    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
    eventNotificationResponse:
      value:
        results:
        - productOptionId: r1172330
          status: 200
        - productOptionId: r1172331
          status: 422
          error: INVALID_PRODUCT_OPTION
    eventNotificationUnprocessableResponse:
      value:
        error: INVALID_PRODUCT_OPTION
        message: All product options are invalid
  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