Tiqets API Specification

Overview

The Tiqets API provides endpoints for browsing and booking activity tickets through the Tiqets.com integration. It includes catalog management for experiences, products, and real-time availability checking.

All catalog endpoints return canonical entities (CCountry, CLocation, CExperience, CProduct, CProductVariant, CTimeslot) that are transformed from native Tiqets data. This ensures consistent data models across all supplier integrations.

Base Path: /tiqets

Content Types: - Request: application/json - Response: application/json

Response Format

All endpoints return a TlinqApiResponse object:

{
  "apiStatus": {
    "errorCode": "OK",
    "errorMessage": "Success"
  },
  "apiData": { ... }
}

Date Format: All dates are in ISO 8601 format (yyyy-MM-dd)

---

Location Endpoints

POST /tiqets/countries

Lists all countries with Tiqets experiences.

Request Body:

Field	Type	Required	Description
session	string	No	User session token

Request Example:

{
  "session": "user-session-token"
}

Response Structure: Returns an array of CCountry canonical entities.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "countryId": 1,
      "countryCode": "AE",
      "countryName": "United Arab Emirates",
      "countryFullName": "United Arab Emirates"
    },
    {
      "countryId": 2,
      "countryCode": "NL",
      "countryName": "Netherlands",
      "countryFullName": "Netherlands"
    },
    {
      "countryId": 3,
      "countryCode": "FR",
      "countryName": "France",
      "countryFullName": "France"
    }
  ]
}

---

POST /tiqets/cities

Lists cities with Tiqets experiences, optionally filtered by country.

Request Body:

Field	Type	Required	Description
session	string	No	User session token
countryId	string	No	Filter by country ID
enabledOnly	boolean	No	Only show enabled cities (default: false)

Request Example:

{
  "session": "user-session-token",
  "countryId": "AE",
  "enabledOnly": true
}

Response Structure: Returns an array of CLocation canonical entities.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "cityCode": "dubai",
      "cityName": "Dubai",
      "countryCode": "AE",
      "latitude": 25.2048,
      "longitude": 55.2708,
      "timezone": "Asia/Dubai",
      "currency": "AED",
      "enabled": true
    },
    {
      "cityCode": "abu-dhabi",
      "cityName": "Abu Dhabi",
      "countryCode": "AE",
      "latitude": 24.4539,
      "longitude": 54.3773,
      "timezone": "Asia/Dubai",
      "currency": "AED",
      "enabled": true
    }
  ]
}

---

POST /tiqets/city/enable

Enables a city for display in the catalog.

Request Body:

Field	Type	Required	Description
session	string	No	User session token
cityId	string	Yes	City ID to enable

Request Example:

{
  "session": "user-session-token",
  "cityId": "dubai"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": "City dubai enabled"
}

Error Codes: - MISSING_PARAMETER - cityId is required

---

POST /tiqets/city/disable

Disables a city from display in the catalog.

Request Body:

Field	Type	Required	Description
session	string	No	User session token
cityId	string	Yes	City ID to disable

Request Example:

{
  "session": "user-session-token",
  "cityId": "dubai"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": "City dubai disabled"
}

Error Codes: - MISSING_PARAMETER - cityId is required

---

Experience Endpoints

POST /tiqets/experiences

Lists experiences (activity categories) with optional filters and pagination.

Request Body:

Field	Type	Required	Description
session	string	No	User session token
cityId	string	No	Filter by city ID
countryId	string	No	Filter by country ID
categoryId	string	No	Filter by category
page	integer	No	Page number (1-based, default: 1)
pageSize	integer	No	Results per page (default: 50)

Request Example:

{
  "session": "user-session-token",
  "cityId": "dubai",
  "page": 1,
  "pageSize": 20
}

Response Structure: Returns an array of CExperience canonical entities.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "experienceId": "145158",
      "experienceType": "attraction",
      "title": "Burj Khalifa: At the Top (Level 124 & 125)",
      "tagline": "Visit the world's tallest building",
      "description": "Experience breathtaking views from the observation deck of the iconic Burj Khalifa...",
      "cityId": "dubai",
      "countryId": "AE",
      "streetAddress": "1 Sheikh Mohammed bin Rashid Blvd",
      "postalCode": "12345",
      "latitude": 25.1972,
      "longitude": 55.2744,
      "googlePlaceId": "ChIJj3R6sMlDXz4RWLq1O1s3NJk",
      "imageSmall": "https://images.tiqets.com/small/burj-khalifa.jpg",
      "imageMedium": "https://images.tiqets.com/medium/burj-khalifa.jpg",
      "imageLarge": "https://images.tiqets.com/large/burj-khalifa.jpg",
      "imageXlarge": "https://images.tiqets.com/xlarge/burj-khalifa.jpg",
      "imageAltText": "Burj Khalifa observation deck",
      "ratingAverage": 4.7,
      "ratingCount": 12500,
      "fromPrice": 149.00,
      "currency": "AED",
      "tagIds": "1,5,12",
      "productIds": "234567,234568,234569",
      "experienceUrl": "https://www.tiqets.com/burj-khalifa-tickets",
      "active": true
    },
    {
      "experienceId": "145159",
      "experienceType": "tour",
      "title": "Desert Safari with BBQ Dinner",
      "tagline": "Experience the Arabian desert adventure",
      "description": "Enjoy dune bashing, camel riding, and a traditional BBQ dinner...",
      "cityId": "dubai",
      "countryId": "AE",
      "latitude": 25.0657,
      "longitude": 55.5285,
      "ratingAverage": 4.5,
      "ratingCount": 8500,
      "fromPrice": 199.00,
      "currency": "AED",
      "active": true
    }
  ]
}

---

POST /tiqets/experience

Gets a single experience by ID.

Request Body:

Field	Type	Required	Description
session	string	No	User session token
experienceId	string	Yes	Experience ID (supplier ID)

Request Example:

{
  "session": "user-session-token",
  "experienceId": "145158"
}

Response Structure: Returns a single CExperience canonical entity.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "experienceId": "145158",
    "experienceType": "attraction",
    "title": "Burj Khalifa: At the Top (Level 124 & 125)",
    "tagline": "Visit the world's tallest building",
    "description": "Experience breathtaking views from the observation deck of the iconic Burj Khalifa. At 555 meters above ground, levels 124 and 125 offer a stunning 360-degree view of Dubai.",
    "cityId": "dubai",
    "countryId": "AE",
    "streetAddress": "1 Sheikh Mohammed bin Rashid Blvd",
    "postalCode": "12345",
    "latitude": 25.1972,
    "longitude": 55.2744,
    "googlePlaceId": "ChIJj3R6sMlDXz4RWLq1O1s3NJk",
    "imageSmall": "https://images.tiqets.com/small/burj-khalifa.jpg",
    "imageMedium": "https://images.tiqets.com/medium/burj-khalifa.jpg",
    "imageLarge": "https://images.tiqets.com/large/burj-khalifa.jpg",
    "imageXlarge": "https://images.tiqets.com/xlarge/burj-khalifa.jpg",
    "imageAltText": "Burj Khalifa observation deck",
    "ratingAverage": 4.7,
    "ratingCount": 12500,
    "fromPrice": 149.00,
    "currency": "AED",
    "tagIds": "1,5,12",
    "productIds": "234567,234568,234569",
    "experienceUrl": "https://www.tiqets.com/burj-khalifa-tickets",
    "active": true
  }
}

Error Codes: - MISSING_PARAMETER - experienceId is required - NOTFOUND - Experience not found

---

Product Endpoints

POST /tiqets/products

Lists products (bookable items) for an experience or city.

Request Body:

Field	Type	Required	Description
session	string	No	User session token
experienceId	string	No*	Filter by experience ID
cityId	string	No*	Filter by city ID

*Either experienceId or cityId must be provided.

Request Example:

{
  "session": "user-session-token",
  "experienceId": "145158"
}

Response Structure: Returns an array of CProduct canonical entities.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "prodCode": "234567",
      "prodName": "At the Top - Standard Entry",
      "productDescription": "Standard entry to At the Top observation deck on levels 124 & 125...",
      "productPrice": 149.00,
      "currency": "AED",
      "hasTimeSlot": true,
      "maxQuantity": 10,
      "hasVendorBooking": true,
      "productInclusions": "Entry to levels 124 & 125|Multimedia presentation|Audio guide",
      "productExclusions": "Food and beverages|SKY lounge access",
      "productInfo": "Arrive 30 minutes before your timeslot. Valid ID required.",
      "cancelPolicy": "Free cancellation up to 24 hours before",
      "prodImgSmall": "https://images.tiqets.com/small/burj-khalifa-standard.jpg",
      "prodImgMed": "https://images.tiqets.com/medium/burj-khalifa-standard.jpg",
      "prodImgLarge": "https://images.tiqets.com/large/burj-khalifa-standard.jpg"
    },
    {
      "prodCode": "234568",
      "prodName": "At the Top SKY - Premium Entry",
      "productDescription": "Premium entry including SKY lounge on level 148...",
      "productPrice": 379.00,
      "currency": "AED",
      "hasTimeSlot": true,
      "hasVendorBooking": true
    }
  ]
}

Error Codes: - MISSING_PARAMETER - Either experienceId or cityId must be provided

---

POST /tiqets/product

Gets a single product by ID with full details.

Request Body:

Field	Type	Required	Description
session	string	No	User session token
productId	string	Yes	Product ID (supplier ID)

Request Example:

{
  "session": "user-session-token",
  "productId": "234567"
}

Response Structure: Returns a single CProduct canonical entity.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "prodCode": "234567",
    "prodName": "At the Top - Standard Entry",
    "productDescription": "Standard entry to At the Top observation deck on levels 124 & 125. Enjoy breathtaking views of Dubai from one of the world's tallest buildings.",
    "productPrice": 149.00,
    "currency": "AED",
    "hasTimeSlot": true,
    "maxQuantity": 10,
    "hasVendorBooking": true,
    "productInclusions": "Entry to levels 124 & 125|Multimedia presentation|Audio guide",
    "productExclusions": "Food and beverages|SKY lounge access",
    "productInfo": "Arrive 30 minutes before your timeslot. Valid ID required. No large bags allowed.",
    "cancelPolicy": "Free cancellation up to 24 hours before the visit. No refund for cancellations within 24 hours.",
    "prodImgSmall": "https://images.tiqets.com/small/burj-khalifa-standard.jpg",
    "prodImgMed": "https://images.tiqets.com/medium/burj-khalifa-standard.jpg",
    "prodImgLarge": "https://images.tiqets.com/large/burj-khalifa-standard.jpg"
  }
}

Error Codes: - MISSING_PARAMETER - productId is required - NOTFOUND - Product not found

---

POST /tiqets/product/variants

Gets product variants (ticket types) for a product.

Request Body:

Field	Type	Required	Description
session	string	No	User session token
productId	string	Yes	Product ID (supplier ID)

Request Example:

{
  "session": "user-session-token",
  "productId": "234567"
}

Response Structure: Returns an array of CProductVariant canonical entities.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "servcode": "V123456",
      "servname": "Adult",
      "servdesc": "Visitors aged 13 and above",
      "cprice": 149.00,
      "currency": "AED",
      "maxOccupancy": 1,
      "available": true
    },
    {
      "servcode": "V123457",
      "servname": "Child (4-12)",
      "servdesc": "Children aged 4 to 12 years",
      "cprice": 99.00,
      "currency": "AED",
      "maxOccupancy": 1,
      "available": true
    },
    {
      "servcode": "V123458",
      "servname": "Infant (0-3)",
      "servdesc": "Infants aged 0 to 3 years (free entry)",
      "cprice": 0.00,
      "currency": "AED",
      "maxOccupancy": 1,
      "available": true
    }
  ]
}

Error Codes: - MISSING_PARAMETER - productId is required

---

Availability Endpoints

POST /tiqets/availability

Gets real-time availability and pricing for a product within a date range. This endpoint calls the Tiqets API in real-time and returns the native TqAvailability structure with rich nested data.

Request Body:

Field	Type	Required	Description
session	string	No	User session token
productId	string	Yes	Product ID (supplier ID)
dateFrom	string	Yes	Start date (yyyy-MM-dd)
dateTo	string	Yes	End date (yyyy-MM-dd)

Request Example:

{
  "session": "user-session-token",
  "productId": "234567",
  "dateFrom": "2025-07-15",
  "dateTo": "2025-07-20"
}

Response Structure: Returns a TqAvailability native entity with nested availability data.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "productId": "234567",
    "availableDates": [
      {
        "date": "2025-07-15",
        "available": true,
        "timeslots": [
          {
            "timeslotId": "TS001",
            "time": "09:00",
            "available": true,
            "vacancies": 50
          },
          {
            "timeslotId": "TS002",
            "time": "10:00",
            "available": true,
            "vacancies": 45
          },
          {
            "timeslotId": "TS003",
            "time": "11:00",
            "available": true,
            "vacancies": 30
          },
          {
            "timeslotId": "TS004",
            "time": "14:00",
            "available": true,
            "vacancies": 60
          },
          {
            "timeslotId": "TS005",
            "time": "17:00",
            "available": true,
            "vacancies": 25
          }
        ],
        "variantPrices": [
          {
            "variantId": "V123456",
            "price": 149.00,
            "currency": "AED",
            "originalPrice": 169.00,
            "availableQuantity": 50
          },
          {
            "variantId": "V123457",
            "price": 99.00,
            "currency": "AED",
            "originalPrice": 119.00,
            "availableQuantity": 50
          },
          {
            "variantId": "V123458",
            "price": 0.00,
            "currency": "AED",
            "originalPrice": 0.00,
            "availableQuantity": 50
          }
        ]
      },
      {
        "date": "2025-07-16",
        "available": true,
        "timeslots": [
          {
            "timeslotId": "TS006",
            "time": "09:00",
            "available": true,
            "vacancies": 55
          },
          {
            "timeslotId": "TS007",
            "time": "10:00",
            "available": true,
            "vacancies": 40
          }
        ],
        "variantPrices": [
          {
            "variantId": "V123456",
            "price": 159.00,
            "currency": "AED",
            "originalPrice": 169.00,
            "availableQuantity": 55
          }
        ]
      },
      {
        "date": "2025-07-17",
        "available": false,
        "timeslots": [],
        "variantPrices": []
      }
    ]
  }
}

Error Codes: - MISSING_PARAMETER - Product ID or date range not provided - API_ERROR - Failed to retrieve availability from Tiqets API

---

POST /tiqets/timeslots

Gets flattened timeslot data for a product within a date range. This is a simplified alternative to /availability that returns canonical CTimeslot entities.

Request Body:

Field	Type	Required	Description
session	string	No	User session token
productId	string	Yes	Product ID (supplier ID)
dateFrom	string	Yes	Start date (yyyy-MM-dd)
dateTo	string	Yes	End date (yyyy-MM-dd)

Request Example:

{
  "session": "user-session-token",
  "productId": "234567",
  "dateFrom": "2025-07-15",
  "dateTo": "2025-07-17"
}

Response Structure: Returns an array of CTimeslot canonical entities.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "timeSlotId": "TS001",
      "startTimestamp": "2025-07-15T09:00:00",
      "status": "available",
      "available": 50,
      "adultPrice": 149.00,
      "childPrice": 99.00,
      "dynamicPrice": true
    },
    {
      "timeSlotId": "TS002",
      "startTimestamp": "2025-07-15T10:00:00",
      "status": "available",
      "available": 45,
      "adultPrice": 149.00,
      "childPrice": 99.00,
      "dynamicPrice": true
    },
    {
      "timeSlotId": "TS003",
      "startTimestamp": "2025-07-15T11:00:00",
      "status": "available",
      "available": 30,
      "adultPrice": 149.00,
      "childPrice": 99.00,
      "dynamicPrice": true
    }
  ]
}

Error Codes: - MISSING_PARAMETER - Product ID or date range not provided - API_ERROR - Failed to retrieve timeslots from Tiqets API

---

Tag Endpoints

Tags are used to categorize experiences and products. They are organized into tag types (e.g., "Activity categories", "Amenities", "Accessibility features").

POST /tiqets/tags

Lists tags, optionally filtered by type group name.

Request Body:

Field	Type	Required	Description
session	string	No	User session token
typeGroupName	string	No	Filter by tag type group (e.g., "Activity categories")

Request Example:

{
  "session": "user-session-token",
  "typeGroupName": "Activity categories"
}

Response Structure: Returns an array of CTag canonical entities.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "tagId": "1",
      "name": "Museums",
      "tagTypeId": 101,
      "typeName": "Museums & Culture",
      "typeGroupName": "Activity categories",
      "iconUrl": "https://cdn.tiqets.com/icons/museums.svg"
    },
    {
      "tagId": "2",
      "name": "Theme Parks",
      "tagTypeId": 102,
      "typeName": "Entertainment",
      "typeGroupName": "Activity categories",
      "iconUrl": "https://cdn.tiqets.com/icons/theme-parks.svg"
    },
    {
      "tagId": "3",
      "name": "City Tours",
      "tagTypeId": 103,
      "typeName": "Tours & Experiences",
      "typeGroupName": "Activity categories",
      "iconUrl": "https://cdn.tiqets.com/icons/tours.svg"
    },
    {
      "tagId": "4",
      "name": "Outdoor Activities",
      "tagTypeId": 104,
      "typeName": "Nature & Adventure",
      "typeGroupName": "Activity categories",
      "iconUrl": "https://cdn.tiqets.com/icons/outdoor.svg"
    }
  ]
}

---

POST /tiqets/tag-types

Lists all tag types available in the system.

Request Body:

Field	Type	Required	Description
session	string	No	User session token

Request Example:

{
  "session": "user-session-token"
}

Response Structure: Returns an array of CTagType canonical entities.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "tagTypeId": 101,
      "name": "Museums & Culture",
      "groupName": "Activity categories",
      "iconUrl": "https://cdn.tiqets.com/icons/category-museums.svg"
    },
    {
      "tagTypeId": 102,
      "name": "Entertainment",
      "groupName": "Activity categories",
      "iconUrl": "https://cdn.tiqets.com/icons/category-entertainment.svg"
    },
    {
      "tagTypeId": 103,
      "name": "Tours & Experiences",
      "groupName": "Activity categories",
      "iconUrl": "https://cdn.tiqets.com/icons/category-tours.svg"
    },
    {
      "tagTypeId": 201,
      "name": "Wheelchair Access",
      "groupName": "Accessibility features",
      "iconUrl": "https://cdn.tiqets.com/icons/wheelchair.svg"
    },
    {
      "tagTypeId": 301,
      "name": "Free WiFi",
      "groupName": "Amenities",
      "iconUrl": "https://cdn.tiqets.com/icons/wifi.svg"
    }
  ]
}

---

POST /tiqets/tags/sync

Synchronizes tags and tag types from the Tiqets API to the local database. This is an administrative endpoint that fetches all tags and tag types from Tiqets and updates the local cache.

Request Body:

Field	Type	Required	Description
session	string	No	Admin session token

Request Example:

{
  "session": "admin-session-token"
}

Response Structure: Returns a status message with sync counts.

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": "Synced 15 tag types and 127 tags"
}

Error Codes: - API_ERROR - Failed to sync tags from Tiqets API

---

Data Models

CCountry (Canonical Country Entity)

Field	Type	Description
countryId	integer	Internal country ID
countryCode	string	ISO 2-letter country code
countryName	string	Country name
countryFullName	string	Full country name
countryPhoneCode	integer	International phone code

CLocation (Canonical Location/City Entity)

Field	Type	Description
cityCode	string	City identifier (from Tiqets cityId)
cityName	string	City name
countryCode	string	ISO 2-letter country code
countryName	string	Country name
latitude	double	City latitude
longitude	double	City longitude
timezone	string	City timezone (e.g., "Asia/Dubai")
currency	string	Default currency code
enabled	boolean	Whether city is enabled for display
type	string	Location type
subType	string	Location subtype

CExperience (Canonical Experience Entity)

Field	Type	Description
experienceId	string	Tiqets experience ID
experienceType	string	Type (attraction, tour, museum, etc.)
title	string	Experience title
tagline	string	Short tagline
description	string	Full description
cityId	string	City ID
countryId	string	Country ID
streetAddress	string	Street address
postalCode	string	Postal code
latitude	double	Location latitude
longitude	double	Location longitude
googlePlaceId	string	Google Place ID
imageSmall	string	Small image URL
imageMedium	string	Medium image URL
imageLarge	string	Large image URL
imageXlarge	string	Extra large image URL
imageAltText	string	Image alt text
ratingAverage	double	Average rating (0-5)
ratingCount	integer	Number of ratings
fromPrice	double	Starting price
currency	string	Currency code
tagIds	string	Comma-separated tag IDs
productIds	string	Comma-separated product IDs
experienceUrl	string	Tiqets experience URL
active	boolean	Whether experience is active

CProduct (Canonical Product Entity)

Field	Type	Description
prodCode	string	Product code (from Tiqets productId)
prodName	string	Product title
productDescription	string	Full description
productPrice	double	Minimum/base price
childPrice	double	Child price if applicable
currency	string	Currency code
hasTimeSlot	boolean	Whether product has timeslots
maxQuantity	integer	Maximum tickets per order
hasVendorBooking	boolean	Whether product is active/bookable
productInclusions	string	Pipe-separated inclusions
productExclusions	string	Pipe-separated exclusions
productInfo	string	Important information
cancelPolicy	string	Cancellation policy text
prodImgSmall	string	Small image URL
prodImgMed	string	Medium image URL
prodImgLarge	string	Large image URL

CProductVariant (Canonical Variant Entity)

Field	Type	Description
servid	integer	Internal variant ID
servcode	string	Variant code (from Tiqets variantId)
servname	string	Variant label (e.g., "Adult", "Child")
servdesc	string	Variant description
cprice	double	Current price
bprice	double	Base price
currency	string	Currency code
maxOccupancy	integer	Max visitors per ticket
maxAdults	integer	Max adult tickets
maxChildren	integer	Max child tickets
hasTimeSlots	boolean	Whether variant has timeslots
available	boolean	Whether variant is available

CTimeslot (Canonical Timeslot Entity)

Field	Type	Description
timeSlotId	string	Timeslot ID
optionId	integer	Option/variant ID
startTimestamp	string	Start date/time (ISO format)
status	string	Availability status
available	integer	Number of available spots
adultPrice	double	Adult price for this timeslot
childPrice	double	Child price for this timeslot
dynamicPrice	boolean	Whether pricing is dynamic

CTag (Canonical Tag Entity)

Field	Type	Description
tagId	string	Tiqets tag ID
name	string	Tag display name
tagTypeId	integer	Parent tag type ID
typeName	string	Tag type name
typeGroupName	string	Tag type group (e.g., "Activity categories")
iconUrl	string	Tag icon URL

CTagType (Canonical Tag Type Entity)

Field	Type	Description
tagTypeId	integer	Tiqets tag type ID
name	string	Tag type name
groupName	string	Tag type group (e.g., "Activity categories")
iconUrl	string	Tag type icon URL

TqAvailability (Native Availability Response)

The /availability endpoint returns native Tiqets data structure for rich nested availability information:

Field	Type	Description
productId	string	Product ID
availableDates	array	Array of AvailableDate objects

TqAvailability.AvailableDate:

Field	Type	Description
date	string	Date (yyyy-MM-dd)
available	boolean	Whether date is available
timeslots	array	Array of Timeslot objects
variantPrices	array	Array of VariantPrice objects

TqAvailability.Timeslot:

Field	Type	Description
timeslotId	string	Timeslot ID
time	string	Time (HH:mm)
available	boolean	Whether timeslot is available
vacancies	integer	Number of available spots

TqAvailability.VariantPrice:

Field	Type	Description
variantId	string	Variant ID
price	decimal	Current price
currency	string	Currency code
originalPrice	decimal	Original price (before discount)
availableQuantity	integer	Available quantity

---

Integration Notes

Canonical Entity Model

All catalog endpoints (countries, cities, experiences, products, variants, timeslots) return canonical entities that are transformed from native Tiqets data using the EntityFacade pattern. This ensures: - Consistent field names across different supplier integrations - Type-safe data (e.g., BigDecimal to Double conversion) - Decoupled API responses from supplier-specific data models

The /availability endpoint is an exception - it returns the native TqAvailability structure because it contains complex nested data that benefits from the original structure.

Caching Strategy

• Static data (countries, cities, experiences, products, variants, tags) is cached in the local database and refreshed periodically via the StaticDataRefresher service.
• Dynamic data (availability, pricing) is fetched in real-time from the Tiqets API.

Initial Data Sync

Before using the API, populate the local cache using:

StaticDataRefresher refresher = new StaticDataRefresher();
refresher.initialSync(5);  // Sync 5 pages of experiences

Tag Sync

Tags must be synced separately from the main catalog data. Use the /tiqets/tags/sync endpoint or call programmatically:

TiqetsCatalogFacade facade = TiqetsCatalogFacade.instance();
facade.syncTagTypes();  // Sync tag types first
facade.syncTags();      // Then sync tags

Tags are useful for: - Filtering experiences by category (e.g., "Museums", "Theme Parks", "City Tours") - Displaying category chips on experience pages - Building category navigation in the UI

The typeGroupName field distinguishes between different tag categories: - "Activity categories" - Main experience categories for UI display - "Amenities" - Venue amenities (WiFi, parking, etc.) - "Accessibility features" - Accessibility information

ID Conventions

All IDs returned by this API are supplier IDs from Tiqets, not internal database IDs. This ensures consistency when making subsequent API calls.

Rate Limiting

Real-time availability calls are subject to Tiqets API rate limits. Implement appropriate caching and request throttling for high-traffic scenarios.