Title
Page icon
Create new category
Edit page index title
Edit category
Edit link
Suppliers, Products & Rates
Travel Curious connects Resellers to Suppliers through a channel binding process - a commercial agreement that makes a Supplier's Products and Rates visible to your API requests. If you do not see the Suppliers or Products you expect, contact the Supplier directly or reach out to your Travel Curious Integration Manager.
The three core entities in this section form a hierarchy. Every API call in the transaction flow depends on IDs retrieved here:
Supplier → Product → Rate → Availability → Hold → Booking
The name, title, and description fields on the main entities - Supplier, Product, Rate, and Rate Price - are treated as standard fields, not content fields.
Suppliers who do not implement content capability may continue using these fields.
Capabilities
Some fields on Supplier, Product, Rate, and Traveler Type objects are opt-in v1.3 features rather than standard structural data. When an object supports one of these features, its identifier appears in that object's capabilities discovery array - e.g. ["travelcurious/content", "travelcurious/bookingquestions", "travelcurious/addons"].
Only the following are capabilities in this sense: Content, Add-ons, and Booking Questions. Everything else in the Object Components tables below (Contacts, Hours, Locations, Prices, Constraints, etc.) is a standard field - present or absent based on what the Supplier configured, not gated behind capability discovery.
Not every capability is available at every entity level. See the Object Components table for each entity below for exactly which capabilities apply there, and the Reseller API Reference for the full schema of each.
Capability Discovery: When querying a Product, the response will include a capabilities array. This array explicitly tells you which advanced features are supported by that specific product so your system knows what to expect. For example, if a product supports Add-ons, Content and Booking Questions, you will see values like the following in this capability array: ["travelcurious/content","travelcurious/bookingquestions","travelcurious/addons"]
Suppliers
A Supplier represents the operator providing the travel experience - a tour company, museum, attraction, or event venue. The Supplier object carries the operator's identity, contacts, accepted traveler types, business hours, and location data.
🔗 Available Endpoints & Params
Endpoints | Recommended use |
|---|---|
Daily cache refresh of your full Supplier catalog | |
Real-time lookups; prefer this over the list wherever possible |
Parameter | Applies to | Description |
|---|---|---|
| Single only | Includes the |
| Single only | Comma-separated list of BCP 47 tags (e.g. |
| Single only | Comma-separated list of formats ( |
⚙️ Supplier Object Components
Component | Type | Version | Operational Function |
|---|---|---|---|
Contacts | Array | v1.2 & v1.3 | Used for high-level account management, central billing inquiries, or escalation issues with the operator's corporate team. |
Content | Object | v1.3 Only | Usually used for brand identity. Contains "About Us" marketing copy, global operator terms, and high-level company assets. See Content. |
Hours | Array | v1.2 & v1.3 | Usually used for Corporate Business Hours. Indicates when the operator's central customer service or head office is open to take inquiries. |
Locations | Array | v1.2 & v1.3 | This is usually the legal business address of the Supplier. The Corporate Headquarters or central depot. |
Traveler Types | Array | v1.2 & v1.3 | Global Age Dictionaries (Rarely Used). This represents the operator's default baseline for age bands across their entire business (e.g., defining that, generally, a "Child" is 4–12 years old). Note: It is not commonly used or relied upon at this level, as individual products usually dictate their own specific age rules. |
📥 Fields Recently Added to Supplier Models
Field | Type | Description | Example | Notes |
|---|---|---|---|---|
v1.3 | object | Provides localized, structured, and customer-facing content that can be attached to multiple entities. This object is the primary source for descriptive marketing data across all levels of the catalog. | - | v1.3 This capability is only present in the latest version, not in v1.2. See more details in the Content page. |
| string | A detailed overview of the Supplier or operator, highlighting their offerings, background, and value proposition. This content is intended for display in full detail pages and should help users understand what makes the Supplier unique. | "Urban Quest Adventures turns city streets into interactive playgrounds. Our app-guided scavenger hunts and outdoor escape games combine local landmarks, puzzles, and storytelling to create unforgettable experiences in cities like New York, Chicago, and San Francisco." | Optional for the supplier to populate. |
| string | Customer-facing name of the Supplier, intended for display in UIs. | "Urban Quest Adventures - Explore Cities Like Never Before" | Optional for the supplier to populate. |
👁️🗨️ Response Example
Get Supplier call response example below. Note: the id field needs to be unique and is used to identify the Supplier.
Products
A Product is a bookable experience offered by a Supplier - a walking tour, museum entry, river cruise, parasailing session, or live show. Each Product belongs to one Supplier and may have multiple Rates.
🔗 Available Endpoints & Params
Endpoints | Recommended use |
|---|---|
Daily cache refresh | |
Real-time product detail pages |
Parameter | Applies to | Description |
|---|---|---|
| List and Single | Includes an |
| Single only | Includes the |
| Single only | Comma-separated list of BCP 47 tags (e.g. |
| Single only | Comma-separated list of formats ( |
⚙️ Product Object Components
Component | Type | Version | Operational Function |
|---|---|---|---|
Add-ons | Array | v1.3 Only | Optional or mandatory purchasable extras configured at the Product level (fast-lane passes, equipment rentals). Applies to all Rates and traveler types under this Product. See Add-ons. |
Contacts | Array | v1.2 & v1.3 | List of designated operational points of contact, on-site coordinators, or emergency help lines for this specific experience. See Contacts. |
Content | Object | v1.3 Only | Usually used for the experience description. Houses the main marketing narrative, overarching highlights, general FAQs (e.g., "What should I wear?"), and primary photo galleries. See Content. |
Hours | Array | v1.2 & v1.3 | General Operating Hours. Indicates the overarching availability of the experience (e.g., "The Museum is open 09:00 to 17:00, Tuesday through Sunday"). See Hours. |
Locations | Array | v1.2 & v1.3 | Ordered array of physical address coordinates and routing notes. The Main Venue or Default Meeting Point. This is the physical address of the museum, the main entrance of the theme park, or the general starting point for the walking tour. See Locations. |
📥 Fields Recently Added to Product Models
Field | Type | Description | Example | Notes |
|---|---|---|---|---|
v1.3 | array | Optional or mandatory purchasable extras configured at the Product level (fast-lane passes, equipment rentals). Applies to all Rates and traveler types under this Product. See Add-ons. | - | v1.3 This capability is only present in the latest version, not in v1.2. See more details in the Add-ons page. |
v1.3 | object | Provides localized, structured, and customer-facing content that can be attached to multiple entities. This object is the primary source for descriptive marketing data across all levels of the catalog. | - | v1.3 This capability is only present in the latest version, not in v1.2. See more details in the Content page. |
| string(enum) | Specifies the technical format of the barcode or identifier that will be issued upon booking confirmation. This field informs the Reseller how to correctly parse, render, or encode the ticket value for the end guest. While the list contains standard industry types like | "QR_CODE" | Required to be populated by the Supplier. |
New | string(enum) | Defines how fulfillment identifiers are distributed within a booking. A value of | "TICKET" | Required to be populated by the Supplier. |
New | boolean | Indicates whether the booking is confirmed immediately. If | "true" | Required to be populated by the Supplier. |
New | boolean | Indicates whether fulfillment identifiers (tickets/vouchers) are available immediately upon confirmation. If | "true" | Required to be populated by the Supplier. |
New | string | Language and region identifier. Must be a valid BCP 47 RFC 5646 RFC 4647 language tag. | "en-US" | Required to be populated by the Supplier. |
v1.3 | array | Classifies the operational nature of the Product to determine the booking behavior.
| "BEST_AVAILABLE" | v1.3 This field is only present in the latest version, not in v1.2. Required to be populated by the Supplier. |
New | string | Provides clear, human-readable directions explaining how the guest should redeem their ticket or voucher at the venue. | "Please present your QR code at the main entrance kiosk to receive your physical pass." | Optional for the Supplier to populate. Note: This is currently mapped to an extension key. You can continue using them for now, but the key will be deprecated in the future. |
Note: Add-ons carry their own independent deliveryFormats/deliveryMethods values, separate from the Product-level fields described here. See Add-ons → Barcode and Ticket Delivery.
👁️🗨️ Response Example
Rates
A Rate defines a specific bookable option within a Product. A single Product can have multiple Rates, for example, separate morning and afternoon sessions with independent capacity, or a standard and premium tier. Each Rate has its own pricing, hours, cancellation policy, and hold configuration.
🔗 Available Endpoints & Params
Endpoints | Recommended use |
|---|---|
Daily cache refresh | |
Real-time Rate detail pages |
Parameter | Applies to | Description |
|---|---|---|
| List and Single | Includes an |
| List and Single | An array of questions that can be asked during the booking flow. Visible when the |
| Single only | Includes the |
| Single only | Comma-separated list of BCP 47 tags (e.g. |
| Single only | Comma-separated list of formats ( |
⚙️ Rate Object Components
Component | Type | Version | Operational Function |
|---|---|---|---|
Add-ons | Array | v1.3 Only | Purchasable extras scoped to this specific Rate only (e.g., a private guide upgrade). Appears in |
Booking Questions | Object | v1.3 Only | An array of questions that can be asked during the booking flow. Visible when the |
Content | Object | v1.3 Only | Usually used for Rate option-specific inclusions. Highly specific details for this option, such as VIP perks, or what is strictly included/excluded in this price option compared to others. See Content. |
Hours | Array | v1.2 & v1.3 | Also used for General Operating Hours or for the specific rate option hours. Indicates the overarching availability of the experience (e.g., "The Museum is open 09:00 to 17:00, Tuesday through Sunday"). See Hours. |
Locations | Array | v1.2 & v1.3 | Ordered array of physical address coordinates and routing notes. The Option-Specific Touchpoint. Used when a specific variation has a different logistical path. For example, a "VIP Dinner Cruise" Rate might depart from Pier 4, while the standard "Lunch Cruise" Rate departs from Pier 1. See Locations. |
Prices | Array | v1.2 & v1.3 | Contains the actual currency breakdowns, age bands (e.g., ADULT, CHILD), net/retail amounts, and included tax structures for the Rate price option. See Pricing. |
📥 Fields Recently Added to Rate Models
Field | Type | Description | Example | Notes |
|---|---|---|---|---|
v1.3 | array | Purchasable extras scoped to this specific Rate only (e.g., a private guide upgrade). Visible when | - | v1.3 This capability is only present in the latest version, not in v1.2. See more details in the Add-ons page. |
v1.3 | object | An array of questions that can be asked during the booking flow. Visible when the | - | v1.3 This capability is only present in the latest version, not in v1.2. See more details in the Booking Questions page. |
v1.3 | object | Provides localized, structured, and customer-facing content that can be attached to multiple entities. This object is the primary source for descriptive marketing data across all levels of the catalog. | - | v1.3 This capability is only present in the latest version, not in v1.2. See more details in the Content page. |
| string | A detailed explanation of the specific activity, experience, or event offered in this Option/Rate. This long-form content is meant to appear on Product detail pages, highlighting experience-specific details or restrictions. | "Perfect for early birds who want to explore the city before the crowds." | Optional for the Supplier to populate. |
cancelPolicy New | string | Text that defines the cancellation policy | "Full refund available up to 24 hours before start time." | Optional for the Supplier to populate. |
👁️🗨️ Response Example
Rate Type
There are three different rate types: FREESALE, PASS, and RESERVED.
FREESALETickets and entry passes are available during the opening hours of the attraction, and there is no specific entry time.PASSRates are used for Products where access is granted multiple times, whereasFREESALEandRESERVEDRates are normally single-use.RESERVEDRates can be with or without capacity, depending on the requirements and inventory defined by the Supplier, and always require a hold to ensure that the availability for a certain date and time does not change between the availability check and the booking request. Bookings can, however, be rejected if there is insufficient capacity at the requested date and time.
Being able to handle both types of product rates gives you, the Reseller, the flexibility to manage both general admission (FREESALE) and time-slot defined (RESERVED) types. This allows you to accommodate a broader range of use cases for different suppliers and their connected products.
Validity vs. Hours
The rate.hours are used to define the available times for the product, which are the product operating hours the traveler is able to enter the attraction.
rate.valid is used to determine when the rate is available for purchase. Bookings can only occur within the defined valid from and valid until attributes. Some suppliers set up products ahead of their validity date for visibility and preparation. Please note and enforce the validity dates.
An example for this would be if a Supplier sets up 2 different rates: General Admission ticket for 2026 and 2027.
They are available to be booked the entire year, but there are specific days and times the product is available in that year.
The timezone field is provided as an IANA timezone string (e.g., "America/New_York"). If this field is empty, then the open and close times are communicated in UTC and should be used to convert to the local time of the product location.
Rate minTravelers & maxTravelers
This field represents the minimum and maximum number of travelers to qualify for this rate which means the maximum number of tickets that can be purchased for this rate. The data is being mapped from the Supplier setup. This will prevent customers from selecting more than the allowed quantity and getting errors during Hold and Booking requests.
Rate travelerTypes, ageBand and modifier
Support list of ageBand to describe a particular age or occupation of a traveler type
Ideally, being able to consume the
nameandmodifierto support the full breadth of price/traveler types the operators provide. These could be things likeEU_CITIZEN,MILITARYMinimally support all age bands in the specifications
ADULT,ANY,CHILD,INFANT,SENIOR,STUDENT,YOUTHThe
ANYtype may be used instead of the above listedageBand, if distinctions between age or occupation are not relevant to the product. It’s a generic ageband type used by some suppliers and it’s recommended to be supported, otherwise, a workaround needs to be done to map that value.
Solve multiple instances of the same age band. There are instances where operators will send 2 prices for the same traveler type (ie 2 - ADULT). This typically means there is a difference in the name/modifier that makes it a different traveler type still limited to adults OR it means they’re running a special price for a limited time. You can:
Consume name/modifier and display both
Display only one lower or higher of the 2 prices
Cancelable Flag
The cancellation policy for a product is indicated by the boolean cancelable = true or cancelable = false. When true, it indicates that bookings made under this Rate are eligible for cancellation. Please note that this does not refer to a hold, which can always be released or canceled regardless of this setting.
✨Tip: You can also check the refundable boolean on the Rate, which indicates if a booking made with this Rate is eligible for a monetary refund. This defines the financial policy, whereas cancelable defines the operational ability to void a booking.
Rate Prices
Each Rate object contains a prices array listing baseline prices by traveler type. These are always superseded by the Price Schedule when a scheduled price exists for the requested date - always check the Price Schedule first and use static prices only as a fallback.
However, because experience prices often fluctuate based on seasonality or specific dates, you must use the Price Schedule API to retrieve the actual bookable price for a specific date.
When placing a Hold or a Booking, provide the priceId from Price Schedule response.
More detailed pricing implementation steps can be found in the Pricing section.
Please note that Rates from the Price Schedule ALWAYS supersede Rate prices.
Rate Traveler Type
Traveler Types define the eligibility requirements and classification for a passenger (e.g., Adult, Child, Senior, Student). Includes age ranges, modifiers, and display information.
⚙️ Traveler Type Object Components
Component | Type | Version | Operational Function |
|---|---|---|---|
Add-ons | Array | v1.3 Only | Purchasable extras scoped to this specific traveler type/age band only (e.g., a mandatory harness rental). Appears in |
Content | Object | v1.3 Only | Houses localized text clarifying the specific passenger profile (e.g., stating that a "Senior" ticket applies to ages 65+ or a "Student" requires a valid university ID at the gate). |
Constraints | Array | v1.2 & v1.3 | Defines mandatory physical or demographic boundaries for this specific ticket, such as strict minimum/maximum ages, height restrictions, or weight limits. |
📥 Fields Recently Added to Traveler Type Models
Field | Type | Description | Example | Notes |
|---|---|---|---|---|
v1.3 | array | Purchasable extras scoped to this specific traveler type/age band only. Visible when | - | v1.3 This capability is only present in the latest version, not in v1.2. See more details in the Add-ons page. |
v1.3 | object | Provides localized, structured, and customer-facing content that can be attached to multiple entities. This object is the primary source for descriptive marketing data across all levels of the catalog. | v1.3 This capability is only present in the latest version, not in v1.2. See more details in the Content page. | |
| Array | |||
| string | Provides information and details about this item. | "Perfect for early birds who want to explore the city before the crowds." | Optional for the Supplier to populate. |
| string | Customer-facing display name. This value may be shown to end customers across reseller and distribution channels. | Optional for the Supplier to populate. |
Traveler Type Constraints New
The constraints[] adds a structured array (with min, max, and type) that can be used across multiple API capabilities (including Traveler Types, Add-ons, and Booking Questions) to enforce validation rules.
When present, your UI must parse these rules to prevent invalid bookings, such as preventing the addition of a child ticket if they don't meet a minimum height requirement, or capping a quantity counter for Add-ons.
This same Constraint structure (min, max, pattern, type) is reused by the constraints[] array on Add-on objects to define purchase limits (e.g., min/max quantity per guest or booking). See Add-ons → Constraints and Purchase Limits.
📥 Fields Recently Added to Constraints Models
Field | Type | Description | Example | Notes |
|---|---|---|---|---|
| string | Provides information and details about this item. | "Perfect for early birds who want to explore the city before the crowds." | Optional for the Supplier to populate. |
| number($double) | Minimum allowable value for the constraint. If specified, the traveler or item must meet or exceed this value to be eligible. At least one of min or max must be set. Must be less than or equal to max if both are set. | Optional for the Supplier to populate. | |
| number($double) | Maximum allowable value for the constraint. If specified, the traveler or item must not exceed this value to be eligible. At least one of min or max must be set. Must be greater than or equal to min if both are set. | Optional for the Supplier to populate. | |
| string | A regex pattern for validation. | Optional for the Supplier to populate. | |
| string(enum) | Enumerates the supported constraint types, defining both the measurement and unit used to evaluate eligibility. | Required to be populated by the Supplier if |
Constraint Types (Enums)
Suppliers can use 15 different constraint types. Check the Category to understand the context of the constraint and how it should be applied to your front-end logic.
Constraint Type | Category | Description | Common Use Case / Example |
|---|---|---|---|
| Physical & Demographic | Enforces a minimum or maximum height limit. | Theme park rides requiring a rider to be at least 120cm tall. |
| Physical & Demographic | Enforces a minimum or maximum weight limit. | Helicopter tours or ziplines with strict weight capacities. |
| Physical & Demographic | A generic numeric boundary, most often used for age verification. | A "Senior" traveler type requiring the guest to be between 65 and 110 years old. |
| Purchase & Selection | General fallback for min/max purchase quantity across contexts. | Basic inventory caps when a specific scope isn't provided. |
| Purchase & Selection | Min/max items allowed per total reservation. | Capping a group at exactly 1 Private Guide or a maximum of 10 drink vouchers. |
| Purchase & Selection | Min/max items allowed per individual traveler. | Requiring exactly 1 Full Body Harness per guest on a zipline. |
| Purchase & Selection | Min/max items allowed per product occurrence. | Limiting souvenir photo packages to 2 per tour group. |
| Purchase & Selection | Min/max items allowed per day of an experience. | Capping parking passes to 1 per day. |
| Purchase & Selection | Number of options a user must pick from a provided list. | "Please choose exactly 3 meals from the menu." |
| Data Validation | Minimum/maximum character count for a text input. | Ensuring a free-text "Special Requirements" answer is under 500 characters. |
| Data Validation | Enforces specific text formatting using a regular expression in the | Validating that a passport number or email address follows the correct format. |
UI Implementation Guidance & Examples
Use the constraint type, min, and max values to drive your UI controls programmatically.
Example 1: Add-on Purchase Limits (Max Capacity)
If a group is restricted to buying a maximum of 10 drink vouchers per booking, your integration must not allow more than 10 to be submitted. A recommended UI approach is to disable the + quantity counter once it reaches 10.
Example 2: Mandatory Minimum Selection
If an item is mandatory (e.g., a required harness for a zipline), the min will be greater than 0. Your application must ensure this minimum is met before allowing the booking to proceed. A common UI pattern is to automatically add this item to the cart and hide the "Remove" button, or explicitly prompt the user to select it before continuing.
Example 3: Physical Restrictions
If a theme park ride requires a traveler to be a specific height, you should validate this on the front end before allowing the traveler to be added to the booking payload.
🔗 Find the full details here: Reseller API Reference v1.3 (Beta)
Questions? We'd love to hear them. Contact Travel Curious Support.