Tax

The Tax API request initiated by Hotel Trader contains detailed tax information such as tax name, tax type, charge frequency, charge basis, charge type, effective dates, etc.

Initiator - Hotel Trader

Endpoint

New taxes

For creating new tax or taxes for the first time in the client system.

[POST] https://<client-base-url>/taxes

Update existing taxes

For updating a single tax that already exists in the client system.

[PUT] https://<client-base-url>/tax/<code>

Request

HTTP Headers

All the HTTP Headers are mandatory. These headers are applicable and remain the same for both end-points of the Tax API.

Header Name	Type
Content-Type	application/json
Accept-Encoding	gzip
Authorization	Basic <token>

Request Description

All the fields in the create tax request are described below.

Field/Object	Datatype	Required	Description
messageId	String	Yes	A string that uniquely identifies this particular message. This should be returned in the response.
updateType	String	Yes	The type of cancellation policy update. Possible values - NEW, UPDATE, ENABLED, DISABLED. More information on this object can be found here.
propertyCode	String	Yes	A unique hotel code provided by Hotel Trader identifies the hotel for which tax metadata is sent in this request.
taxes	Array	Yes	A list of tax objects, which contain the tax metadata.

Field/Object	Datatype	Required	Description
name	String	Yes	The name of the tax.
code	String	Yes	A code provided by Hotel Trader which identifies this tax. This code is unique for each tax for a property.
description	String	No	A short description of the tax.
taxType	String	Yes	The tax type (such as tax, resort fee, or facility fee) Possible values - TAX, FEE
chargeFrequency	String	Yes	The frequency at which the tax is charged (e.g., per stay, per night).
chargeBasis	String	Yes	The basis for charging the tax (e.g., per person, per room).
percentOrFlat	String	Yes	Whether the tax value is a percentage or a flat amount.
appliesToChildren	Boolean	Yes	Specifies whether the tax should be applied to children or not. This will be used only if the chargeBasis is PERSON. For more information read the ageCategories node in the Hotel API.
payAtProperty	Boolean	Yes	Whether the tax is paid directly at the property.
value	Float	Yes	The value of the tax.

Pay-at-Property Fee

The obligation to distribute taxes to the eventual guest downstream is the client’s responsibility.

It is mandatory to pass along any Pay-at-Property fees like resort fees, amenities fees, etc.

Failure to display these fees on the confirmation emails/vouchers will result in Hotel Trader passing along the fees to the client, as Hotel Trader is contractually liable to pay for any Pay-at-Property fees that are missing from the confirmation voucher.

Additional Optional Fields

If you have opted-in to receive the additional fields available as part of the Tax API, please ensure that you go through the Additional Content page for field description, usage, and examples.

Example

Request to add new tax

{
    "messageId": "s6aa3d81-6c1d-4e12-b374-c76735b49fc9",
    "updateType": "NEW",
    "propertyCode": "NYCMIL",
    "taxes": [
        {
            "code": "FACFEE",
            "name": "Facilities Fee",
            "percentOrFlat": "FLAT",
            "chargeFrequency": "DAY",
            "chargeBasis": "ROOM",
            "value": 27.22,
            "taxType": "FEE",
            "appliesToChildren": false,
            "payAtProperty": true
        },
        {
            "code": "STATE",
            "name": "New York State Sales Tax",
            "percentOrFlat": "PERCENT",
            "chargeFrequency": "STAY",
            "chargeBasis": "ROOM",
            "value": 8.875,
            "appliesToChildren": false,
            "payAtProperty": false,
            "taxType": "TAX"
        },
        {
            "code": "CITTAX",
            "name": "NY City Sales Tax",
            "percentOrFlat": "PERCENT",
            "chargeFrequency": "STAY",
            "chargeBasis": "ROOM",
            "value": 5.875,
            "appliesToChildren": false,
            "taxType": "FEE",
            "payAtProperty": false
        }
    ]
}

Request for updating existing tax

{
    "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
    }
}

Response

This API follows the Standard Response model of the Metadata Push API.

Tax API