openapi: 3.1.0 info: title: Tiqets Distributor API version: 2.7.0 termsOfService: https://portals.tiqets.com/distributorapi/terms-of-service contact: email: distributorapi@tiqets.com servers: - url: https://api.tiqets.com/v2 description: Production Environment - url: https://api-tiqt-test.steq.it/v2 description: Test Environment (until February 4th, 2026) - url: https://api.api-tiqt-test.steq.it/v2 description: Test Environment (from February 4th, 2026) tags: - name: Content API - name: Availability & Pricing API - name: Booking API - name: Notification Subscriptions API paths: /products: get: tags: - Content API summary: Search and filter products parameters: - $ref: '#/components/parameters/Authorization' - name: city_id in: query required: false description: | Only return products located in the defined city. Use the [/cities](#tag/Content-API/paths/~1cities/get) endpoint to find the IDs Tiqets has assigned to the various known cities. Products located in the surrounding area can also be returned, this depends on the configuration of each individual product. Repeat the city_id parameter to broaden the search to span multiple cities. schema: type: integer example: 113 explode: true - name: city_name in: query required: false description: Name of the city to filter by. Useful for debugging or certain use cases. We recommend using `city_id` instead. schema: type: string example: Barcelona - name: country_id in: query required: false description: Tiqets ID of the product country to filter by. schema: type: integer example: 50233 - name: country_name in: query required: false description: Name of the country to filter by. Useful for debugging or certain use cases. We recommend using `country_id` instead. schema: type: string example: United States - $ref: '#/components/parameters/Currency' - name: exclude_city_id description: Exclude products from the results if they belong to the specified city. in: query required: false schema: type: integer example: 113 explode: true - name: exclude_venue_id description: Exclude products from the results if they belong to the specified experience. in: query required: false schema: type: integer example: 145528 - $ref: '#/components/parameters/Language' - name: lat description: Filters the result set by latitude. Requires a combination of latitude/longitude parameters. Also see `max_distance`. in: query required: false schema: type: number example: 40.74844100000001 - name: lng in: query required: false description: Filters the result set by longitude. Requires a combination of latitude/longitude parameters. Also see `max_distance`. schema: type: number example: -73.9856616352348 - name: max_distance description: Maximum distance in kilometers to filter results by. Value can be between 0 and 100; defaults to 5 if undefined. in: query required: false schema: type: integer minimum: 1 maximum: 100 - name: min_rating description: Minimum rating of the product in customer reviews. in: query required: false schema: type: integer minimum: 1 maximum: 5 example: 1 - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/Page' - name: query description: | Textual query to find products that match the query. The results are ranked by internal calculation of relevancy which can change over time. Adding more keywords narrows down the results. in: query required: false schema: type: string example: Sagrada Familia - name: require_venue description: Define as true if you do not wish to include products that do not have a determined venue location. Defaults to false if undefined. in: query required: false schema: type: boolean default: false - name: sort description: | Sort by - `popularity` - `price` - `title` - `distance` (in combination with `lat`/`lng`) - `score` (Search query matching score. Only in combination with the `query` parameter). Sort ascending (`asc`) or descending (`desc`). in: query required: false schema: type: string example: distance desc explode: true - name: tag_id description: | ID of the tag to filter by. See tags endpoint. Repeat the tag_id parameter to broaden the search to include one or more of the provided tag IDs. in: query required: false schema: type: integer example: 312 explode: true - name: exclude_tag_id description: | ID of the tag to exclude from results. Products associated with the specified tag will not be returned. Repeat the exclude_tag_id parameter to exclude products matching any of the provided tag IDs. in: query required: false schema: type: integer example: 312 explode: true - name: exclude_packages description: If true, only individual products are returned and package products are excluded from the results. Defaults to false if undefined. in: query required: false schema: type: boolean default: false - name: experience_id in: query required: false description: | ID of the experience to filter by. Experiences can be searched and retrieved using the dedicated Experiences endpoint. Repeat the experience_id parameter to broaden the search to span multiple experiences. Note that this parameter is not allowed together with venue_id that is deprecated. schema: type: integer example: 145528 explode: true - name: venue_id deprecated: true in: query required: false description: | ID of the experience to filter by. Experiences can be searched and retrieved using the dedicated Experiences endpoint. Repeat the venue_id parameter to broaden the search to span multiple experiences. Note that this parameter is deprecated and experience_id is recommended. If you specify this and experience_id, it will trigger an error. schema: type: integer example: 145528 explode: true responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean pagination: $ref: '#/components/schemas/Pagination' products: $ref: '#/components/schemas/ProductList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /products/{productId}: get: summary: Get single product tags: - Content API parameters: - name: productId in: path description: The ID of a product. required: true schema: type: integer example: 974092 - $ref: '#/components/parameters/Currency' - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean product: $ref: '#/components/schemas/Product' product_groups: type: array items: $ref: '#/components/schemas/ProductGroup' deprecated: true description: Moved to inside `product` '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /products/{productId}/checkout_information: get: summary: Product checkout information tags: - Content API parameters: - name: productId in: path description: The ID of product required: true schema: type: integer example: 974092 - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean has_timeslots: type: boolean description: Indicates whether the product has timeslots. has_dynamic_pricing: type: boolean deprecated: true description: Indicates whether the product has dynamic pricing. additional_information: type: object description: Additional information regarding the product. properties: must_know: type: - string - 'null' description: Important information. Mandatory to be displayed in the checkout before buying tickets. Will be displayed on the voucher. good_to_know: type: - string - 'null' description: Additional information. Mandatory to be displayed in the checkout before buying tickets. pre_purchase: type: - string - 'null' description: Pre-purchase information. Mandatory to be displayed in the checkout before buying tickets. post_purchase: type: - string - 'null' description: Post-purchase information. usage: type: - string - 'null' description: Instructions of how to use the tickets. Will be displayed on the voucher. included: type: - string - 'null' description: Description of what is included in the ticket. excluded: type: - string - 'null' description: Description of what is explicitly not included in the ticket. customer_data_required_on_create_order: type: boolean deprecated: true description: This element can be ignored and is only returned for compatibility with legacy integrations. Always `true`. example: success: true additional_information: must_know: In the event of bad weather, outdoor attractions may be temporarily closed. good_to_know: To get to the venue foolow these instructions.... pre_purchase: Kids under 122 cm must be accompanied by an adult. usage: Enter the museum via the main door and show your ticket at the entrance. excluded: Entrance to Dolphin Island or S.E.A. Aquarium. included: Life jackets post_purchase: This is a fixed date ticket. You can only use this ticket on the date shown on your voucher. has_timeslots: true has_dynamic_pricing: true customer_data_required_on_create_order: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '501': description: Not Implemented '503': $ref: '#/components/responses/ServiceUnavailable' /products/{productId}/reviews: get: tags: - Content API summary: Get reviews for a product parameters: - name: productId in: path description: The ID of product required: true schema: type: integer example: 974092 - $ref: '#/components/parameters/Authorization' - name: lang in: query description: Filter by reviews in a specific language. schema: type: string - name: start_date in: query description: Filter by start date (inclusive) schema: type: string format: date example: '2025-01-01' - name: end_date in: query description: Filter by end date (exclusive) schema: type: string format: date example: '2025-01-01' - name: page in: query description: Pagination offset (default 1) schema: type: integer example: '2' - name: page_size in: query description: Number of results per page (default 20) schema: type: integer example: '20' - name: sort_by in: query description: Define which field is used to sort the results. schema: type: string default: date enum: - date - rating - relevance example: rating - name: sort_direction in: query description: Define whether the results are sorted in ascending or descending order. schema: type: string default: desc enum: - asc - desc example: desc - name: min_rating in: query description: 'filter by rating (min: 1, max: 5)' schema: type: integer example: 5 - name: traveler_type in: query description: Filter on the type of travel schema: allOf: - $ref: '#/components/schemas/traveler_type' example: friends responses: '200': description: Successful operation. content: application/json: schema: type: object properties: product_id: type: integer example: 5432 product_reviews: type: array items: $ref: '#/components/schemas/ProductReview' pagination: $ref: '#/components/schemas/Pagination' examples: simple-example: value: product_id: 1234 product_reviews: - id: 62948 author: Jane Doe traveler_type: friends rating: 4 rating_per_category: value_for_money: 4 info_onsite: 5 body: Splendid experience! Highly recommended. language: en date: '2025-01-01' source: Tiqets - id: 62382 author: Jean Doe traveler_type: family rating: 4 rating_per_category: value_for_money: 4 info_onsite: 5 body: C'etait vraiement génial! Je le recommande. language: fr date: '2025-01-01' source: Tiqets pagination: total: 2 page: 1 page_size: 20 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '501': description: Not Implemented '503': $ref: '#/components/responses/ServiceUnavailable' /products/{productId}/reviews/summary: get: tags: - Content API summary: Get a review summary for a product description: Retrieves detailed rating information and an AI summary for a specific product. parameters: - name: productId in: path description: The ID of product required: true schema: type: integer example: 974092 - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ProductReviewSummary' example: product_id: 12345 average_rating: 4.3 rating_count: 128 rating_distribution: '1': count: 2 percentage: 1.6 '2': count: 3 percentage: 2.3 '3': count: 10 percentage: 7.8 '4': count: 35 percentage: 27.3 '5': count: 78 percentage: 60.9 average_rating_per_category: value_for_money: 4.8 info_onsite: 3.5 average_rating_per_traveler_type: alone: 5 friends: 5 partner: 5 family: 4.6 colleagues: 4.8 reviews_summary: Customers recommended the Guinness Storehouse for its informative self-guided tour, covering the history and brewing process of Guinness. Many appreciated the panoramic views from the Gravity Bar and the free pint included. However, customers mentioned it can be crowded, especially at the bar, and advised booking tickets in advance. supplier_average_rating: 4.5 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '501': description: Not Implemented '503': $ref: '#/components/responses/ServiceUnavailable' /products/{product_id}/recommendations/alternative: get: tags: - Content API summary: Get product alternatives description: Returns a list of alternative product recommendations based on the given product ID for when the product is unavailable. parameters: - name: product_id in: path required: true schema: type: integer description: The ID of the product to get alternatives for. - name: sort_by in: query required: false schema: type: string enum: - commission - conversion_rate - balanced default: balanced description: Sorting criterion. - $ref: '#/components/parameters/Currency' - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ProductAlternativeResponse' examples: successResponse: summary: Successful response value: recommendations: - product_id: 67890 title: Louvre - Group tour image_url: https://cdn.tiqets.com/louvre.jpg from_price: amount: 59.99 currency: USD - product_id: 54321 title: Louvre - Group tour (exhibition included) image_url: https://cdn.tiqets.com/louvre.jpg from_price: amount: 79.99 currency: USD '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /products/{product_id}/recommendations/cross-sell: get: tags: - Content API summary: Get product cross-sell options description: Returns a list of product recommendations that can be cross-sold based on the given product ID. parameters: - name: product_id in: path required: true schema: type: integer description: The ID of the product to get alternatives for. - name: sort_by in: query required: false schema: type: string enum: - commission - conversion_rate - balanced default: balanced description: Sorting criterion. - name: max_per_experience in: query description: Maximum number of variations/options to show per specific museum/experience. schema: type: integer default: 1 example: 1 - name: exclude_product_ids in: query description: A comma-separated list of product IDs to exclude from results (e.g., products already in cart). style: form explode: false schema: type: array items: type: integer example: - 1001 - 1002 - name: product_tag_ids in: query description: Filter recommendations by specific tag IDs (e.g., "Guided tour"). style: form explode: false schema: type: array items: type: integer example: - 5 - 12 - $ref: '#/components/parameters/Currency' - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful response. content: application/json: schema: $ref: '#/components/schemas/ProductCrossSellOptionsResponse' examples: museum_example: summary: Successful response value: filters: exclude_product_ids: - 1001 product_tag_ids: - 5 max_per_experience: 1 recommendations: - product_id: 67890 title: Louvre - Group tour image_url: https://cdn.tiqets.com/louvre.jpg from_price: amount: 59.99 currency: USD - product_id: 54321 title: Louvre - Group tour (exhibition included) image_url: https://cdn.tiqets.com/louvre.jpg from_price: amount: 79.99 currency: USD '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /experiences: get: tags: - Content API summary: Search and filter experiences parameters: - $ref: '#/components/parameters/Authorization' - name: city_id in: query required: false description: | Only return experiences located in the defined city. Use the [/cities](#tag/Content-API/paths/~1cities/get) endpoint to find the IDs Tiqets has assigned to the various known cities. Experiences located in the surrounding area can also be returned, this depends on the configuration of each individual product. Repeat the city_id parameter to broaden the search to span multiple cities. explode: true schema: type: integer example: 113 - name: country_id in: query required: false description: | Only return experiences located in the defined country. Use the [/countries]#tag/Content-API/paths/~1countries/get) endpoint to find the IDs Tiqets has assigned to the various known countries. Experiences located in the surrounding area can also be returned, this depends on the configuration of each individual product. Repeat the country_id parameter to broaden the search to span multiple countries. explode: true schema: type: integer example: 50233 - name: type in: query required: false explode: true schema: type: string example: activity enum: - venue - activity - service - poi description: Only return experiences with the defined type. - $ref: '#/components/parameters/Currency' - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/Page' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean pagination: $ref: '#/components/schemas/Pagination' experiences: $ref: '#/components/schemas/ExperienceList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /experiences/{experienceId}: get: summary: Get single experience tags: - Content API parameters: - name: experienceId in: path description: The ID of an experience. required: true schema: type: integer example: 145761 - $ref: '#/components/parameters/Currency' - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean experience: $ref: '#/components/schemas/Experience' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /tags: get: summary: Get list of tags tags: - Content API parameters: - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/Page' - name: type_name in: query description: Name of the type of tags to retrieve; i.e. 'category', 'time_of_day', etc. required: false schema: type: string example: category description: Name of the type of tags to retrieve; i.e. 'category', 'time_of_day', etc. - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean pagination: $ref: '#/components/schemas/Pagination' tags: type: array items: $ref: '#/components/schemas/Tag' example: success: true pagination: total: 5 page: 1 page_size: 100 tags: - id: '1188' name: Couples type_name: Traveler type type_id: '273' type_group_name: Activity categories - id: '1041' name: Hop-On Hop-Off type_name: Tours type_id: '236' type_group_name: Product Sub-categories - id: '726' name: National Parks type_name: Nature type_id: '140' type_group_name: Activity categories - id: '702' name: History Museums type_name: Museums type_id: '137' type_group_name: Product Sub-categories - id: '703' name: Science & Technology Museums type_name: Museums type_id: '137' type_group_name: Activity categories '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /tags/{tagId}: get: summary: Get a single tag tags: - Content API parameters: - name: lang in: query description: Localized language of the tags to retrieve. Defaults to English if undefined. required: false schema: type: string default: en example: en - name: tagId in: path description: ID of the tag to retrieve. required: true schema: type: integer example: 315 - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean tag: $ref: '#/components/schemas/Tag' example: success: true tag: id: '1645' name: Karaoke type_name: Indoor Adventure type_id: '351' type_group_name: Service categories '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /tag_types: get: summary: Get tag types tags: - Content API parameters: - name: lang in: query description: Language of the tags to retrieve. Defaults to English if undefined. required: false schema: type: string example: en description: Language of the tags to retrieve. - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean tag_types: type: array items: type: object properties: id: type: integer description: The ID of the tag type. name: type: string description: The name of the tag type. group_name: type: string description: The name of the group of tags the tag is included in. example: Service categories example: success: true tag_types: - id: 137 name: Museums group_name: Venue categories - id: 2 name: best_time_of_day group_name: Product characteristics - id: 354 name: Hop-On Hop-Off group_name: Product Sub-categories '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /cities: get: summary: Get list of cities tags: - Content API parameters: - name: country_id in: query description: Country ID to filter cities by. required: false schema: type: integer example: 50 description: Country ID to filter cities by. - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean pagination: $ref: '#/components/schemas/Pagination' cities: type: array items: $ref: '#/components/schemas/City' example: success: true pagination: total: 252 page_size: 100 page: 1 cities: - country_name: Mexico country_id: '50157' id: '109534' name: Isla Mujeres - country_name: Mexico country_id: '50157' id: '74201' name: Puerto Vallarta '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /cities/{cityId}: get: summary: Get single city tags: - Content API parameters: - $ref: '#/components/parameters/Language' - name: cityId in: path description: ID of city to return. required: true schema: type: integer example: 67441 - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean city: $ref: '#/components/schemas/City' example: success: true city: country_name: United Kingdom country_id: '50076' id: '67441' name: Manchester '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /countries: get: summary: Get list of countries tags: - Content API parameters: - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean pagination: $ref: '#/components/schemas/Pagination' countries: type: array items: $ref: '#/components/schemas/Country' example: success: true pagination: total: 252 page_size: 100 page: 1 countries: - id: '50001' name: United Arab Emirates - id: '50003' name: Antigua and Barbuda '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /countries/{countryId}: get: summary: Get single country tags: - Content API parameters: - $ref: '#/components/parameters/Language' - name: countryId in: path description: ID of the country to return. required: true schema: type: integer example: 50047 - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean country: $ref: '#/components/schemas/Country' example: success: true country: id: '50166' name: Netherlands '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /products/{productId}/opening_times: get: summary: Product opening times tags: - Availability & Pricing API parameters: - $ref: '#/components/parameters/ProductId' - $ref: '#/components/parameters/Language' - name: start_date in: query description: First day for which to return opening times. required: false schema: type: string format: date example: '2020-03-21' - name: end_date in: query description: Last day for which to return opening times. The maximum time range is 90 days; retrieving opening times for more than 90 days in one API request results in an error. required: false schema: type: string format: date example: '2020-03-25' - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean opening_times: type: array items: $ref: '#/components/schemas/OpeningTimes' examples: opening-times-defined_one_entity: summary: Opening times for one entity description: Product that has opening times defined for one entity. value: success: true opening_times: openings: - date: '2025-06-11' from_time: '09:10' to_time: '21:45' timezone: US/Eastern - date: '2025-06-12' from_time: '09:00' to_time: '21:30' timezone: US/Eastern entity_name: '' opening-times-defined_two_entities: summary: Opening times for two entities description: Product that has opening times defined for two entities. value: success: true opening_times: - openings: - date: '2025-06-11' from_time: '08:30' to_time: '22:00' timezone: Europe/Rome - date: '2025-06-12' from_time: '08:00' to_time: '22:30' timezone: Europe/Rome entity_name: Art Museum - openings: - date: '2025-06-11' from_time: '00:00' to_time: '20:00' timezone: Europe/Rome - date: '2025-06-12' from_time: '08:30' to_time: '20:00' timezone: Europe/Rome entity_name: Exhibition in the East Wing opening-times-undefined: summary: Opening times undefined description: Product that has no opening times defined. value: success: true opening_times: '' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /products/{productId}/availability: get: summary: Product availability and pricing tags: - Availability & Pricing API parameters: - $ref: '#/components/parameters/ProductId' - $ref: '#/components/parameters/Currency' - $ref: '#/components/parameters/Language' - name: start_date in: query description: First day for which to return availability. required: false schema: type: string format: date example: '2019-06-05' pattern: YYYY-MM-DD - name: end_date in: query description: 'Last day for which to return availability (by default: 31 days from current date). We capped the endpoint response to a maximum of 31 days per request to manage the response time of the endpoint.' schema: type: string format: date example: '2019-06-05' pattern: YYYY-MM-DD - name: skip_to_first_available_day in: query description: Whenever a range (open or closed) is specified with start_date and/or end_date, validate it against the next available date. If the next available date is in between start_date and end_date, return data from next available date adn end_date. If next available date is beyond end_date, return no available date. If it precedes start_date, nothing changes. required: false schema: type: boolean example: false - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean capped_at: type: - string - 'null' description: The capped date that is used to limit the availability information in the response. For example, *capped_at* 2020-08-19 means the last information in the response is 2020-08-18. We capped the endpoint response to a maximum of 31 days per request to manage the response time of the endpoint. next_available_date: type: - string - 'null' description: The first available date for the product. For example, *next_available_date* 2020-08-19 means that the first date in which there is availability and the product can bo sold is 2020-08-18. sales_enabled: type: boolean description: Indicates whether the product is available for sale or not. dynamic_pricing: type: boolean deprecated: true description: If true, the price depends on the day and timeslot, as well as the day on which the data is requested. Products with dynamic pricing can have different prices for one date for one variant ID, and it allows for active price changes from the supplier. max_tickets_per_order: type: - number - 'null' description: Maximum total number of tickets of any product variant that can be purchased in one order. Returned as `null` if no restriction applies. min_tickets_per_order: type: - number - 'null' description: Minimum total number of tickets of any product variant that can be purchased in one order. Returned as `null` if no restriction applies. dates: type: array description: Availability information for the specific dates. items: type: object properties: date: type: string description: Date of the availability information. Format YYYY-MM-DD. availability: type: number description: Maximum number of tickets that can be purchased together for this date. price: type: - number - 'null' description: Listing price per date. Can be null if there is no availability. currency: type: string description: The currency used in the *price*. timeslots: type: array description: List of available timeslots for a product in the venues timezone using the format HH:MM. items: type: object properties: time: type: string description: Information on time of the availability. Format HH:MM or whole_day for a product without timeslots. availability: type: number description: Maximum number of tickets that can be purchased together for this timeslot. timezone: type: string description: Timeslot timezone, following the venue timezone. In tz format. variants: type: array items: type: object properties: id: type: integer description: Variant identifier. currency: type: string description: The currency used in the *price_component*. max_tickets: type: integer description: Maximum number of tickets available for the specific variant. price_mediation: type: object description: Variant price components for mediation partners. All amounts in currency as defined on the request. properties: sale_ticket_value_incl_vat: type: - number - 'null' description: Basic price of a single ticket from the supplier. If `booking_fee_incl_vat` contains a value > 0, `sale_ticket_value_incl_vat` value should be shown to the customer as Face Value Price. booking_fee_incl_vat: type: - number - 'null' description: Booking fee. If `booking_fee_incl_vat contains a value` > 0, this value should be shown to the customer at checkout. total_retail_price_incl_vat: type: - number - 'null' description: Total retail price including VAT. The amount corresponds with the sum of `sale_ticket_value_incl_vat` and `booking_fee_incl_vat.` Any additional charges to this price are for the risk of the Distributor. distributor_commission_excl_vat: type: - number - 'null' description: Distributor commission excluding VAT. Products with dynamic pricing have the final amount in the invoice. prediscount_price_incl_vat: description: Pre-discount price returned in case a discount applies to the `price` of this product. type: - number - 'null' estimated_partner_rate: description: As an intermediary of Tiqets, you receive a partner commission for your services in accordance with your partner contract. The Estimated Partner Rate is merely displayed to indicate the estimated difference between the ticket retail price (including VAT) and your estimated partner commission (excluding VAT). No rights can be derived from this estimation. The terms of your partner contract shall prevail and take precedence in all cases. type: - number - 'null' price_son: type: object deprecated: true description: In the past, this object returned price components for the now deprecated SON pricing type. This object can be completely ignored and is only returned for compatibility with legacy integrations. All values are always returned as `null`. properties: net_payment_by_distributor: type: - number - 'null' description: Always `null`. venue_legal_mode: type: - string - 'null' description: Always `null`. collection_of_fee_on_behalf_of_venue: type: - number - 'null' description: Always `null`. distributor_discount_excl_vat: type: - number - 'null' description: Always `null`. payable_vat_by_tiqets: type: - number - 'null' description: Always `null`. distributor_booking_fee_excl_vat: type: - number - 'null' description: Always `null`. face_value_price_excl_vat: type: - number - 'null' description: Always `null`. face_value_price_incl_vat: type: - number - 'null' description: Always `null`. tiqets_retail_price_incl_vat: type: - number - 'null' description: Always `null`. distributor_commission_excl_vat: type: - number - 'null' description: Always `null`. pricing_restriction: deprecated: true description: Deprecated field; always `null`. Always follow 'total_retail_price_incl_vat' and do not change the price. type: - string - 'null' variants: type: array items: type: object properties: id: type: integer description: Variant identifier. label: type: string description: Localized label for the variant. valid_with_variant_ids: type: - array - 'null' description: List of variant_ids. If the list is not `null`, this variant can only be booked in combination with at least one of the listed variant_ids. A common use case are infant variants which require an adult variant. items: type: integer description: Variant identifier. description: type: - string - 'null' description: Localized description for the variant with embedded age ranges. requires_visitors_details: type: - array - 'null' description: For products that require visitor's details, this is a list of additional data fields required when placing an order. Please find the detailed requirements of the individual elements in the documentation of our Booking API endpoints. items: type: string enum: - full_name - email - phone - passport_id - passport_ids - date_of_birth - nationality - weight_kg - weight_lb - address - zipcode - pickup_location - dropoff_location - flight_number - dietary_preference description: The fields required to create an order. variant_type: description: Variant type classification information. This field is intended to enable partners to do machine matching/processing of certain properties of a variant. type: string enum: - adult - youth - child - infant - senior - family - regular - reduced maximum_visitors_per_ticket: description: Maximum number of visitors covered by the price of one ticket of this variant. If no group size is configured, the value is 1. Variants priced for a group can return a value greater than 1; refer to the variant label and description for details about the group composition. type: integer languages: description: List of the languages of available tour guides for this variant. The format generally follows ISO 639-1 codes; for languages that do not have a 639-1 code, it is in 639-3. type: - array - 'null' items: type: string description: Language code. language_selection: description: List of the languages of available tour guides for this variant. The format follows ISO 639-3 codes. If this is not `null`, customers need to select a language on the tiqets.com checkout. Please refer to [How to implement language selection](https://developers.tiqets.dev/integration-guides/product-integration/how-to-implement-language-selection) for more details. type: - array - 'null' items: type: string description: Language code. is_addon: description: True if the variant is an addon that can only be sold in combination with a non-addon variant. False if the variant can be sold as stand-alone. type: boolean group_ids: type: array description: 'List of group ID, associated with the variant. NOTE: Multiple IDs can be associated with one variant.' items: type: integer description: Group identifier. cancellation: description: Cancellation information. type: object properties: window: type: - integer - 'null' description: The cancellation window in hours corresponds to the cancellation policy. policy: type: string enum: - before_timeslot - before_date - never description: |- Indicates the cancellation policy of the product. Possible values: - before_date: Cancellation is possible until X hours (returned as `window`) before midnight on the visit date. - before_timeslot: Cancellation is possible until X hours (returned as `window`) before the booked timeslot (if the product makes use of timeslots) or the opening hour of the venue (if the product does not have timeslots). - never: Cancellation is not possible for this product. min_per_order: description: The minimum number of tickets required to create an order. type: - integer - 'null' max_per_order: description: The maximum number of tickets allowed to create an order. type: - integer - 'null' groups: type: array description: Group ID and label description. items: type: object properties: id: type: integer example: 0 name: type: string example: Peak examples: example-whole-day: summary: Availability per day description: Availability for a product that manages availability per day. The timeslots are returned as `whole_day`. value: success: true capped_at: '2023-06-26' sales_enabled: true dynamic_pricing: true dates: - availability: 12 date: '2023-06-24' price: 18.5 currency: EUR timeslots: - availability: 12 time: whole_day timezone: Europe/Amsterdam variants: - currency: EUR id: 14239 max_tickets: 12 price_mediation: booking_fee_incl_vat: 0 distributor_commission_excl_vat: 1.29 sale_ticket_value_incl_vat: 18.5 total_retail_price_incl_vat: 18.5 estimated_partner_rate: 17.21 price_son: booking_fee_incl_vat: null collection_of_fee_on_behalf_of_venue: null distributor_booking_fee_excl_vat: null distributor_commission_excl_vat: null distributor_discount_excl_vat: null face_value_price_excl_vat: null face_value_price_incl_vat: null net_payment_by_distributor: null payable_vat_by_tiqets: null sale_ticket_value_incl_vat: null tiqets_retail_price_incl_vat: null total_retail_price_incl_vat: null venue_legal_mode: null pricing_restriction: null - currency: EUR id: 14244 max_tickets: 12 price_mediation: booking_fee_incl_vat: 0 distributor_commission_excl_vat: 0.39 sale_ticket_value_incl_vat: 5 total_retail_price_incl_vat: 5 estimated_partner_rate: 4.61 price_son: booking_fee_incl_vat: null collection_of_fee_on_behalf_of_venue: null distributor_booking_fee_excl_vat: null distributor_commission_excl_vat: null distributor_discount_excl_vat: null face_value_price_excl_vat: null face_value_price_incl_vat: null net_payment_by_distributor: null payable_vat_by_tiqets: null sale_ticket_value_incl_vat: null tiqets_retail_price_incl_vat: null total_retail_price_incl_vat: null venue_legal_mode: null pricing_restriction: null - currency: EUR id: 14248 max_tickets: 12 price_mediation: booking_fee_incl_vat: 0 distributor_commission_excl_vat: 2.93 sale_ticket_value_incl_vat: 39 total_retail_price_incl_vat: 39 estimated_partner_rate: 36.07 price_son: booking_fee_incl_vat: null collection_of_fee_on_behalf_of_venue: null distributor_booking_fee_excl_vat: null distributor_commission_excl_vat: null distributor_discount_excl_vat: null face_value_price_excl_vat: null face_value_price_incl_vat: null net_payment_by_distributor: null payable_vat_by_tiqets: null sale_ticket_value_incl_vat: null tiqets_retail_price_incl_vat: null total_retail_price_incl_vat: null venue_legal_mode: null pricing_restriction: null - availability: 14 date: '2023-06-25' price: 18.5 currency: EUR timeslots: - availability: 14 time: whole_day timezone: Europe/Amsterdam variants: - currency: EUR id: 14239 max_tickets: 14 price_mediation: booking_fee_incl_vat: 0 distributor_commission_excl_vat: 1.29 sale_ticket_value_incl_vat: 18.5 total_retail_price_incl_vat: 18.5 prediscount_price_incl_vat: 20 estimated_partner_rate: 17.21 price_son: booking_fee_incl_vat: null collection_of_fee_on_behalf_of_venue: null distributor_booking_fee_excl_vat: null distributor_commission_excl_vat: null distributor_discount_excl_vat: null face_value_price_excl_vat: null face_value_price_incl_vat: null net_payment_by_distributor: null payable_vat_by_tiqets: null sale_ticket_value_incl_vat: null tiqets_retail_price_incl_vat: null total_retail_price_incl_vat: null venue_legal_mode: null pricing_restriction: null - currency: EUR id: 14244 max_tickets: 14 price_mediation: booking_fee_incl_vat: 0 distributor_commission_excl_vat: 0.39 sale_ticket_value_incl_vat: 5 total_retail_price_incl_vat: 5 estimated_partner_rate: 4.61 price_son: booking_fee_incl_vat: null collection_of_fee_on_behalf_of_venue: null distributor_booking_fee_excl_vat: null distributor_commission_excl_vat: null distributor_discount_excl_vat: null face_value_price_excl_vat: null face_value_price_incl_vat: null net_payment_by_distributor: null payable_vat_by_tiqets: null sale_ticket_value_incl_vat: null tiqets_retail_price_incl_vat: null total_retail_price_incl_vat: null venue_legal_mode: null pricing_restriction: null - currency: EUR id: 14248 max_tickets: 14 price_mediation: booking_fee_incl_vat: 0 distributor_commission_excl_vat: 2.93 sale_ticket_value_incl_vat: 39 total_retail_price_incl_vat: 39 estimated_partner_rate: 36.07 price_son: booking_fee_incl_vat: null collection_of_fee_on_behalf_of_venue: null distributor_booking_fee_excl_vat: null distributor_commission_excl_vat: null distributor_discount_excl_vat: null face_value_price_excl_vat: null face_value_price_incl_vat: null net_payment_by_distributor: null payable_vat_by_tiqets: null sale_ticket_value_incl_vat: null tiqets_retail_price_incl_vat: null total_retail_price_incl_vat: null venue_legal_mode: null pricing_restriction: null max_tickets_per_order: 14 min_tickets_per_order: null variants: - description: 'Age: 19 - 21. Description' id: 14239 label: Adult languages: [] language_selection: [] requires_visitors_details: [] valid_with_variant_ids: [] is_addon: false variant_type: adult maximum_visitors_per_ticket: 1 min_per_order: null max_per_order: null group_ids: - 1 cancellation: window: 72 policy: before_date - description: 'Age: 3 - 18. Description' id: 14244 label: Child languages: [] language_selection: [] requires_visitors_details: [] valid_with_variant_ids: - 14239 is_addon: false variant_type: child maximum_visitors_per_ticket: 1 min_per_order: null max_per_order: null group_ids: - 1 cancellation: window: 72 policy: before_date - description: 2 Adults and 2 Children id: 14248 label: Family languages: [] language_selection: [] requires_visitors_details: [] valid_with_variant_ids: [] is_addon: false variant_type: family maximum_visitors_per_ticket: 4 min_per_order: null max_per_order: null group_ids: - 1 cancellation: window: 72 policy: before_date groups: - id: 0 name: Peak - id: 1 name: Off Peak example-timeslot: summary: Availability per timeslot description: Availability for a product that manages availability per timeslot. value: success: true capped_at: '2020-06-25' sales_enabled: true dynamic_pricing: true dates: - availability: 10 date: '2020-06-24' price: 20 currency: EUR timeslots: - availability: 6 time: '09:00' variants: - currency: EUR id: 253 max_tickets: 10 price_mediation: booking_fee_incl_vat: 3 distributor_commission_excl_vat: 1.25 sale_ticket_value_incl_vat: 17 total_retail_price_incl_vat: 20 estimated_partner_rate: 18.75 price_son: booking_fee_incl_vat: null collection_of_fee_on_behalf_of_venue: null distributor_booking_fee_excl_vat: null distributor_commission_excl_vat: null distributor_discount_excl_vat: null face_value_price_excl_vat: null face_value_price_incl_vat: null net_payment_by_distributor: null payable_vat_by_tiqets: null sale_ticket_value_incl_vat: null tiqets_retail_price_incl_vat: null total_retail_price_incl_vat: null venue_legal_mode: null pricing_restriction: null - availability: 8 time: '13:30' variants: - currency: EUR id: 253 max_tickets: 10 price_mediation: booking_fee_incl_vat: 3 distributor_commission_excl_vat: 1.25 sale_ticket_value_incl_vat: 17 total_retail_price_incl_vat: 20 estimated_partner_rate: 18.75 price_son: booking_fee_incl_vat: null collection_of_fee_on_behalf_of_venue: null distributor_booking_fee_excl_vat: null distributor_commission_excl_vat: null distributor_discount_excl_vat: null face_value_price_excl_vat: null face_value_price_incl_vat: null net_payment_by_distributor: null payable_vat_by_tiqets: null sale_ticket_value_incl_vat: null tiqets_retail_price_incl_vat: null total_retail_price_incl_vat: null venue_legal_mode: null pricing_restriction: null max_tickets_per_order: 10 min_tickets_per_order: null variants: - description: 'Age: 18+. Description' label: Entrance Ticket id: 253 languages: [] language_selection: [] requires_visitors_details: [] valid_with_variant_ids: [] min_per_order: null max_per_order: null is_addon: false variant_type: adult maximum_visitors_per_ticket: 1 group_ids: - 1 cancellation: window: 72 policy: before_timeslot groups: - id: 1 name: Entrance Ticket '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /products/{productId}/product-variants: get: summary: All active product variants tags: - Availability & Pricing API parameters: - $ref: '#/components/parameters/ProductId' - name: lang in: query description: Language of the variants to retrieve. Defaults to English if undefined. required: false schema: type: string example: en description: Language of the variants to retrieve. - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean variants: type: array description: Active product variants items: type: object properties: description: type: string description: Localized description for the variant. age_range: type: object description: Age range for the variant. properties: age_from: type: - integer - 'null' description: Minimum age requirement for the variant. age_to: type: - integer - 'null' description: Maximum age requirement for the variant. requires_visitors_details: type: - array - 'null' description: |- For products that require visitor's details, this is a list of additional data fields required when placing an order. - full_name: The full name of each visitor as in the first name and last name in Latin characters without special characters or numbers - email: email of each visitor. - phone: phone of each visitor. - nationality: The nationality of each visitor. - passport_id: Passport ID of the (main) visitor. (on order level, not per individual visitor) - passport_ids: Passport ID of each visitor. - date_of_birth: The date of birth of each visitor. Date format YYYY-MM-DD. - weight_kg: The weight of each visitor in kg. This field might be required for weight-sensitive experiences such as helicopter flights. - weight_lb: The weight of each visitor in lb. This field might be required for weight-sensitive experiences such as helicopter flights. - address: The home address of each visitor. Expects a non-empty string. - zipcode: The US Zipcode/Postal code if the visitor lives in the United States. Expects a 5-digit number. (on order level, not per individual visitor) - pickup_location: The holiday address of visitors. The tour provider may contact the visitor to arrange the nearest pickup location. (on order level, not per individual visitor) - dropoff_location: The address where the visitors want to be dropped off after the ordered product/activity. (on order level, not per individual visitor) - flight_number: The number of the flight the visitors arrive with. This allows the supplier to be at the right time and location if a product includes an airport pickup/dropoff. (on order level, not per individual visitor) - dietary_preference: The preference or restrictions for the diet of the visitor. - us_mandatory_zipcode: similar to zipcode, but mandatory. items: type: string enum: - full_name - passport_id - passport_ids - date_of_birth - nationality - address - zipcode - pickup_location - dropoff_location - flight_number - email - phone - dietary_preference description: The fields required to create an order. min_per_order: type: - integer - 'null' description: The minimum number of tickets required to create an order. max_per_order: description: The maximum number of tickets allowed to create an order. type: - integer - 'null' label: type: string description: Localized label for the variant. is_addon: description: True if the variant is an addon that can only be sold in combination with a non-addon variant. False if the variant can be sold as stand-alone. type: - boolean - 'null' variant_type: type: string description: Variant type classification to enable machine matching/processing of certain properties of a variant. enum: - adult - youth - child - infant - senior - family - regular - reduced maximum_visitors_per_ticket: description: Maximum number of visitors covered by the price of one ticket of this variant. If no group size is configured, the value is 1. Variants priced for a group can return a value greater than 1; refer to the variant label and description for details about the group composition. type: integer group_ids: type: - array - 'null' description: 'List of group ID, associated with the variant. NOTE: Multiple IDs can be associated with one variant.' items: type: integer description: Group identifier. languages: description: List of the languages of available tour guides for this variant. The format generally follows ISO 639-1 codes; for languages that do not have a 639-1 code, it is in 639-3. type: array items: type: string description: Language code. language_selection: description: List of the languages of available tour guides for this variant. The format follows ISO 639-3 codes. If this is not `null`, customers need to select a language on the tiqets.com checkout. Please refer to [How to implement language selection](https://developers.tiqets.dev/integration-guides/product-integration/how-to-implement-language-selection) for more details. type: - array - 'null' items: type: string cancellation: description: Cancellation information. type: object properties: window: type: - integer - 'null' description: The cancellation window in hours corresponds to the cancellation policy. policy: type: string enum: - before_timeslot - before_date - never description: |- Indicates the cancellation policy of the product. Possible values: - before_date: Indicates that cancellation must be done (window) hours before 12 AM on the date of the visit. - before_timeslot: Indicates that cancellation must be done (window) hours before the timeslot or venue's opening hour. - never: Indicates that a cancellation is never possible. id: type: integer description: Variant identifier. valid_with_variant_ids: type: array description: List of variant_ids, only with these variants will this variant be valid for orders. items: type: integer description: Variant identifier. groups: type: array description: Group ID and label description. items: type: object properties: id: type: integer description: Unique variant group identifier. name: type: string description: Group label. sales_enabled: type: boolean description: Indicates whether the product is available for sale or not. dynamic_pricing: type: boolean deprecated: true description: If true, the price depends on the day and timeslot, as well as the day on which the data is requested. Products with dynamic pricing can have different prices for one date for one variant ID, and it allows for active price changes from the supplier. max_tickets_per_order: type: - integer - 'null' description: Maximum total number of tickets of any product variant that can be purchased in one order. min_tickets_per_order: type: - number - 'null' description: Minimum total number of tickets of any product variant that can be purchased in one order. examples: example: value: success: true variants: - description: 'Age: 18 - 21.' age_range: age_from: 18 age_to: 21 requires_visitors_details: [] min_per_order: null max_per_order: null label: Adult (17+) is_addon: false variant_type: adult maximum_visitors_per_ticket: 1 group_ids: - 5 languages: [] language_selection: [] cancellation: window: null policy: never id: 21035 valid_with_variant_ids: [] - description: null age_range: age_from: null age_to: null requires_visitors_details: [] min_per_order: null max_per_order: null label: Child (4-16) is_addon: false variant_type: child maximum_visitors_per_ticket: 1 group_ids: - 5 languages: [] language_selection: [] cancellation: window: null policy: never id: 21036 valid_with_variant_ids: [] - description: 'Age: 0 - 40. Description' age_range: age_from: null age_to: 40 requires_visitors_details: [] min_per_order: null max_per_order: null label: Infant (0-3) is_addon: false variant_type: infant maximum_visitors_per_ticket: 1 group_ids: - 5 - 1337 languages: [] language_selection: [] cancellation: window: null policy: never id: 21037 valid_with_variant_ids: - 21035 - 21036 - 21038 - 22101 - 22102 - 22103 - description: 'Age: 18+. With a valid student card.' age_range: age_from: 18 age_to: null requires_visitors_details: [] min_per_order: null max_per_order: null label: University Student is_addon: false variant_type: reduced maximum_visitors_per_ticket: 1 group_ids: - 5 languages: [] language_selection: [] cancellation: window: null policy: never id: 21038 valid_with_variant_ids: [] - description: Description age_range: age_from: null age_to: null requires_visitors_details: [] min_per_order: null max_per_order: null label: Audio Guide is_addon: true variant_type: regular maximum_visitors_per_ticket: 1 group_ids: - 5 languages: [] language_selection: [] cancellation: window: null policy: never id: 21847 valid_with_variant_ids: [] - description: Description age_range: age_from: null age_to: null requires_visitors_details: [] min_per_order: null max_per_order: null label: Adult (17+) is_addon: false variant_type: adult maximum_visitors_per_ticket: 1 group_ids: - 1337 languages: [] language_selection: [] cancellation: window: null policy: never id: 22101 valid_with_variant_ids: [] - description: 'Age: 3 - 18.' age_range: age_from: 3 age_to: 18 requires_visitors_details: [] min_per_order: null max_per_order: null label: Child (4-16) is_addon: false variant_type: child maximum_visitors_per_ticket: 1 group_ids: - 1337 languages: [] language_selection: [] cancellation: window: null policy: never id: 22102 valid_with_variant_ids: [] - description: 'Age: 20+. With a valid student card.' age_range: age_from: 20 age_to: null requires_visitors_details: [] min_per_order: null label: University Student is_addon: false variant_type: reduced maximum_visitors_per_ticket: 1 group_ids: - 1337 languages: [] language_selection: [] cancellation: window: null policy: never id: 22103 valid_with_variant_ids: [] groups: - id: 5 name: Entry Ticket - id: 1337 name: Entry Ticket and Guided Tour sales_enabled: true dynamic_pricing: true max_tickets_per_order: 20 min_tickets_per_order: null '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' operationId: '' /products/calendar: get: summary: Product calendar tags: - Availability & Pricing API parameters: - name: product_ids in: query required: true description: List of comma-separated product IDs for which to request the calendar. At least one product ID needs to be provided; the maximum is 20 product IDs. schema: type: string example: 1006356,1010393,975854 - $ref: '#/components/parameters/Language' - name: start_date in: query required: false schema: type: string format: date description: First day for which to return availability. example: '2025-03-21' - name: end_date in: query required: false schema: type: string format: date description: 'Last day for which to return availability (by default: 31 days from current date). We capped the endpoint response to a maximum of 31 days per request to manage the response time of the endpoint.' example: '2025-03-25' - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean products: type: array items: $ref: '#/components/schemas/Calendar' example: value: success: true products: - product_id: 1005201 title: 'The Mauritshuis Museum: Entry Ticket' next_available_date: '2025-03-22' availability: - date: '2025-03-22' available: true - date: '2025-03-23' available: true - product_id: 984972 title: '1238 Battle of Iceland: Entry Ticket' next_available_date: '2025-03-22' availability: - date: '2025-03-22' available: true - date": '2025-03-23' available: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /orders: post: tags: - Booking API summary: Create order parameters: - $ref: '#/components/parameters/Authorization' - name: lang in: query description: Order language. The language of the generated tickets follow this language. Defaults to English if undefined. required: false schema: type: string example: en description: Language of the variants to retrieve. requestBody: description: The request body must be signed with the Distributors private key. See the API Integration document for details on how to generate the key pair and JWT [**Request Signing**](#section/API-Basics/Request-signing) required: true content: application/json: schema: type: object properties: product_id: type: integer description: ID of the product day: type: string description: Visit date of the product format: date example: '2019-06-01' timeslot: type: - string - 'null' description: Selected timeslot to visit. Required only for products that manage their availability using timeslots variants: type: array description: Variants to include in this order items: type: object properties: variant_id: type: integer description: The ID of the variant count: type: integer description: Number of tickets requested for this variant customer_details: $ref: '#/components/schemas/CustomerDetailsRequest' visitors_details: $ref: '#/components/schemas/VisitorsDetails' passport_id: type: - string - 'null' minLength: 6 maxLength: 20 pattern: ^[a-zA-Z0-9]{6,20}$ description: Passport ID of the (main) visitor. Must contain 6–20 ASCII alphanumeric characters. Only if required for the product as advertised in Availability API. (On order level, not per individual visitor.) zipcode: type: - integer - 'null' description: The 5-digit US zipcode/postal code if the visitor lives in the United States. Only if required for the product as advertised in Availability API. (On order level, not per individual visitor.) pickup_location: type: - string - 'null' description: The holiday address of visitors. The tour provider may contact the visitor to arrange the nearest pickup location. Only if required for the product as advertised in Availability API. (On order level, not per individual visitor.) dropoff_location: type: - string - 'null' description: The address where the visitors want to be dropped off after the ordered product/activity. Only if required for the product as advertised in Availability API. (On order level, not per individual visitor.) flight_number: type: - string - 'null' description: The number of the flight the visitors arrive with. This allows the supplier to be at the right time and location if a product includes an airport pickup/dropoff. Only if required for the product as advertised in Availability API. (On order level, not per individual visitor.) callback_url: type: - string - 'null' description: Optional Callback URL (webhook) for order status change notifications. This URL will be called for all order status changes, including cancellation. external_reference: type: - string - 'null' description: Partner's order reference ID. Maximum 255 characters, needs to be unique required: - product_id - day - variants - customer_details examples: minimum_parameters: summary: Order for a product with minimum requirements description: Creating an order for a product with minimum requirements. Additional checkout fields are not required for this product. value: product_id: 1006356 day: '2025-12-17' variants: - variant_id: 38100 count: 3 customer_details: firstname: Fred lastname: Bloggs phone: '5551234' email: fred.bloggs@example.com dropoff_location: summary: Order for a product with additional checkout fields description: Creating an order for a product with additional checkout fields `flight_number` and `dropoff_location`, both on order level. value: product_id: 975854 day: '2025-10-17' variants: - variant_id: 13102 count: 3 dropoff_location: City Hotel, 4659 Wilson Avenue, Dallas, TX flight_number: TQ221 customer_details: firstname: Fred lastname: Bloggs phone: '5551234' email: fred.bloggs@example.com full_name: summary: Order for a product with additional checkout fields and optional fields description: Creating an order for a product with additional checkout fields `full_name` and `passport_ids`, both on visitor level. Also, the optional fields `callback_url` and `external_reference` are provided. value: product_id: 975244 day: '2025-11-02' timeslot: '10:00' variants: - variant_id: 4911 count: 1 - variant_id: 4910 count: 2 customer_details: firstname: John lastname: Doe email: john+doe@example.com phone: '+31111111111' visitors_details: - variant_id: 4911 visitors_data: - full_name: John Doe passport_ids: CU987765 - variant_id: 4910 visitors_data: - full_name: Jane Doe passport_ids: CU287765 - full_name: Jimmy Doe passport_ids: CU3987765 - full_name: زين مالك passport_ids: AR987654 callback_url: http://partnercallbackurl.com/test?123 external_reference: partnerorderref2025test123 responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean order_reference_id: type: string description: The unique order reference ID created for this order. payment_confirmation_token: type: string description: Unique token that must be used to confirm the order. price_components_eur: $ref: '#/components/schemas/PriceComponentMediationInEUR' price_components: $ref: '#/components/schemas/PriceComponentMediation' expected_ticket_delivery_date: description: The date on which the tickets will be expected to be delivered. Relevant when ticket_delivery != direct_via_tiqets_api type: string format: date nullable: true estimated_commissions: type: array description: Estimated commission for the order. items: type: object properties: currency: type: string description: Currency code (ISO 4217) for the estimated commission amount. variant_id: type: integer description: Variant identifier. value: type: number description: Value of the estimated commission. example: success: true order_reference_id: '11111111' payment_confirmation_token: eyJhbGciOiJIUzI1NiJ9.eyJwYXltZW50X2lkIjo3ODkzMDh9.InZrWGpbEn09_S7jdjgntAtSt4DY_ZZ60rG5C_CkxzA estimated_commissions: - currency: EUR variant_id: 32 value: 1.36 - currency: EUR variant_id: 33 value: 1.06 price_components_eur: sale_ticket_value_incl_vat: 36.5 booking_fee_incl_vat: 2 sale_order_value_incl_vat: 38.5 distributor_commission_excl_vat: 2.42 price_components: sale_ticket_value_incl_vat: 38.2 booking_fee_incl_vat: 2.25 sale_order_value_incl_vat: 40.45 distributor_commission_excl_vat: 2.68 estimated_partner_rate: 37.77 currency: USD expected_ticket_delivery_date: '2026-01-01' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' get: tags: - Booking API summary: List orders parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/Page' - name: start_date in: query description: 'First day for which to return list of orders (default: 30 days before the current date).' required: false schema: type: string format: date example: '2021-01-05' pattern: YYYY-MM-DD - name: end_date in: query description: 'Last day for which to return list of orders. (default: the current date).' schema: type: string format: date example: '2021-02-05' pattern: YYYY-MM-DD responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean pagination: $ref: '#/components/schemas/Pagination' order: type: - array - 'null' items: $ref: '#/components/schemas/Order' examples: example-api-orders: summary: API orders description: List of orders that were created through Booking API. value: success: true orders: - external_reference: ABC-555341 order_reference_id: '7219243315' basket_reference_id: '1124718178' product_id: 975446 order_date: '2025-02-08' order_created_timestamp: '2025-02-08T13:52:41.653342+00:00' visit_date: '2025-02-09' number_of_tickets: 2 sale_order_value: 45 estimated_commission: 7.24 estimated_partner_rate: 37.76 order_type: regular order_status: done currency: EUR sitebrand: my-sitebrand source_tool: affiliate_link campaign_name: test_campaign click_id: test_click_id - external_reference: ABC-555368 order_reference_id: '349454721' basket_reference_id: '2471178653' product_id: 975446 order_date: '2025-02-10' order_created_timestamp: '2025-02-10T16:27:22.514914+00:00' visit_date: '2025-02-16' number_of_tickets: 1 sale_order_value: 22.5 estimated_commission: 3.65 order_type: regular order_status: cancelled currency: EUR sitebrand: my-second-sitebrand source_tool: discovery_widget campaign_name: test_campaign click_id: test_click_id pagination: total: 2 page: 1 page_size: 100 example-affiliate-orders: summary: Non-API orders description: List of orders that were created through our Affiliate tools (affiliate links, widgets). value: success: true orders: - order_reference_id: 2151954338 basket_reference_id: 4713178653 product_id: 975446 order_date: '2025-02-02' order_created_timestamp: '2025-02-02T06:12:06.682547+00:00' visit_date: '2025-02-04' number_of_tickets: 2 sale_order_value: 45 estimated_commission: 7.47 sitebrand: MySitebrand source_tool: affiliate_link campaign_name: mywebsite-landingpage-link2 click_id: abcdefg-xyz order_type: regular order_status: done - external_reference: null order_reference_id: 471334569 basket_reference_id: 2178265306 product_id: 975446 order_date: '2025-02-18' order_created_timestamp: 2025-18-23:52:53.482137+00:00 visit_date: '2025-02-24' number_of_tickets: 4 sale_order_value: 90 estimated_commission: 15.58 sitebrand: MySitebrand source_tool: availability_widget campaign_name: mywebsite-citypage-avwidget click_id: abcdefg-kpx order_type: regular order_status: done pagination: total: 2 page: 1 page_size: 100 example-orders: summary: API and non-API orders description: List of orders that were created via the Booking API or using Affiliate tools. value: success: true orders: - order_reference_id: 2151954338 basket_reference_id: 1186324740 product_id: 975446 order_date: '2025-02-02' order_created_timestamp: '2025-02-02T06:12:06.682547+00:00' visit_date: '2025-02-04' number_of_tickets: 2 sale_order_value: 45 estimated_commission: 7.47 sitebrand: MySitebrand source_tool: affiliate_link campaign_name: mywebsite-landingpage-link2 click_id: abcdefg-wqt order_type: regular order_status: done - external_reference: ABC-555368 order_reference_id: 349454721 basket_reference_id: 3232470062 product_id: 975446 order_date: '2025-02-10' order_created_timestamp: '2025-02-10T16:27:22.514914+00:00' visit_date: '2025-02-16' number_of_tickets: 1 sale_order_value: 22.5 estimated_commission: 3.65 order_type: regular order_status: cancelled - order_reference_id: 7621548195 basket_reference_id: 5646578319 product_id: 975446 order_date: '2025-02-27' order_created_timestamp: '2025-02-27T09:32:06.657118+00:00' visit_date: '2025-03-04' number_of_tickets: 2 sale_order_value: 45 estimated_commission: 7.47 sitebrand: MyNewSitebrand source_tool: discovery_widget order_type: regular order_status: done pagination: total: 3 page: 1 page_size: 100 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /orders/{orderReferenceId}: put: tags: - Booking API parameters: - $ref: '#/components/parameters/OrderReferenceId' - $ref: '#/components/parameters/Authorization' requestBody: description: The request body must be signed with the Distributor's private key. See the Integration Guide for details on how to generate the key pair and JWT [**request signing**](#section/API-Basics/Request-signing). content: application/json: schema: type: object properties: payment_confirmation_token: type: string description: The unique token that must be used to confirm the order example: payment_confirmation_token: eyJhbGciOiJIUzI1NiJ9.eyJwYXltZW50X2lkIjo3ODkzMDh9.InZrWGpbEn09_S7jdjgntAtSt4DY_ZZ60rG5C_CkxzA responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean description: Indicates whether the request was successful (`True`) or not (`False`). order_reference_id: type: number description: The payment confirmation token echoed back from the order creation step. example: success: true order_reference_id: 1111111 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Confirm order get: tags: - Booking API parameters: - name: orderReferenceId in: path description: Unique ID of order. required: true schema: type: string example: '1111111' - name: lang in: query description: Language of the content to retrieve (ISO 639-1). Defaults to English if undefined. required: false schema: type: string example: en - $ref: '#/components/parameters/Authorization' - name: external in: query required: false schema: type: boolean description: Set this parameter to `true` to trace an order using the partner's own order ID (defined as `external_reference` upon order creation) as `orderReferenceId`. example: true responses: '200': description: Successful operation. content: application/json: schema: type: object properties: product_id: type: integer description: ID of the booked product. promoted_product_id: type: - integer - 'null' description: Only applicable for products that aggregate the availability of a group of products. The `promoted_product_id` is the ID that was originally promoted while the actually booked product is different. order_reference_id: type: string description: Order reference ID of the order. basket_reference_id: type: string description: Basket reference ID of the order. day: type: - string - 'null' format: date description: Booked visit date. timeslot: type: - string - 'null' description: Booked timeslot at the given visit date. variants: type: array description: Variants included in this order. items: type: object properties: count: type: integer description: Number of tickets for this variant. variant_id: type: integer description: Variant ID. customer_details: $ref: '#/components/schemas/CustomerDetailsResponse' order_status: type: string description: |- The order status, as one of the following values: * new: Order was created, but not yet confirmed or paid. * pending: Order was confirmed or paid, and the tickets are still being processed. * failed: Order was not paid or the ticket processing failed. * done: Order was completed and PDF tickets have been generated. * cancelled: Order was cancelled after it had been completed. is_currently_cancellable: type: boolean description: Indicates if the order is currently eligible for cancellation. cancellation_deadline: type: - string - 'null' description: The latest timestamp allowed for the order cancellation. Only returned if the value of `is_currently_cancellable` is `true`. Format ISO_8601 YYYY-MM-DDTHH:MM:SS±HH:MM. price_components_eur: $ref: '#/components/schemas/PriceComponentMediationInEUR' price_components: $ref: '#/components/schemas/PriceComponentMediation' external_reference: type: - string - 'null' description: External order ID as provided upon order creation API request. Unique, maximum 255 characters expected_ticket_delivery_date: description: The date on which the tickets will be expected to be delivered. Relevant when ticket_delivery != direct_via_tiqets_api type: string format: date nullable: true examples: example-msp: summary: Order of a Multisource Product description: This is an order of a Multisource Product. The booked product ID is returned as `product_id`, the previously promoted product ID as `promoted_product_id`. value: success: true order_reference_id: '91782315' basket_reference_id: '4756756758' product_id: 918256 promoted_product_id: 123456 day: '2025-06-20' timeslot: '09:00' order_status: done variants: - count: 1 variant_id: 24 customer_details: email: bart@example.com firstname: Bart lastname: Simpson phone: '+1234' is_currently_cancellable: true cancellation_deadline: '2025-06-18T10:00:00+01:00' price_components_eur: sale_ticket_value_incl_vat: 14.5 booking_fee_incl_vat: 0 sale_order_value_incl_vat: 14.5 distributor_commission_excl_vat: 0 price_components: sale_ticket_value_incl_vat: 15.05 booking_fee_incl_vat: 0 sale_order_value_incl_vat: 15.05 distributor_commission_excl_vat: 1 estimated_partner_rate: 14.05 currency: USD expected_ticket_delivery_date: '2026-01-01' example-mediation: summary: Order of a standard Product description: This is an order of a standard Product without Multisource. The product ID remained the same throughout the booking process and is returned as `product_id`. value: success: true order_reference_id: 91782315 basket_reference_id: 7854308931 product_id: 918256 day: '2025-06-20' timeslot: '09:00' order_status: done variants: - count: 1 variant_id: 24 customer_details: email: bart@example.com firstname: Bart lastname: Simpson phone: '+1234' is_currently_cancellable: true cancellation_deadline: '2025-06-18T10:00:00+01:00' price_components_eur: sale_ticket_value_incl_vat: 14.5 booking_fee_incl_vat: 0 sale_order_value_incl_vat: 14.5 distributor_commission_excl_vat: 0 price_components: sale_ticket_value_incl_vat: 15.05 booking_fee_incl_vat: 0 sale_order_value_incl_vat: 15.05 distributor_commission_excl_vat: 0 currency: USD expected_ticket_delivery_date: '2026-01-01' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Get order information delete: tags: - Booking API parameters: - $ref: '#/components/parameters/OrderReferenceId' - $ref: '#/components/parameters/Authorization' requestBody: description: | The request body must be signed with the distributor's private key. See the Integration Guide for details on how to generate the key pair and JWT [**request signing**](#section/API-Basics/Request-signing). Partners are required to send one of the possible cancellation reason in the request body: - COULD_NOT_MAKE_IT - NEED_TO_RESCHEDULE - FOUND_A_BETTER_PRICE_ELSEWHERE - DID_NOT_RECEIVE_TICKETS - OTHER. content: application/json: schema: type: object properties: cancellation_reason: type: string enum: - COULD_NOT_MAKE_IT - NEED_TO_RESCHEDULE - FOUND_A_BETTER_PRICE_ELSEWHERE - DID_NOT_RECEIVE_TICKETS - - OTHER description: Reason for cancellation from the customer. example: cancellation_reason: NEED_TO_RESCHEDULE responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean description: Indicates whether the request was successful (`True`) or not (`False`). example: success: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Cancel Order /orders/{orderReferenceId}/tickets: get: tags: - Booking API parameters: - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/OrderReferenceId' - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean order_reference_id: type: string description: Unique order reference ID. order_status: type: string description: |- The order status, as one of the following values: * new: Order is successfully created in Tiqets but not yet confirmed by the distributor. * pending: Order is confirmed; Tiqets is currently working on the fulfilment. * failed: Order fulfilment failed. * done: Order is fulfilled and the PDF tickets are ready. * cancelled: A previously fulfilled order has been cancelled. enum: - new - pending - failed - done - cancelled how_to_use_info: type: - string - 'null' description: Instructions of how to use the tickets. Also displayed on the voucher. post_purchase_info: type: - string - 'null' description: Post-purchase information. tickets_pdf_url: type: - string - 'null' description: |- URL to PDF document with the tickets. Language on the voucher follows order language as defined at order creation. Value is `null` unless the order_status is `done`. must_know: type: - string - 'null' description: Important information. Also displayed on the voucher. pre_purchase: type: - string - 'null' description: Pre-purchase information. good_to_know: type: - string - 'null' description: Additional information. included: type: - string - 'null' description: Description of what is included in the ticket. excluded: type: - string - 'null' description: Description of what is explicitly not included in the ticket. has_timeslots: type: - boolean - 'null' description: Indicates whether the product has timeslots. has_dynamic_pricing: type: boolean deprecated: true description: Indicates whether the product has dynamic pricing. customer_data_required_on_create_order: type: boolean deprecated: true description: This element can be ignored and is only returned for compatibility with legacy integrations. Always `true`. starting_point_address: type: - string - 'null' description: Address of the starting point. starting_point_latitude: type: - number - 'null' description: Latitude of the starting point. starting_point_longitude: type: - number - 'null' description: Longitude of the starting point. starting_point_city_id: type: - integer - 'null' description: Tiqets city ID of the starting point. example: order_reference_id: '13798247' how_to_use_info: Show the vouchers at the door. post_purchase_info: The venue is closed every Tuesday. order_status: done success: true tickets_pdf_url: http://www.tiqets.com/voucher.pdf must_know: Pets are not allowed. pre_purchase: Children under 6 years old do not need a ticket. good_to_know: Storage lockers are available in the basement for an additional fee. included: Entrance ticket excluded: Usage of storage locker has_timeslots: false has_dynamic_pricing: true customer_data_required_on_create_order: true starting_point_address: 1017 Amsterdam, Netherlands starting_point_latitude: 52.3702 starting_point_longitude: 4.8951 starting_point_city_id: 1017 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Retrieve tickets /subscriptions: post: tags: - Notification Subscriptions API requestBody: description: The request body must be signed with the distributor private key. See the API Integration document for details on how to generate the key pair and JWT [**Request Signing**](#section/API-Basics/Request-signing) required: true content: text/plain: schema: type: object properties: name: type: string description: An optional free-form name for the list. subscription_type: type: string description: Currently only `webhook` subscription type is supported. There may be different subscription type in the future. example: webhook target_endpoint: type: string description: Partner notification URL. Needs to be HTTPS. products: type: array description: List of product ID which will have change notification. items: type: object properties: product_id: type: integer description: Tiqets product ID. required: - subscription_type - target_endpoint - products - product_id examples: example: value: name: Important product list one subscription_type: webhook target_endpoint: https://partner/notification/url products: - product_id: 973888 - product_id: 973666 - product_id: 929249 responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean is_active: type: boolean description: Subscription list status. id: type: number description: Unique ID created for this subscription list. name: type: string description: Name of the list. subscription_type: type: string description: Currently only `webhook` subscription type is supported. There may be different subscription type in the future. target_endpoint: type: string description: Partner notification URL. products: type: array description: List of product ID which will have change notification. items: type: object properties: product_id: type: integer description: Tiqets product ID. target_email: type: string description: Will be supported in the future. Partner email address for the notification. examples: example: value: success: true subscription_type: webhook is_active: true name: Important products target_endpoint: https://partner/notification/url products: - product_id: 973888 - product_id: 973666 - product_id: 973698 target_email: null id: 34 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Create subscription list parameters: - $ref: '#/components/parameters/Authorization' get: tags: - Notification Subscriptions API parameters: - $ref: '#/components/parameters/Authorization' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean subscriptions: type: array items: $ref: '#/components/schemas/Subscription' examples: example: value: success: true subscriptions: - subscription_type: webhook target_email: null target_endpoint: https://partnerURL/webhooks/ID1 name: Important products is_active: true id: 1 products: - product_id: 1006356 - product_id: 1006523 - product_id: 1006524 - product_id: 1006518 - subscription_type: webhook target_email: null target_endpoint: https://partnerURL2/webhooks/IDXXX name: VIP products is_active: true id: 7 products: - product_id: 1006356 - product_id: 1006522 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Retrieve all subscriptions lists /subscriptions/{id}: get: tags: - Notification Subscriptions API parameters: - $ref: '#/components/parameters/Authorization' - name: id in: path description: Unique ID of the subscription list. required: true schema: type: string example: '11' responses: '200': description: Successful operation. content: application/json: schema: allOf: - type: object properties: success: type: boolean - $ref: '#/components/schemas/Subscription' examples: example: value: success: true subscription_type: webhook is_active: true name: Important products target_endpoint: https://partner/notification/url products: - product_id: 973888 - product_id: 973666 - product_id: 973698 target_email: null id: 34 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Retrieve subscription list information put: tags: - Notification Subscriptions API parameters: - $ref: '#/components/parameters/Authorization' - name: id in: path description: Unique ID of the subscription list. required: true schema: type: string example: '11' requestBody: description: The request body must be signed with the distributor private key. See the Integration Guide for details on how to generate the key pair and JWT [**request signing**](#section/API-Basics/Request-signing). content: application/json: schema: type: object properties: name: type: string description: An optional free-form name for the list. subscription_type: type: string description: Currently only `webhook` subscription type is supported. There may be different subscription type in the future. example: webhook target_endpoint: type: string description: Partner notification URL. products: type: array description: List of product ID which will have change notification. items: type: object properties: product_id: type: integer description: Tiqets product ID. required: - subscription_type - target_endpoint - products - product_id examples: example: value: name: Important product list one subscription_type: webhook target_endpoint: https://partner/notification/url products: - product_id: 973888 - product_id: 973666 - product_id: 929249 responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean is_active: type: boolean description: Subscription list status. id: type: number description: Unique ID created for this subscription list. name: type: string description: Name of the list. subscription_type: type: string description: Currently only `webhook` subscription type is supported. There may be different subscription type in the future. target_endpoint: type: string description: Partner notification URL. products: type: array description: List of product ID which will have change notification. items: type: object properties: product_id: type: integer description: Tiqets product ID. target_email: type: string description: Will be supported in the future. Partner email address for the notification. examples: example: value: success: true subscription_type: webhook is_active: true name: Important products target_endpoint: https://partner/notification/url products: - product_id: 973888 - product_id: 973666 - product_id: 973698 target_email: null id: 34 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Overwrite subscription list patch: tags: - Notification Subscriptions API parameters: - $ref: '#/components/parameters/Authorization' - name: id in: path description: Unique ID of the subscription list. required: true schema: type: string example: '11' requestBody: description: The request body must be signed with the distributor private key. See the Integration Guide for details on how to generate the key pair and JWT [**request signing**](#section/API-Basics/Request-signing). content: application/json: schema: type: object properties: name: type: string description: An optional free-form name for the list. subscription_type: type: string description: Currently only `webhook` subscription type is supported. There may be different subscription type in the future. example: webhook target_endpoint: type: string description: Partner notification URL. products: type: array description: List of product ID which will have change notification. items: type: object properties: product_id: type: integer description: Tiqets product ID. required: - subscription_type - target_endpoint - products - product_id examples: example: value: name: Important product list one subscription_type: webhook target_endpoint: https://partner/notification/url products: - product_id: 973888 - product_id: 973666 - product_id: 929249 responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean is_active: type: boolean description: Subscription list status. id: type: number description: Unique ID created for this subscription list. name: type: string description: Name of the list. subscription_type: type: string description: Currently only `webhook` subscription type is supported. There may be different subscription type in the future. target_endpoint: type: string description: Partner notification URL. products: type: array description: List of product ID which will have change notification. items: type: object properties: product_id: type: integer description: Tiqets product ID. target_email: type: string description: Will be supported in the future. Partner email address for the notification. examples: example: value: success: true subscription_type: webhook is_active: true name: Important products target_endpoint: https://partner/notification/url products: - product_id: 973888 - product_id: 973666 - product_id: 973698 target_email: null id: 34 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Append products to list delete: tags: - Notification Subscriptions API parameters: - $ref: '#/components/parameters/Authorization' - name: id in: path description: Unique ID of the subscription list. required: true schema: type: string example: '11' responses: '200': description: Successful operation. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Delete subscription list /reports/orders: get: tags: - Reports APIs parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/Page' - name: start_date in: query description: Start day for which orders were finalised. Defaults to 30 days after end_date required: false schema: type: string format: date example: '2020-03-21' - name: end_date in: query description: Last day for which orders were finalised (inclusive). Defaults to tomorrow. required: false schema: type: string format: date example: '2020-03-25' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean pagination: $ref: '#/components/schemas/Pagination' orders: $ref: '#/components/schemas/OrderReportList' examples: example-orders: summary: Report orders description: Report of your orders value: success: true orders: order_reference_id: '123123123' basket_reference_id: '1231231231324' click_id: click_idrandom number device: desktop campaign_name: entry product_id: 974081 package_id: null order_fulfilled_at: '2025-11-04T13:34:18.824991+00:00' visit_date: '2025-12-31' visit_timeslot: null sitebrand_name: My sitebrand sitebrand_shortname: mys customer_booking_language: it customer_self_cancellation_deadline: '2025-12-30T23:59:00-05:00' customer_charged_currency: EUR customer_country_code: IT customer_ip_country: IT currency: EUR sale_order_value_incl_vat: 92.98 commission_excl_vat: 11.16 variants: - variant_id: 123 quantity: 3 - variant_id: 124 quantity: 1 pagination: total: 5 page: 1 page_size: 100 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Retrieve list of orders for the report /reports/refunds: get: tags: - Reports APIs parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/Page' - name: start_date in: query description: Start day for which refunds were finalised. Defaults to 30 days after end_date required: false schema: type: string format: date example: '2020-03-21' - name: end_date in: query description: Last day for which refunds were finalised (inclusive). Defaults to tomorrow required: false schema: type: string format: date example: '2020-03-25' responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean pagination: $ref: '#/components/schemas/Pagination' orders: $ref: '#/components/schemas/RefundReportList' examples: example-refunds: summary: Report refunds description: Report of your refunds value: success: true refunds: order_reference_id: '123123' basket_reference_id: '123123' device: desktop refunded_at: '2025-11-04T13:46:03.361715+01:00' currency: EUR sale_order_value_incl_vat: -51.58 commission_excl_vat: -10.39 sitebrand_name: My sitebrand Tickets sitebrand_shortname: mys pagination: total: 5 page: 1 page_size: 100 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' summary: Retrieve list of refunds for the report /product-change-notification: get: tags: - Notification Subscriptions API V2 parameters: - $ref: '#/components/parameters/Authorization' responses: '200': description: Subscriptions successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/ProductChangeNotificationSubscriptions' /product-change-notification/{subscription_id}: put: tags: - Notification Subscriptions API V2 parameters: - $ref: '#/components/parameters/Authorization' - name: subscription_id in: path description: Unique ID of your subscription. required: true schema: type: string requestBody: description: Product change notification subscription configuration. required: true content: application/json: schema: $ref: '#/components/schemas/ProductChangeNotificationSubscriptionRequest' responses: '200': description: Subscription successfully updated. content: application/json: schema: $ref: '#/components/schemas/ProductChangeNotificationSubscription' '201': description: Subscription successfully created. content: application/json: schema: $ref: '#/components/schemas/ProductChangeNotificationSubscription' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' get: tags: - Notification Subscriptions API V2 parameters: - $ref: '#/components/parameters/Authorization' - name: subscription_id in: path description: Unique ID of your subscription. required: true schema: type: string responses: '200': description: Subscription successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/ProductChangeNotificationSubscription' delete: tags: - Notification Subscriptions API V2 parameters: - $ref: '#/components/parameters/Authorization' - name: subscription_id in: path description: Unique ID of your subscription. required: true schema: type: string responses: '204': description: Subscription successfully deleted. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /product-change-notification/{subscription_id}/reactivate: post: tags: - Notification Subscriptions API V2 parameters: - $ref: '#/components/parameters/Authorization' - name: subscription_id in: path description: Unique ID of your subscription. required: true schema: type: string requestBody: description: Optional callback URL override when reactivating the subscription. required: false content: application/json: schema: $ref: '#/components/schemas/ReactivateProductChangeSubscriptionRequest' responses: '200': description: Subscription successfully reactivated. content: application/json: schema: $ref: '#/components/schemas/ProductChangeNotificationSubscription' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /temporary-events/{temporaryEventId}: get: summary: Get single temporary event tags: - Content API parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Language' - name: temporaryEventId in: path description: The ID of a temporary event. required: true schema: type: integer example: 42 responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean event: $ref: '#/components/schemas/TemporaryEvent' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' /temporary-events: get: tags: - Content API summary: Search and filter temporary events parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/CityId' - $ref: '#/components/parameters/CountryId' - $ref: '#/components/parameters/ExperienceId' - name: from_date in: query description: | Filter by when temporary events are active. Defaults to today when omitted. If `to_date` is provided, only events that are active at any time between this date and `to_date` are returned. If `to_date` is omitted, only events that are active on or after this date are returned. required: false schema: type: string format: date example: '2026-06-05' pattern: YYYY-MM-DD - name: to_date in: query description: | End of the date range for filtering temporary events. When provided together with `from_date`, only events that are active at any time between `from_date` and this date are returned. When omitted, no upper bound is applied (events from `from_date` onwards). required: false schema: type: string format: date example: '2026-06-30' pattern: YYYY-MM-DD responses: '200': description: Successful operation. content: application/json: schema: type: object properties: success: type: boolean pagination: $ref: '#/components/schemas/Pagination' events: $ref: '#/components/schemas/TemporaryEventsList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' webhooks: ProductChangeNotification: post: requestBody: description: | Product Change Notification webhook definition. required: true content: application/json: schema: $ref: '#/components/schemas/ProductChange' examples: closure_example: summary: Temporary closure with reopening date value: product_id: 313373 change_types: - checkout reason: temporary_closure reopening_date: within_7_days alternative_product_id: 555789 out_of_season_example: summary: Out of season, no alternative value: product_id: 888111 change_types: - checkout reason: out_of_season reopening_date: more_than_month alternative_product_id: null content_change: summary: Product information has changed value: product_id: 982219 change_types: - content minimal_example: summary: Reopening of a closed product value: product_id: 999222 change_types: - checkout reason: null reopening_date: null alternative_product_id: null responses: '200': description: Webhook successfully received and processed by the distributor. default: description: | All non-200 responses (e.g., 4xx, 5xx) indicate failure and will **trigger a retry** using an **exponential backoff mechanism**. ProductChangeNotificationV2: post: requestBody: description: | Product Change Notification V2 webhook definition. required: true content: application/json: schema: $ref: '#/components/schemas/ProductChangeNotificationV2Payload' examples: checkout_disabled: summary: Product temporarily disabled for checkout value: subscription_id: 2b4e1f08-c4ef-4a4f-992e-1f7120332c6b products: - product_id: 974081 changes: - change_type: checkout_disabled reason_code: maintenance expected_reopening: '2025-12-01' recommended_alternative_product_id: 974082 mixed_changes: summary: Multiple change types in a single notification value: subscription_id: 2b4e1f08-c4ef-4a4f-992e-1f7120332c6b products: - product_id: 974081 changes: - change_type: product_details_update field_name: description type: rich_text old_value: Original description new_value: Updated description - product_id: 999222 changes: - change_type: health_check status: degraded orderStatusChange: post: summary: Notification that an order's status has changed. description: | This webhook is triggered whenever an order transitions to a new status. To obtain details of the change, please follow up with a "Get Order Information" call to fetch the new status and order details. requestBody: description: The key identifier of the affected order. required: true content: application/json: schema: type: object properties: order_reference_id: type: string description: The unique identifier of the order whose status has changed. example: 1234567 responses: '200': description: Webhook successfully received and acknowledged by the supplier. default: description: | All non-200 responses (e.g., 4xx, 5xx) indicate failure and will **trigger a retry** using an **exponential backoff mechanism**. components: parameters: Authorization: name: Authorization in: header required: true description: Token . schema: type: string default: Token . Currency: name: currency in: query description: Currency code of the price components (ISO 4217). required: false style: form explode: true schema: type: string default: EUR example: EUR Language: name: lang in: query description: Language of the content to retrieve (ISO 639-1). Defaults to English if undefined. required: false style: form explode: true schema: type: string default: en example: en PageSize: name: page_size in: query description: Number of items per page. Default value is 10, maximum value is 100. required: false schema: type: integer minimum: 1 maximum: 100 default: 10 example: 5 Page: name: page in: query description: Number of the page to retrieve. Used in combination with the `page_size` parameter to define the page size. required: false schema: type: integer minimum: 1 default: 1 example: 1 ProductId: name: productId in: path description: ID of the product to return. required: true schema: type: integer example: 974092 OrderReferenceId: name: orderReferenceId in: path description: Tiqets Order ID. required: true schema: type: string example: 1111111 CityId: name: city_id in: query required: false explode: true description: Filter results by city. Use the [/cities](#tag/Content-API/paths/~1cities/get) endpoint to find the IDs Tiqets has assigned to the various known cities. Repeat the city_id parameter to broaden the search to span multiple cities. schema: type: integer example: 113 CountryId: name: country_id in: query required: false explode: true description: Filter results by country. Use the [/countries](#tag/Content-API/paths/~1countries/get) endpoint to find the IDs Tiqets has assigned to the various known countries. Repeat the country_id parameter to broaden the search to span multiple countries. schema: type: integer example: 50233 ExperienceId: name: experience_id in: query required: false explode: true description: Filter results by experience. Use the [/experiences](#tag/Content-API/paths/~1experiences/get) endpoint to find the IDs Tiqets has assigned to the various known experiences. Repeat the experience_id parameter to broaden the search to span multiple experiences. schema: type: integer example: 145528 schemas: Pagination: type: object properties: total: type: integer description: Total number of items. example: 5 page: type: integer description: Number of the current page. example: 1 page_size: type: integer description: Size of the current page. example: 100 Image: type: object description: Image with URLs in different sizes and optional alt text and credit. properties: small: type: string description: URL of small size image. example: https://aws-tiqets-cdn.imgix.net/images/content/3a740f66b9664886b391b042f442edde.jpg?auto=format%2Ccompress&fit=crop&h=128&ixlib=python-4.0.0&q=70&w=128 medium: type: string description: URL of medium size image. example: https://aws-tiqets-cdn.imgix.net/images/content/3a740f66b9664886b391b042f442edde.jpg?auto=format%2Ccompress&fit=crop&h=250&ixlib=python-4.0.0&q=70&w=250 large: type: string description: URL of large size image. example: https://aws-tiqets-cdn.imgix.net/images/content/3a740f66b9664886b391b042f442edde.jpg?auto=format%2Ccompress&fit=crop&h=500&ixlib=python-4.0.0&q=70&w=500 extra_large: type: string description: URL of extra large size image. example: https://aws-tiqets-cdn.imgix.net/images/content/3a740f66b9664886b391b042f442edde.jpg?auto=format%2Ccompress&fit=crop&h=1284&ixlib=python-4.0.0&q=70&w=1284 alt_text: type: - string - 'null' description: ALT text for the image. Returned if available for the image in the defined request language. Returned as `null` if no ALT text is available. example: People riding an open-top tour bus along a coastal promenade lined with palm trees, with buildings and the sea in the background. credit: type: - string - 'null' description: Image credit information. Credit needs to be shown when an image is shown on your system. Tiqets cannot be held liable for any infringement. example: Photo by Tiqets Images: type: array description: Array of image URLs in different sizes and corresponding image information. items: $ref: '#/components/schemas/Image' ProductGroup: type: object properties: group_id: type: string description: ID of the group. Corresponds with the product ID of the main product of the group. example: '1106932' type: type: string enum: - booking_sources - upsell - comparison description: Type of the group. example: booking_sources products: type: array description: List of all products that belong to this group. items: type: object properties: id: type: string description: Product ID. example: '1086528' title: type: string description: Product title. example: 'Accademia Gallery: Skip The Line Ticket + Guided Tour' currency: type: string description: Currency code (ISO 4217) for the existing amounts. example: EUR from_price: type: - number - 'null' description: From price of the product. example: 46 Product: type: object properties: id: type: string description: Unique Tiqets ID of the product. example: '1006356' language: description: Language of the content information as in the request parameter. The format follows ISO 639-1 codes. type: string example: en languages: type: - array - 'null' description: List of supported languages to retrieve content information for this product. (Thus, the languages returned here do not represent the guide languages of the product.) The format follows ISO 639-1 codes. items: type: string example: - pt - en - de - nl - it - fr - es - ja title: type: string description: Localized title. example: The Museum of Cognitive Dissonance city_name: description: Localized name of the product city. type: string example: Milan city_id: description: Tiqets ID of the product city. type: string example: '105851' country_name: description: Localized name of the product country. type: string example: Italy country_id: description: Tiqets ID of the product country. type: string example: '50109' tag_ids: description: List of tag IDs. See tags. type: array items: type: string example: '327' images: $ref: '#/components/schemas/Images' geolocation: description: Dictionary with `lat`, `lng` coordinates of the product. type: - object - 'null' properties: lat: type: number description: The latitude of the geographic location. example: 44.5 lng: type: number description: The longitude of the geographic location. example: 7.58 distance: description: Distance in kilometers from the given `lat`, `lng`; displayed when filtering by coordinates. type: - integer - 'null' example: 3 venue: description: The experience object. (Experiences were called venue in the past, hence the object name 'venue'.) Experiences can be searched and retrieved using the dedicated Experiences endpoint. type: - object - 'null' properties: address: description: Street address of the venue (can be accurate or an estimate). type: - string - 'null' example: 800, Town and country boulevard id: description: Unique Tiqets ID of the experience. type: string name: description: Name of the experience. type: string example: Moco Museum Amsterdam postal_code: description: The zip code of the experience. type: - string - 'null' example: '77024' ratings: description: Ratings object. type: - object - 'null' properties: average: description: Average number of ratings/reviews (1-5 star rating). type: - number - 'null' example: 4.5 total: description: Total number of ratings/reviews. type: integer example: 1081 price: description: Retail price on Tiqets.com in the currency as returned by `currency`. type: - number - 'null' example: 9.5 currency: description: Currency code (ISO 4217) of the price. Follows the currency as defined in the API request. Defaults to EUR if no currency is provided as a request parameter. type: - string - 'null' example: EUR price_in_supplier_currency: description: Retail price on Tiqets.com following the supplier currency as returned by `supplier_currency`. type: - number - 'null' example: 9.5 supplier_currency: description: Currency code (ISO 4217) of the price in supplier currency. type: - string - 'null' example: EUR product_slug: description: Slug of a product. type: - string - 'null' example: tickets-moco-museum-amsterdam-p974431 supports_cancellation_insurance_in_affiliate_checkout: description: Indicates whether the product can be bought with cancellation insurance in affiliate checkout. type: - boolean - 'null' example: true marketing_restrictions: description: A list of marketing channels that you are not allowed to use with this product. Currently either `things_to_do` or `null`, other channels might be added at any time. type: - array - 'null' deprecated: true items: type: string marketing_restrictions_detailed: description: A list of marketing channels and corresponding restrictions that apply for this product. New channels might be added at any time. type: - array - 'null' items: type: object properties: type: type: string enum: - AD_CONTENT - KEYWORD - TARGETING - THINGS_TO_DO_ADS - THINGS_TO_DO_BOOKING_MODULE description: The type of marketing activity that is restricted. scope: type: string enum: - COUNTRY - CITY - REGIONS - CITY_COUNTRY_GLOBAL - OTHER - ALL description: The geographic scope of the restriction. languages: type: array items: type: string example: en-US description: List of IETF language codes this restriction applies to, or `ALL` if restriction applies for all languages. parameters: type: array items: type: string example: Rembrandthuis description: Additional parameters for the restriction. scope_geolocation: type: - string - 'null' description: Optional geolocation identifier for the scope. example: The Netherlands prediscount_price: description: Pre-discount price returned in case a discount applies to the `price` of this product. type: - number - 'null' example: 10 discount_percentage: type: - number - 'null' description: Percentage of the price discount in case there is a discount applied. Rounded to full per cent. example: 5 display_price: deprecated: true type: - number - 'null' description: Deprecated. Please use `price` instead. example: null display_booking_fee: type: - number - 'null' description: Booking fee. example: 0 cancellation: description: Cancellation information. type: - object - 'null' properties: window: type: - integer - 'null' description: The cancellation window in hours corresponds to the cancellation policy. example: 48 policy: type: string enum: - before_timeslot - before_date - never description: |- Indicates the cancellation policy of the product. Possible values: - before_date: Cancellation is possible until X hours (returned as `window`) before midnight on the visit date. - before_timeslot: Cancellation is possible until X hours (returned as `window`) before the booked timeslot (if the product makes use of timeslots) or the opening hour of the venue (if the product does not have timeslots). - never: Cancellation is not possible for this product. example: before_timeslot product_url: description: |- URL to the product on the Tiqets.com website. The field `product_url` points to the consumer Tiqets.com website. An affiliate tracking code is added to the URL to measure usage and track what orders are done by what partner (`?partner=foobar`). The URL does not contain or follow any currency parameter. The currency shown is determined by the configuration of the browser accessing the URL. type: string example: https://www.tiqets.com/en/centallo-attractions-c105851/tickets-for-distributor-test-a-p1006356?partner=testpartner product_checkout_url: description: |- URL to product checkout on the Tiqets.com website. The field `product_checkout_url` points to the consumer Tiqets.com website. An affiliate tracking code is added to the URL to measure usage and track what orders are done by which partner (`?partner=foobar`). The URL does not contain or follow any currency parameter. The currency shown is determined by the configuration of the browser accessing the URL. type: string example: https://www.tiqets.com/en/centallo-attractions-c105851/tickets-for-distributor-test-a-p1006356/goto_checkout?partner=testpartner tagline: description: Localized tagline. type: - string - 'null' example: Unleash your inner troglodyte on the uncomfortable reality of modern life! promo_label: description: Promotional label. type: - string - 'null' example: bestseller sale_status: description: Indicates whether the product is available for sale (`available`) or not (`unavailable`). type: - string - 'null' enum: - unavailable - available example: available sale_status_reason: type: - string - 'null' enum: - The product is temporarily not available due to technical reasons - The venue of this product is closed - The product is out of season - The product is temporarily not available description: If sale_status is 'unavailable' this field indicates the reason why. example: The product is out of season sale_status_expected_reopen: type: - string - 'null' format: date description: When a product is temporarily unavailable this field will be present with the expected reopen date. summary: description: Localized summary description of the product. type: - string - 'null' example: Leon Festinger\'s theory presented in the Main Hall is widely regarded as some of the finest pieces of psychology ever created. It alone would be worth the price of admission, but the Museum of Cognitive Dissonance is full of other works amassed by its curators over decades – with drawings, video clips, scientific papers, and more. These skip-the-line tickets let you head straight for the entrance. No waiting, just wall-to-wall cognitive dissonance. whats_included: description: Localized list of what is included in the tickets. type: - string - 'null' example: Skip-the-line entrance to the Museum of Cognitive Dissonance. whats_excluded: description: Localized list of what is explicitly not included in the tickets. type: - string - 'null' example: Entrance to temporary exhibitions on the 6th floor. Tickets can be bought at the venue. best_time_to_visit: deprecated: true type: - array - 'null' description: Replaced with tags. items: type: string example: daytime example: null live_guide_languages: description: List of the languages of available live guides for this product. The format generally follows ISO 639-1 codes; for languages that do not have a 639-1 code, it is in 639-3. type: - array - 'null' items: type: string example: - en - it - fr - es - nl - ru audio_guide_languages: description: List of the languages of available audio guides for this product. The format generally follows ISO 639-1 codes; for languages that do not have a 639-1 code, it is in 639-3. type: - array - 'null' items: type: string example: - en - de - it - fr - es - zh - ja language_selection: description: List of the languages of available tour guides for this product. The format follows ISO 639-3 codes. If this is not `null`, customers need to select a language on the tiqets.com checkout. Please refer to [How to implement language selection](https://developers.tiqets.dev/integration-guides/product-integration/how-to-implement-language-selection) for more details. type: - array - 'null' items: type: string example: - eng - ita - fra - spa - nld - rus starting_time: description: Product activity starting time if the product includes a tour. Format HH:MM:SS. type: - string - 'null' example: '12:00:00' timezone: type: - string - 'null' description: Product timezone, following the venue timezone. In tz format. example: Europe/Madrid duration: description: Product activity estimated duration time. Format HH:MM:SS. type: - string - 'null' example: '01:00:00' starting_point: description: | Starting point details of the tour, experience or venue. All products have a starting point, regardless of their type. For venues, the starting point simply repeats the venue's address and coordinates. type: - object - 'null' properties: lat: type: - number - 'null' description: The latitude of a geographic location. example: 44.5 lng: type: - number - 'null' description: The longitude of a geographic location. example: 7.58 address: type: - string - 'null' description: The street address of the venue (can be accurate or an estimate). example: 800, Town and country boulevard city_id: type: number description: Tiqets ID of the city. example: 105851 label: type: - string - 'null' description: The name of the location. example: Anne Frank Huis wheelchair_access: description: Indicates the venue's wheelchair accessibility. type: - boolean - 'null' example: true skip_line: deprecated: true description: Indicates whether the product includes a skip the line feature. type: - boolean - 'null' example: true smartphone_ticket: description: Indicates whether the venue supports tickets via smartphone without any printing. type: - boolean - 'null' example: true advance_arrival_time: description: Recommended time before the start of the activity that the customer should arrive by. Typically used for security checks (cruises), getting seated (theatre), or checking if everyone is there (tours). Format HH:MM:SS. type: - string - 'null' example: '0:10:00' last_admission_window: description: Last ticket admission time before the venue closing time. Format HH:MM:SS. type: - string - 'null' example: '01:00:00' description: description: Full product description. Only for partners with special contracts. type: - string - 'null' example: The Museum of Cognitive Dissonance underwent a ten-year renovation between 2007 and 2017. It's come out looking great – airy, bright and inviting. Plus, it's filled with more scientific papers and art objects than you can possibly absorb in an afternoon. Still, it's fun to give it a try. The highlight is Leon Festinger\'s theory, one of the museum's most famous pieces of writing. Another spectacular – though underrated – section of the museum is the collection of gifs and memes presented in a multimedia installation on floor 4 and 5. The Museum of Cognitive Dissonance also offers an excellent multimedia tour app that can be downloaded straight to your smartphone. Check it out on the App Store or Google Play! highlights: deprecated: true description: Localized highlight description of the product. Only for partners with special contracts. type: - string - 'null' example: Get up close to 8,000 objects across 80 galleries, including renowned Cognitive Dissonance masterpieces like Leon Festinger\'s theory. One of the most visited museums in the world, the Museum of Cognitive Dissonance can have lengthy ticket lines – luckily our tickets get you in via the Fast Lane! It's not just science – the museum also has drawings, an multimedia exhibition of memes, and one of the finest libraries you'll ever see! safety_measures: deprecated: true description: In the past, this object returned safety measures of the venue related to the COVID-19 period. These measures have been deprecated as they are not applicable anymore. This object can be completely ignored and is only returned for compatibility with legacy integrations. type: - object - 'null' example: null properties: cash_accepted: description: Always `null`. type: - boolean - 'null' example: false face_mask: description: Always `null`. type: - string - 'null' example: false gloves: description: Always `null`. type: - string - 'null' example: false has_hand_sanitizer_available: description: Always `false`. type: - boolean - 'null' example: false has_intensified_cleaning: description: Always `false`. type: - boolean - 'null' example: false has_reduced_capacity: description: Always `false`. type: - boolean - 'null' example: false has_social_distancing: description: Always `false`. type: - boolean - 'null' example: false has_temperature_checks: description: Always `false`. type: - boolean - 'null' example: false limited_duration: description: Always `null`. type: - string - 'null' example: null online_ticketing_only: description: Always `false`. type: - boolean - 'null' example: false reduced_capacity: description: Always `null`. type: - integer - 'null' example: false waiting_time: description: Always `null`. type: - string - 'null' example: false exhibitions: description: Localized exhibition information scheduled at the venue. type: - array - 'null' items: type: object properties: from_date: type: - string - 'null' description: Exhibition start date. Format YYYY-MM-DD. example: '2022-11-03' to_date: type: - string - 'null' description: Exhibition end date. Format YYYY-MM-DD. example: '2021-08-03' title: type: string description: Exhibition title. example: Influencing Consumer Behaviour id: type: number description: Tiqets ID of the exhibition. example: 2589 description: type: - string - 'null' description: Localized exhibition description. All partners receive a short exhibition description. Partners with special contracts receive the full exhibition description. example: How is cognitive dissonance used to influence consumers? Find out in this exhibition. Only today with a 20% discount on the admission price! url: description: |- URL to the exhibition page on the Tiqets.com website. The field `url` points to the consumer Tiqets.com website. An affiliate tracking code is added to the URL to measure usage and track what orders are done by which partner (`?partner=foobar`). The URL does not contain or follow any currency parameter. The currency shown is determined by the configuration of the browser accessing the URL. type: - string - 'null' example: https://www.tiqets.com/en/city-centre-tickets-l35818/influencing-customer-behaviour-e2589?partner=testpartner instant_ticket_delivery: description: Indicates whether the tickets will be delivered automatically in less than 10 minutes. If `false`, the fulfilment can take longer than an hour. type: - boolean - 'null' example: true is_package: description: Indicates whether the product is a package. Packages consist of two or more stand-alone products. If the product is a package, the IDs of the included products are returned by `package_products`. type: boolean example: false in_packages: description: List of packages that contain this product. type: - array - 'null' items: type: number example: 1013153 package_products: description: List of products included in the package. type: - array - 'null' items: type: number example: null supplier: description: Information about the supplier of the product. type: - object - 'null' properties: name: type: string description: Supplier name. example: Tiqets International B.V. address: type: - string - 'null' description: Supplier street address. example: James Wattstraat 77-P city: type: - string - 'null' description: Supplier city. example: Amsterdam postalcode: type: - string - 'null' description: Supplier postal code. example: 1097 DL countrycode: type: - string - 'null' description: Supplier country code (ISO 3166-2). example: NL ticket_delivery: description: How the tickets will be delivered. type: string enum: - direct_via_tiqets_api - delayed_via_tiqets_api - delayed_via_supplier_email days_before_visit_delivery: type: integer description: How many days before the visit date the delivery of the tickets will happen. Relevant when ticket_delivery != direct_via_tiqets_api hours_after_booking_delivery: type: integer description: How many hours after the booking the delivery of the tickets will happen. Relevant when ticket_delivery != direct_via_tiqets_api product_groups: description: List of product groups this product is part of. type: - array - 'null' items: $ref: '#/components/schemas/ProductGroup' ProductList: type: array items: $ref: '#/components/schemas/Product' traveler_type: type: string enum: - alone - friends - partner - family - colleagues nullable: true ProductReview: type: object required: - id - author - traveler_type - rating - rating_per_category - body - language - date - source properties: id: type: integer description: The ID of the review. example: 50104 nullabe: false author: type: string description: The reviewer name. example: Jane Doe nullable: true allOf: $ref: '#/components/schemas/traveler_type' rating: type: number format: float description: A number between 1-5 example: 5 rating_per_category: type: object nullable: true properties: value_for_money: type: integer example: 4 nullable: true info_onsite: type: integer example: 5 nullable: true body: type: string description: the review text left by the customer example: I had a lovely time with my friends here. I highly recommend a visit! nullable: true language: type: string description: Language code of the language in which the review is written. example: en nullable: true date: type: string description: The date on which the review was left format: date example: '2025-01-01' source: type: string description: Source of the review. enum: - Tiqets example: Tiqets RatingBreakdown: type: object properties: count: type: integer description: Number of reviews with that rating percentage: type: number format: float description: Percentage of total reviews with that rating (0–100) minimum: 0 maximum: 100 required: - count - percentage RatingsDistribution: type: object description: Breakdown of ratings (1–5) with counts and percentages properties: '1': $ref: '#/components/schemas/RatingBreakdown' '2': $ref: '#/components/schemas/RatingBreakdown' '3': $ref: '#/components/schemas/RatingBreakdown' '4': $ref: '#/components/schemas/RatingBreakdown' '5': $ref: '#/components/schemas/RatingBreakdown' ProductReviewSummary: type: object required: - product_id - average_rating - rating_count - rating_distribution - average_rating_per_category - average_rating_per_traveler_type - reviews_summary - supplier_average_rating properties: product_id: type: integer description: Product identifier example: 12345 average_rating: type: number format: float description: Average rating (1–5) nullable: true minimum: 1 maximum: 5 example: 4.3 rating_count: type: integer description: Total number of ratings example: 128 rating_distribution: $ref: '#/components/schemas/RatingsDistribution' average_rating_per_category: type: object description: 'Average ratings per category. Current categories are: value_for_money, info_onsite' nullable: true additionalProperties: type: number format: float minimum: 1 maximum: 5 example: value_for_money: 4.8 info_onsite: 3.5 average_rating_per_traveler_type: type: object description: 'Average ratings per traveler type. Current traveler types are: alone, friends, partner, family, colleagues' nullable: true additionalProperties: type: number format: float minimum: 1 maximum: 5 example: alone: 5 friends: 5 partner: 5 family: 4.6 colleagues: 4.8 reviews_summary: type: string description: AI reviews summary nullable: true supplier_average_rating: type: number format: float description: Average rating (1–5) for the supplier of the product nullable: true minimum: 1 maximum: 5 example: 4.5 Price: type: object required: - amount - currency properties: amount: type: number format: decimal nullable: false example: 20 currency: type: string pattern: ^[A-Z]{3}$ nullable: false example: EUR RecommendationResult: type: object required: - product_id - title - image_url - from_price properties: product_id: type: integer nullable: false example: 12345 title: type: string nullable: false example: Louvre - Guided Tour image_url: type: string nullable: false example: https://cdn.tiqets.com/path/to/img.jpg from_price: nullable: false $ref: '#/components/schemas/Price' ProductAlternativeResponse: type: object required: - recommendations properties: recommendations: type: array nullable: false items: $ref: '#/components/schemas/RecommendationResult' RecommendationFilters: type: object properties: exclude_product_ids: type: array items: type: integer nullable: true description: IDs that were explicitly excluded from the search. example: - 1 - 2 product_tag_ids: type: array items: type: integer nullable: true description: Tag IDs used to filter the search. example: - 1 - 2 max_per_experience: type: integer default: 1 description: The limit applied per experience type. example: 1 ProductCrossSellOptionsResponse: type: object required: - filters - recommendations properties: filters: $ref: '#/components/schemas/RecommendationFilters' recommendations: type: array items: $ref: '#/components/schemas/RecommendationResult' Experience: type: object properties: id: type: integer description: Unique Tiqets ID of the experience. example: 211947 type: type: string description: 'Type of the experience. Tiqets currently categorises each experience into one of these four types: activity (e.g. a guided tour), service (e.g. public transport), venue (e.g. a museum), or poi (point of interest).' enum: - activity - service - venue - poi example: activity language: description: Language of the content information as in the request parameter. The format follows ISO 639-1 codes. type: string example: en title: type: string description: Localized title. example: Barcelona Hop-on Hop-off Tours images: $ref: '#/components/schemas/Images' address: description: Address of the experience. type: object properties: street: description: Street and number of the experience. type: - string - 'null' example: null postal_code: description: Postal code of the experience. type: - string - 'null' example: null city_id: description: Tiqets ID of the experience city. type: integer example: 66342 city_name: description: Localized name of the experience city. type: string example: Barcelona country_id: description: Tiqets ID of the experience country. type: integer example: 50067 country_name: description: Localized name of the experience country. type: string example: Spain lat: type: - number - 'null' description: The latitude of the experience. example: 41.387397 lng: type: - number - 'null' description: The longitude of the experience. example: 2.168568 google_place_id: description: Google Place ID of the experience. type: - string - 'null' example: null tag_ids: description: List of tag IDs. See tags. type: array items: type: integer example: 1041 product_ids: description: List of product IDs that belong to the experience. type: array items: type: integer example: - 974325 - 1029217 - 1032090 - 1098213 - 1114753 - 1116576 experience_url: description: |- URL to the experience on the Tiqets.com website. The field `experience_url` points to the consumer Tiqets.com website. An affiliate tracking code is added to the URL to measure usage and track what orders are done by what partner (`?partner=foobar`). The URL does not contain or follow any currency parameter. The currency shown is determined by the configuration of the browser accessing the URL. type: string example: https://www.tiqets.com/en/barcelona-hop-on-hop-off-tours-tickets-l211947/ ratings: description: Ratings object. type: object properties: average: description: Average number of ratings/reviews (1-5 star rating). type: number example: 4.3 total: description: Total number of ratings/reviews. type: integer example: 15381 currency: type: - string - 'null' description: Currency code (ISO 4217) of the price. Defaults to EUR if no currency is provided as request parameter. example: EUR from_price: type: - number - 'null' description: From price of the experience. example: 22 tagline: type: string description: Localized tagline. example: Explore all the highlights of Barcelona at your own pace description: type: - string - 'null' description: Experience description. example: |- Ditch the walking tours and set itineraries and explore Barcelona your way with these city bus tour selections. Get to know Barcelona the easy way with a convenient hop-on hop-off bus tour around the city. See Barcelona's best sights at your own pace with guided narration in multiple languages onboard. Speed over to Sagrada Familia, cruise to Casa Mila, and check out Plaça de Catalunya (and so much more) all on the same day with a hop-on hop-off option. Looking to beat the heat (and the crowds)? Opt for a night bus tour around Barcelona to see the city in a different light. Or, pick your own route with a public transport card (and save your soles). ExperienceList: type: array items: $ref: '#/components/schemas/Experience' Tag: type: object properties: id: type: string description: The ID of the tag. example: 1039 name: type: string description: The name of the tag. example: Outdoor Activities type_name: type: string description: The name of the tag-type. example: Adventure type_id: type: string description: The ID of the tag-type. example: 239 type_group_name: type: string description: The name of the group of tags the tag is included in. example: Service categories City: type: object properties: id: type: string description: The ID of the city. example: 271766 name: type: string description: The name of the city. example: Hvammsvík country_id: type: string description: The ID of the country the city is in. example: 50108 country_name: type: string description: The name of the country the city is in. example: Iceland Country: type: object properties: id: type: string description: The ID of the country. example: 50104 name: type: string description: The name of the country. example: India OpeningTimes: type: - object - 'null' properties: entity_name: type: string description: Name of the entity that the opening times information applies for. openings: type: array description: Opening times information for the given entity. items: type: object properties: date: type: string format: date description: Date of the opening times information. Format YYYY-MM-DD. from_time: type: string description: Time when the entity opens. Format HH:MM. to_time: type: string description: Time when the entity closes. Format HH:MM. timezone: type: string description: Timeslot timezone, following the venue timezone. In tz format. Calendar: type: object properties: product_id: type: integer description: ID of the product. title: type: string description: Product title. capped_at: type: string format: date nullable: true description: The capped date that is used to limit the availability information in the response. For example, *capped_at* 2020-08-19 means the last information in the response is 2020-08-18. We capped the endpoint response to a maximum of 31 days per request to manage the response time of the endpoint. Format YYYY-MM-DD. next_available_date: type: string format: date nullable: true description: First available date for the product. Format YYYY-MM-DD. availability: type: object description: Availability information for the product. properties: date: type: string format: date description: Date of the availability information. Format YYYY-MM-DD. available: type: boolean description: Indication of the product is available at the given date. `true` means that there is availability for the date, `false` means that the date is fully unavailable. Order: type: object properties: external_reference: type: - string - 'null' description: Partner's order reference ID as provided upon order creation through Booking API. Unique, maximum 255 characters. Not applicable for non-Booking API orders. order_reference_id: type: string description: Order reference ID of the order. basket_reference_id: type: string description: Basket reference ID of the order. product_id: type: integer description: ID of the product. order_date: type: string format: date description: Date when the order was created. Always follows 'Europe/Amsterdam' timezone. It is recommended to prefer `order_created_timestamp` for the exact timestamp of the order creation. order_created_timestamp: type: string format: date-time description: Date and time when the order was created formatted according to ISO-8601 standard. Always follows UTC timezone. visit_date: type: - string - 'null' format: date description: Visit date selected by the guest during or after the order process. Can be null if the visit date has not been selected yet. number_of_tickets: type: integer description: Total number of tickets in the order. sale_order_value: type: number description: Sale order value (excluding VAT) which is the sum of all the tickets value in the order. estimated_commission: type: - number - 'null' description: Estimated total distributor commission of the order (excluding VAT). estimated_partner_rate: type: - number - 'null' description: As an intermediary of Tiqets, you receive a partner commission for your services in accordance with your partner contract. The Estimated Partner Rate is merely displayed to indicate the estimated difference between the ticket retail price (including VAT) and your estimated partner commission (excluding VAT). No rights can be derived from this estimation. The terms of your partner contract shall prevail and take precedence in all cases. currency: type: string description: Currency code (ISO 4217) for the existing amounts. The returned currency follows the invoice currency. sitebrand: type: - string - 'null' description: Name of partner's co-branded version of Tiqets.com. source_tool: type: - string - 'null' description: Affiliate tool used by user to create the order. This entire field and value will be omitted if the order was created through the Booking API. enum: - affiliate_link - discovery_widget - availability_widget - booking_widget campaign_name: type: - string - 'null' description: Partner's campaign name. Only applicable for non-Booking API orders. click_id: type: - string - 'null' description: Partner's click ID. Only applicable for non-Booking API orders. order_type: type: string description: |- The order type: * Regular: Order consisting of a single product. * Bundle: Order consisting of different products combined together with a discount. * Combi deal: Order of a product with additional products selected to be bought together with a discount during the order proces. * Package: Order of a predefined package which consists of different products with a discount on the total price. enum: - REGULAR - BUNDLE - COMBI_DEAL - PACKAGE order_status: type: string enum: - new - pending - failed - done - cancelled description: |- The order status, as one of the following values: * new: Order was created, but not yet confirmed or paid. * pending: Order was confirmed or paid, and the tickets are still being processed. * failed: Order was not paid or the ticket processing failed. * done: Order was completed and PDF tickets have been generated. * cancelled: Order was cancelled after it had been completed. CustomerDetailsRequest: type: object description: 'Customer details required to create an order. Note: The Tiqets support team might contact the provided email address and/or phone number in case of sudden changes.' properties: firstname: type: string description: Customer's first name. Unicode characters, including accents and non-Latin scripts, are supported. lastname: type: string description: Customer's last name. Unicode characters, including accents and non-Latin scripts, are supported. email: type: string format: email description: Customer's email address. Must be a valid email address. phone: type: string description: Customer's phone number. required: - firstname - lastname - email - phone VisitorsDetails: type: array description: |- Additional checkout information of every visitor. **Note**: these fields are only required for a few products which have `requires_visitors_details` on the variant endpoint. In case it is required, the details of the visitors must be provided for every visitor/ticket purchased within the order. items: type: object properties: variant_id: type: integer description: The ID of the variant. visitors_data: type: array description: |- Additional information required of each visitor associated with the `variant_id`. One value per key. *The full_name example shows the correct format for a request to create an order for 2 variants and 3 guests in total.* items: type: object properties: full_name: type: - string - 'null' minLength: 1 maxLength: 100 pattern: ^\S+\s\S.*$ description: Visitor's full name. Must not be blank, must contain at least two name parts separated by whitespace, and must be no more than 100 characters. Unicode characters, including accents and non-Latin scripts, are supported. passport_ids: type: - string - 'null' minLength: 1 pattern: .*\S.* description: Visitor's passport ID. Must not be blank when required for the product. date_of_birth: type: - string - 'null' format: date description: Visitor's date of birth. Date format YYYY-MM-DD. nationality: type: - string - 'null' description: Visitor's nationality in Latin characters. weight_kg: type: - string - 'null' description: Visitor's weight in kg. Expects an integer value as a string. weight_lb: type: - string - 'null' description: Visitor's weight in lb. Expects an integer value as a string. address: type: - string - 'null' description: Visitor's home address. email: type: - string - 'null' format: email minLength: 5 maxLength: 255 pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$ description: Visitor's email address. Must use a valid user@domain.tld format. phone: type: - string - 'null' minLength: 7 maxLength: 20 pattern: ^[+0-9\s\-().]{7,20}$ description: Visitor's phone number. May contain digits, plus signs, whitespace, hyphens, parentheses, and periods. dietary_preference: type: - string - 'null' description: Visitor's dietary preferences or restrictions PriceComponentMediationInEUR: type: - object - 'null' description: Order pricing details in EUR. properties: sale_ticket_value_incl_vat: type: number description: Sale tickets value, including VAT. Sum of `sale_ticket_value_incl_vat` of all the tickets in the order. booking_fee_incl_vat: type: number description: Booking fee, including VAT. sale_order_value__incl_vat: type: number description: Sale order value, including VAT. Sum of `sale_ticket_value_incl_vat` and `booking_fee_incl_vat` of all the tickets in the order. distributor_commission_excl_vat: type: number description: Total distributor commission of the order, excluding VAT. PriceComponentMediation: type: - object - 'null' description: Order pricing details in the distributor's invoicing currency. properties: sale_ticket_value_incl_vat: type: number description: Sale tickets value, including VAT. Sum of `sale_ticket_value_incl_vat` of all the tickets in the order. booking_fee_incl_vat: type: number description: Booking fee, including VAT. sale_order_value__incl_vat: type: number description: Sale order value, including VAT. Sum of `sale_ticket_value_incl_vat` and `booking_fee_incl_vat` of all the tickets in the order. distributor_commission_excl_vat: type: number description: Total distributor commission of the order, excluding VAT. currency: type: string description: Currency code (ISO 4217) for the existing amounts. estimated_partner_rate: type: - number - 'null' description: As an intermediary of Tiqets, you receive a partner commission for your services in accordance with your partner contract. The Estimated Partner Rate is merely displayed to indicate the estimated difference between the ticket retail price (including VAT) and your estimated partner commission (excluding VAT). No rights can be derived from this estimation. The terms of your partner contract shall prevail and take precedence in all cases. CustomerDetailsResponse: type: - object - 'null' description: Customer details as provided during order creation. Please note that customer details are only returned up to one year after the visit date. For orders with a visit date further in the past, the object is returned as `null`. properties: firstname: type: string description: Customer's first name. lastname: type: string description: Customer's last name. email: type: string description: Customer's email address. phone: type: string description: Customer's phone number as provided during order creation. Subscription: type: object properties: is_active: type: boolean description: Subscription list status. id: type: number description: Unique ID created for this subscription list. name: type: string description: Name of the list. subscription_type: type: string description: Currently only `webhook` subscription type is supported. There may be different subscription type in the future. target_endpoint: type: - string - 'null' description: Partner notification URL. products: type: - array - 'null' description: List of product ID which will have change notification. items: type: object properties: product_id: type: integer description: Tiqets product ID. target_email: type: - string - 'null' description: Will be supported in the future. Partner email address for the notification. OrderReport: type: object properties: order_reference_id: type: string description: Unique identifier for the order. example: 869059006 basket_reference_id: type: string description: Identifier for the basket associated with the order. example: 268314360 click_id: type: string description: Unique tracking ID for the click that led to this order. example: Cj0KCQiA5abIBhCaARIsAM3-zFWTmeztUmknG_pugPab0m2nQq7oO6w5DTZa-B856T6Q21zSQsC9v6UaAuIlEALw_wcB device: type: string description: Device type used by the customer (e.g., desktop, mobile). example: desktop campaign_name: type: string description: Name of the marketing campaign associated with the order. example: entry product_id: type: integer description: ID of the purchased product. example: 974081 package_id: type: integer nullable: true description: Identifier of the purchased package, if applicable. example: null order_fulfilled_at: type: string format: date-time description: Timestamp indicating when the order was fulfilled. example: '2025-11-04T13:34:18.824991+00:00' visit_date: type: string format: date description: Date of the customer's visit or booking. example: '2025-12-31' visit_timeslot: type: string nullable: true description: Time slot of the customer's visit (if applicable). example: null sitebrand_name: type: string description: Full display name of the site or brand. example: MoMA Tickets sitebrand_shortname: type: string description: Short identifier or slug for the site or brand. example: moma customer_booking_language: type: string description: Language chosen by the customer during booking. example: it customer_self_cancellation_deadline: type: string format: date-time description: Deadline by which the customer can cancel their booking. example: '2025-12-30T23:59:00-05:00' customer_charged_currency: type: string description: Currency in which the customer was charged. example: EUR customer_country_code: type: string description: ISO country code of the customer’s residence. example: IT customer_ip_country: type: string description: ISO country code derived from the customer’s IP. example: IT currency: type: string description: Currency used for financial reporting. example: EUR sale_order_value_incl_vat: type: number format: float description: Total order value including VAT. example: 92.98 commission_excl_vat: type: number format: float description: Commission amount excluding VAT. example: 11.16 variants: type: array description: List of product variants included in the order. items: type: object properties: variant_id: type: integer description: Identifier of the specific product variant. example: 13376 quantity: type: integer description: Quantity of this variant in the order. example: 3 OrderReportList: type: array items: $ref: '#/components/schemas/OrderReport' RefundReport: type: object properties: order_reference_id: type: string description: Unique identifier for the refunded order. example: 919735658 basket_reference_id: type: string description: Identifier for the basket associated with the refund. example: 306259950 device: type: string description: Device type used by the customer (e.g., desktop, mobile). example: desktop refunded_at: type: string format: date-time description: Timestamp when the refund was processed. example: '2025-11-04T13:46:03.361715+01:00' currency: type: string description: Currency of the refunded transaction. example: EUR sale_order_value_incl_vat: type: number format: float description: Refunded order value including VAT (negative for refunds). example: -51.58 commission_excl_vat: type: number format: float description: Refunded commission excluding VAT (negative for refunds). example: -10.39 sitebrand_name: type: string description: Full display name of the site or brand. example: MoMA Tickets sitebrand_shortname: type: string description: Short identifier or slug for the site or brand. example: moma RefundReportList: type: array items: $ref: '#/components/schemas/RefundReport' ProductChangeNotificationSubscriptions: type: object description: List of all your product change notification subscriptions. properties: subscription_ids: type: array description: Identifiers of your product change notification subscriptions. items: type: string example: - 2b4e1f08-c4ef-4a4f-992e-1f7120332c6b - 8d9a6cd1-7c0b-4bf1-86e2-3fbcb0f2db56 required: - subscription_ids ProductChangeNotificationSubscriptionRequest: type: object description: Request body used to subscribe to product change notifications. properties: subscription_type: type: string description: Scope of the subscription. enum: - product_ids - experience_ids - destination_ids - products_i_sell example: product_ids entity_ids: type: array nullable: false description: Unique identifiers for the entities that belong to the selected subscription scope. minItems: 1 uniqueItems: true items: type: integer example: 974081 change_types: type: array description: | Non-empty set of change types the partner wants to be notified about. minItems: 1 uniqueItems: true items: type: string enum: - product_details_update - checkout_disabled - checkout_enabled example: product_details_update callback_url: type: string format: uri description: HTTP or HTTPS endpoint where Tiqets will send the product change notifications. example: https://example-partner.com/webhooks/product-change required: - subscription_type - change_types - callback_url ProductChangeNotificationSubscription: allOf: - $ref: '#/components/schemas/ProductChangeNotificationSubscriptionRequest' - type: object properties: subscription_id: type: string description: Unique identifier assigned to the subscription. status: type: string description: Current lifecycle status of the subscription. enum: - pending - active - degraded - failed required: - subscription_id - status ReactivateProductChangeSubscriptionRequest: type: object description: Optional payload used when reactivating an existing subscription. properties: callback_url: type: string format: uri nullable: true description: | Optional HTTP/HTTPS endpoint override. When omitted, the subscription is attempted to reactivate using the existing callback URL. example: https://example-partner.com/webhooks/product-change TemporaryEvent: type: object description: A temporary event (e.g. exhibitions in museums) tied to an experience and a date range, and accessed through a product. properties: id: type: integer description: Unique identifier of the temporary event. example: 42 title: type: string description: Title of the temporary event. example: Leaonardo Da Vinci. 500 years of Genius description: type: string nullable: true description: Description of the temporary event. example: | The exhibition is a celebration of the 500th anniversary of Leonardo da Vinci's death. It features over 100 of his most famous works, including The Mona Lisa, The Last Supper, and The Vitruvian Man. event_type: type: string description: Type of the temporary event. enum: - exhibition - other example: exhibition experience_id: type: integer description: Tiqets ID of the experience this event belongs to. example: 145528 experience_name: type: string description: Name of the experience. example: Prince Felipe Science Museum from_date: type: string format: date description: Start date of the event (inclusive). example: '2026-06-05' to_date: type: string format: date description: End date of the event (inclusive). example: '2026-06-30' tiqets_url: type: string format: uri description: URL of the event on Tiqets. example: https://www.tiqets.com/en/entradas-museo-de-las-ciencias-de-valencia-l154852/leaonardo-da-vinci-500-years-of-genius-e72447/ image: $ref: '#/components/schemas/Image' nullable: true description: Main image for the event. access_product_ids: type: array items: type: integer description: List of product IDs that grant access to this event. example: - 1006356 - 1006357 TemporaryEventsList: type: array items: $ref: '#/components/schemas/TemporaryEvent' ProductChange: type: object properties: product_id: type: integer example: 313373 change_types: type: array items: type: string example: checkout reason: type: - string - 'null' enum: - temporary_closure - out_of_season - other - null example: temporary_closure reopening_date: type: - string - 'null' enum: - within_7_days - within_2_weeks - within_month - more_than_month - null example: within_7_days alternative_product_id: type: - integer - 'null' example: 555789 required: - product_id - change_types ProductChangeNotificationV2CheckoutDisabledChange: type: object properties: change_type: type: string enum: - checkout_disabled reason_code: type: string description: Reason why checkout was disabled. enum: - permanent_closure - temporary_closure - out_of_season - other expected_reopening: type: string nullable: true description: Approximate reopening window for the product checkout. enum: - within_7_days - within_2_weeks - within_month - more_than_month recommended_alternative_product_id: type: integer nullable: true description: Suggested alternative product identifier, when applicable. required: - change_type - reason_code ProductChangeNotificationV2CheckoutEnabledChange: type: object properties: change_type: type: string enum: - checkout_enabled required: - change_type ProductChangeNotificationV2ChangeValue: description: Raw value for a product field before/after an update. nullable: true oneOf: - type: string - type: number - type: integer - type: boolean - type: object - type: array ProductChangeNotificationV2ProductDetailsUpdateChange: type: object properties: change_type: type: string enum: - product_details_update field_name: type: string description: Name of the product field that changed. type: type: string description: JSON type of the `old_value` and `new_value` fields (for example `string`). old_value: $ref: '#/components/schemas/ProductChangeNotificationV2ChangeValue' new_value: $ref: '#/components/schemas/ProductChangeNotificationV2ChangeValue' required: - change_type - field_name - type - new_value ProductChangeNotificationV2HealthCheckChange: type: object properties: change_type: type: string enum: - health_check status: type: string description: Current status of the subscription. enum: - pending - active - degraded - failed required: - change_type - status ProductChangeNotificationV2Change: description: Union of possible Product Change Notification V2 change payloads. oneOf: - $ref: '#/components/schemas/ProductChangeNotificationV2CheckoutDisabledChange' - $ref: '#/components/schemas/ProductChangeNotificationV2CheckoutEnabledChange' - $ref: '#/components/schemas/ProductChangeNotificationV2ProductDetailsUpdateChange' - $ref: '#/components/schemas/ProductChangeNotificationV2HealthCheckChange' discriminator: propertyName: change_type mapping: checkout_disabled: '#/components/schemas/ProductChangeNotificationV2CheckoutDisabledChange' checkout_enabled: '#/components/schemas/ProductChangeNotificationV2CheckoutEnabledChange' product_details_update: '#/components/schemas/ProductChangeNotificationV2ProductDetailsUpdateChange' health_check: '#/components/schemas/ProductChangeNotificationV2HealthCheckChange' ProductChangeNotificationV2ProductRecord: type: object properties: product_id: type: integer description: Tiqets product identifier affected by the change. changes: type: array minItems: 1 description: Concrete set of changes detected for the product. items: $ref: '#/components/schemas/ProductChangeNotificationV2Change' required: - product_id - changes ProductChangeNotificationV2Payload: type: object description: Detailed payload delivered by the Product Change Notification V2 webhook. properties: subscription_id: type: string description: Identifier of the subscription that triggered the notification. products: type: array minItems: 1 description: List of products impacted in this notification batch. items: $ref: '#/components/schemas/ProductChangeNotificationV2ProductRecord' required: - subscription_id - products responses: BadRequest: description: Bad Request -- Check your request parameters (typo in parameter or invalid value). content: application/json: schema: type: object properties: success: type: boolean message: type: string error: type: string field_errors: type: object example: success: false message: Invalid data error: validation_error field_errors: lang: - Missing data for required field. Unauthorized: description: Unauthorized -- Your API key is incorrect. content: application/json: schema: type: object properties: success: type: boolean message: type: string error: type: string example: success: false error: api_error message: an error occurred Forbidden: description: Forbidden -- The endpoint or parameters are not allowed for the matching API key. content: application/json: schema: type: object properties: success: type: boolean message: type: string error: type: string example: success: false message: The key is incorrect or the user is not authorized to access this resource. error: unauthorized NotFound: description: Not Found -- Requested resource/endpoint could not be found. content: application/json: schema: type: object properties: success: type: boolean message: type: string error: type: string example: success: false message: product 705268 was not found. error: not_found MethodNotAllowed: description: Method Not Allowed -- Check your request method. content: application/json: schema: type: object properties: success: type: boolean message: type: string error: type: string example: success: false error: api_error message: an error occurred TooManyRequests: description: Too Many Requests -- We currently apply a fair-use policy, but we might enforce limits in the future. content: application/json: schema: type: object properties: success: type: boolean message: type: string error: type: string example: success: false error: api_error message: an error occurred InternalServerError: description: Internal Server Error -- We had a problem with our server. Try again later. content: application/json: schema: type: object properties: success: type: boolean message: type: string error: type: string example: success: false error: api_error message: an error occurred ServiceUnavailable: description: Service Unavailable -- We're temporarily offline for maintenance. Please try again later. content: application/json: schema: type: object properties: success: type: boolean message: type: string error: type: string example: success: false error: api_error message: an error occurred x-navigateMethodsByName: true x-hideTryItPanel: true