Pricing

Price Schedule is a connectivity feature offered by Travel Curious, allowing operators to set specific daily price points for tours and attractions rather than static pricing for all dates.

Within the transaction flow, you will need to retrieve Supplier, Product, and Rate objects regardless of the pricing type. At the time of availability and traveler type selection, you must check both the Availabilities and Price Schedule endpoints to ensure that there is capacity AND a valid price for that date and traveler type.

Please note that Get Price Schedule needs to be implemented in conjunction with the Get Rates call.

The Get Rates call uses the product_id and the supplier_id which returns a list of available rates with their rate_ids. The rate_id can be used in the price schedule call to get details of a specific rate. It should also be stored and used when creating a hold for cross-reference.

Static prices on the Rate object provide a baseline, but they are always superseded by the Price Schedule when a scheduled price exists for the requested date and Rate.

The data from both the Availability and Price Schedule endpoints must be used together to determine which dates/times are available to be booked, and what traveler types/prices are available at those times.

For example: Availabilities are checked for Product 1, Rate A, which utilizes Travel Curious’s Price Schedule feature and contains a RatePrice for an Adult traveler. When checking availability, Rate A is available at various times on June 23rd and June 24th. However, upon checking the Price Schedule for Rate A, an Adult price is only visible on June 23rd. Therefore, Rate A is only bookable for an adult on June 23rd using the price returned on the Price Schedule.

Summary of the Booking Flow

Supplier, Product, and Rate are selected as normal.
Availabilities endpoint is queried to determine when the product has capacity.
Price Schedule endpoint is queried to determine which traveler types are available and at what price point.
A Hold is created using the selected Supplier, Product, Rate, Price, and Availability IDs.
A Booking is placed finalizing the transaction.

If a RatePrice is present on the Price Schedule, this should be used above all else.
It is an error to use the PriceId of a RatePrice if a price for the requested time & traveler type is present on the Price Schedule.

Price Object Structure

All monetary amounts in the API are expressed as integers in the minor unit of the currency (e.g., cents for USD, euro cents for EUR) as defined by ISO 4217. A retail price of $40.00 USD is represented as 4000. Always use the currency's ISO 4217 minor unit to interpret amounts correctly - the relationship between major and minor units varies by currency.

Every price in the API carries up to three tiers:

Field	Description
`retail`	The recommended selling price the guest pays, inclusive of any applied discounts. This is the price to display at checkout.
`net`	The wholesale settlement amount owed to the Supplier by the Reseller.
original	The price before any discounts were applied. Use this to render a strike-through price in your UI when it differs from `retail`.

Note: If your system does not support the use of both retail and net, please let your integration manager know that Travel Curious can set up pricing rules to provide the type of rates that you need per operator.

Price Schedule Response Structure

The response contains a nested, multi-level map:

The top-level map uses RateIDs as keys.
Each RateID contains a map using one or more Dates (YYYY-MM-DD) as the key.
Finally, each Date points to an array of prices.

Each array contains, for that RateID and Date:

A travelerType object, which is a structured description of the age, membership, or role of the traveler this price is intended for.
An optional array of startTimes containing the specific times of the day. If startTimes is empty, this price is valid for the entire date.
All valid prices (original, net, retail) and their currency.
An optional array of includedTaxes if any taxes or additional fees are included in the prices.
An optional array of labels (e.g., "early-bird", "mobile-exclusive") assigned to this price, which can be used to filter prices available by specific sales channels.

Start Times Granularity

The Price Schedule may contain an array of startTimes if an operator has various timeslots in a day. If there are different prices for different times of day (e.g., a "Matinee" vs. "Evening" show), the Price Schedule provides that level of granularity. If a price has one or more startTimes, that price MUST be used when placing a hold with the matching at time

startTimes example
    
xxxxxxxxxx
 
{    "9010149b-537f-4417-884c-39970b1dc9bb": {        "2023-08-17": [            {                "id": "d4fa23b4-6b9c-4407-b642-bc678bd3c00a",                "name": "ADULT",                "net": {                    "amount": 5405,                    "currency": "USD"                },                "original": {                    "amount": 0,                    "currency": "USD"                },                "retail": {                    "amount": 5405,                    "currency": "USD"                },                "travelerType": {                    "ageBand": "ADULT",                    "maxAge": 100,                    "minAge": 13,                    "name": "ADULT"                },                "startTimes": [                  "2023-08-17T12:00:00-04:00",                  "2023-08-17T13:00:00-04:00",                  "2023-08-17T14:00:00-04:00",                ]            },            {                "id": "d4fa23b4-6b9c-4407-b642-bc678bd3c00a",                "name": "ADULT",                "net": {                    "amount": 4405,                    "currency": "USD"                },                "original": {                    "amount": 0,                    "currency": "USD"                },                "retail": {                    "amount": 4405,                    "currency": "USD"                },                "travelerType": {                    "ageBand": "ADULT",                    "maxAge": 100,                    "minAge": 13,                    "name": "ADULT"                },                "startTimes": [                  "2023-08-17T19:00:00-04:00",                  "2023-08-17T20:00:00-04:00",                  "2023-08-17T21:00:00-04:00",                ]            }        ]    }}
Copy

Included Taxes

Operators have the ability to send not only the prices, but also the tax information, depending on the country's requirements. Each entry should include the id, name, currency, and at least one price attribute (original, retail, or net). More than one price attribute may be provided if applicable, as shown inthe example below.

If the Operator does not give any tax details, the includedTaxes object is not present.

Note: When includedTaxes is present, at least one of original, net or retail must be included; all of them may be provided if applicable.

Each includedTaxes object will contain the following fields:

Field Name	Format	Required	Description
`id`	string	No	A unique identifier for the tax or fee. Strongly recommended for internal reference and integration purposes.
`name`	string	Available (required from supplier)	A short, descriptive name for the tax being applied (e.g., "VAT", "City Tax"). The name should be unique. If no tax `id` is provided, the system will use the combination of name and currency to identify uniqueness.
`currency`	string	Available (required from supplier)	The currency code (ISO 4217 format) in which the tax amount is expressed (e.g., "USD", "EUR"). The currency must match the currency used for the item's price (`original`, `net` or `retails`).
`original`	int64	Optional - conditionally required from supplier	The amount of tax or fee applied to the original price. At least one of `original`, `net` or `retail` price fields must be present.
`net`	int64	Optional - conditionally required from supplier	The amount of tax or fee applied to the net price. At least one of `original`, `net` or `retail` price fields must be present.
`retail`	int64	Optional - conditionally required from supplier	The amount of tax or fee applied to the retail price. At least one of `original`, `net` or `retail` price fields must be present.

Example

Price Schedule example
    
xxxxxxxxxx
 
{  "783dba55-f9a8-4b82-a4c6-fe2cadad45d2": {    "2021-04-05": [      {        "id": "aefe688e-4b90-4e92-b6b6-23a660eaa3f8",        "name": "Adult Rate",        "net": {          "amount": 10000,          "currency": "USD"        },        "original": {          "amount": 12000,          "currency": "USD"        },        "retail": {          "amount": 15000,          "currency": "USD"        },        "startTimes": [          "2021-04-05T14:30:00-06:00",          "2021-04-05T16:30:00-06:00"        ],        "status": "ACTIVE",        "travelerType": {          "ageBand": "ADULT",          "maxAge": 99,          "minAge": 18,          "modifier": "NONE",          "name": "Adult",          "title": "Adult (18+)",          "description": "Price for a single adult traveler."        },        "includedTaxes": [          {            "id": "tax-001",            "name": "VAT",            "currency": "USD",            "net": 800,            "retail": 1000,          },          {            "id": "tax-002",            "name": "City Tax",            "currency": "USD",            "net": 300,            "retail": 500,          }        ],      }    ]  }}
Copy

Price Labels and Channel Binding

RatePrice and PriceScheduleItem objects may carry a labels[] string array. These are filterable tags configured by the Supplier that control which prices are visible to specific distribution channels (ie.: "early-bird", "mobile-exclusive")

If your channel binding includes price tag filters (priceTags), only prices whose labels match your configured tags will be returned. If you are not seeing prices you expect, check with your Travel Curious Integration Manager whether price tag filtering is applied to your channel.

Last-Minute Pricing Check

Use GET /suppliers/{supplier_id}/products/{product_id}/pricing/schedule for a last-minute pricing check. This can be set as a configurable option based on transaction volume. Your Travel Curious Implementation manager can tell you if a particular supplier changes pricing frequently. This will avoid a hold or booking failure later.

Handling Zero-Value vs. Unconfigured Prices

To accurately represent pricing data, the API must differentiate between two distinct scenarios:

Unconfigured Prices: The Supplier simply did not provide a specific price.
Free Prices: The Supplier explicitly set the price to zero (e.g., a free "Infant" ticket).

To allow Resellers to safely parse this difference without breaking legacy integrations, Travel Curious has introduced a new HTTP header: X-Allow-Nil-Static-Prices.

When calling WITHOUT the header (Default Behavior)

This is the recommended implementation for all new integrations. It provides strict accuracy regarding Supplier data.

Dynamic Pricing Objects (net, retail, original): Pricing values that were not provided by the Supplier will be explicitly returned as nil (null). For example, if a Supplier only configures a net value, the net object is returned, while the retail and original objects will be explicitly nil rather than defaulting to 0. If a Supplier unconfigures prices for a day or age band, price objects will be completely omitted from the response.
Intentional Free Tickets: If you see a price with an amount: 0 for any field, it is a guarantee that the Supplier explicitly and intentionally submitted the price as $0.00 (free).
Data Updates: If a Supplier later updates an unconfigured (nil) price to contain an actual dollar amount, the API will generate new Price IDs. The parent Rate IDs will remain unchanged. (This mirrors standard behavior for any price update).

When calling WITH the header (X-Allow-Nil-Static-Prices: true)

If you use the header, the API defaults to legacy behavior for backward compatibility.

All missing or unconfigured dollar amounts will continue to be returned as amount: 0.
Warning: In this mode, Resellers will not be able to programmatically discern the difference between a missing price and a truly free $0.00 price.

Note that the same behaviour is applied to Price Schedule endpoint and the embedded rates under Booking items in Booking endpoint responses.

Examples

Request WITHOUT the X-Allow-Nil-Static-Prices=true header (default):

Example
    
xxxxxxxxxx
 
Copy

Response

Example
    
xxxxxxxxxx
 
Copy

Request WITH the X-Allow-Nil-Static-Prices=true header:

Example
    
xxxxxxxxxx
 
Copy

Response

Example
    
xxxxxxxxxx
 
Copy

If these data behaviors conflict with your system logic, please notify your Integration Manager. We can provide alternative solutions, such as our pricing engine, to ensure a smooth integration.

Last updated on

Was this page helpful?