API messages can include optional additional information for clients who choose to receive it. These optional fields handle non-standard cases where CRSs transmit data in unique formats.
For example, some CRSs provide cancellation policies at the product level instead of the rateplan level, while others include mealplan options with date ranges.
We've made these fields optional to accommodate these variations—clients can retrieve this data if needed, but implementation isn't mandatory. For partners who don't support certain usage patterns, we'll enable only their compatible hotels. These special cases affect less than 5% of our portfolio.
Clients must opt-in to receive this additional content, which is currently available in the Tax and Product APIs. When opting in to receive these fields, clients are required to include them in their Tax and Product audit API responses.
When starting your integration, you must specify your preferences regarding these additional fields.
At present, the Tax API and the Products API include these optional fields.
Tax API
| Field/Object | Datatype | Required | Description |
|---|---|---|---|
| conditions | Array | Yes | List of conditions to check for applicability of this tax. |
| refundable | Boolean | Yes | Indicates whether the tax is refundable. For example, refundable damage deposit fee will set this true. |
Conditions
| Field/Object | Datatype | Required | Description |
|---|---|---|---|
| conditionType | String | Yes | Enum: BOOKING_DATE, ARRIVAL_DATE, STAY_DATE, DAY_OF_WEEK, NIGHTLY_RATE, TOTAL_PRICE, NIGHT_NUMBER, LOS, LEAD_TIME.
Data Types:
Such new properties will only be enabled after the partner builds support for these enums. Possible upcoming values shortly are NIGHTLY RATE and NIGHT_NUMBER. |
| minValue | String | No | minValue and maxValue fields are used if the conditionType needs to specify a range for tax applicability with min and max values.
Otherwise, if a specific value or values need to be specified, the values field will be used. All minValue, maxValue, and values fields are inclusive. Note: Only one of the ranges (minValue/maxValue) or values will be specified. See below, for examples of minValue and maxValue are used. |
| maxValue | String | No | minValue and maxValue are used if the conditionType needs to specify a range for tax applicability with min and max values.
Otherwise, if a specific value or values need to be specified, the values field will be used. The "values" field is used to specify a particular value or values when the conditionType doesn't require a range for tax applicability. If a range with minimum and maximum values must be specified, minValue and maxValue are used. |
| values | Array | No | minValue and maxValue are used if the conditionType needs to specify a range for tax applicability with min and max values. Otherwise, if a specific value or values need to be specified, the values field will be used. The "values" field is used to specify a particular value or values when the conditionType doesn't require a range for tax applicability. If a range with minimum and maximum values must be specified, minValue and maxValue are used.
Example: ConditionType=DAY_OF_WEEK values=[“Saturday”, “Sunday”] |
| includes | Array | No | Includes a list of Fee codes on which this tax will be charged. |
Examples to specify condition ranges
Tax is applicable only for a booking date range or check-in date range. It will use minValue and maxValue fields to specify the start and end dates as strings. All dates are specified in ISO 8601 format - YYYY-MM-DD.
Date range example
{
"conditionType": "BOOKING_DATE",
"minValue": "2025-12-10",
"maxValue": "2025-12-31",
"values": null
}
Price range example 1
{
"conditionType": "RATE",
"minValue": "100",
"maxValue": "200",
"values": null
}
Price range example 2
Applicable for prices greater than 500
{
"conditionType": "RATE",
"minValue": "500",
"maxValue": null,
"values": null
}
Request Sample for Tax API with the additional fields
For more details about the Tax request and response structure, read through the Tax API page.
{ "messageId": "s6aa3d81-6c1d-4e12-b374-c76735b49fc9", "updateType": "UPDATE", "propertyCode": "NYCMIL", "tax": { "code": "FACFEE", "name": "Facilities Fee", "percentOrFlat": "FLAT", "chargeFrequency": "DAY", "chargeBasis": "ROOM", "value": 27.22, "taxType": "FEE", "appliesToChildren": false, "payAtProperty": true,"refundable": false,"conditions": [ { "conditionType": "BOOKING_DATE", "minValue": "2025-12-01", "maxValue": "2025-12-31" }, { "conditionType": "DAY_OF_WEEK", "values": [ "SAT", "SUN" ] }, { "conditionType": "TOTAL_PRICE", "minValue": "300", "maxValue": null } ] } }
Products API
Certain CRS/PMS systems manage specific content, such as mealPlan details and policies at the Product level instead of the Rateplan or Roomtype level.
This API enables partners to receive information at the Product level based on their preferences. This information is not sent automatically—clients or partners must opt-in to receive it if their system supports it.
If the partners opt-in to receive the cancellation policies (including seasonal cancellation policies) and mealPlans through Products API, they will not be sent in the Rateplan Push API.
| Field/Object | Datatype | Required | Description |
|---|---|---|---|
| mealplans | Array | No | Lis of mealplans applicable for this product |
| defaultCancellationPolicyCode | String | No | The default cancellation policy code applicable for this product. This is the unique identifier provided by Hotel Trader in the Cancellation Policy API. |
| seasonalCancellationPolicies | Array | No | List of seasonal cancellation policies applicable for this product. |
Mealplan
| Field/Object | Datatype | Required | Description |
|---|---|---|---|
| mealplanCode | String | Yes | A unique identifier for the meal plan. List of valid meal plan codes: BI, LI, DI, AI, None |
| meaplanDescription | String | Yes | Description of the meaplan option. |
| startDate | String | No | Start date from which the meal plan will be effective. ISO 8601 format - YYYY-MM-DD. Dates are inclusive. |
| endDate | String | No | End date until which the meal plan will be effective. ISO 8601 format - YYYY-MM-DD. Dates are inclusive. |
Sample Request for the Products API including additional fields
For more details about the Product request and response structure, read through the Product API page.
{
"messageId": "s6aa3d81-6c1d-4e12-b374-c76735b49fc7",
"rateplanCode": "HTPKG",
"propertyCode": "NYCMIL",
"products": [
{
"rateplanCode": "HTPKG",
"roomtypeCode": "KING",
"mealplans": [
{
"code": "CBF",
"mealplanDescription": "Free continental breakfast",
"startDate": "2025-12-01",
"endDate": "2025-12-31"
}
],
"defaultCancellationPolicyCode": "72HR",
"seasonalCancellationPolicies": [
{
"code": "24HR",
"startDate": "2025-12-01",
"endDate": "2025-12-31"
}
],
"taxes": [
"code1",
"code2"
]
}
]
}