TABLE OF CONTENTS

1. Overview

This document defines the Fee & Tax JSON structure used across GO APIs for communicating hotel charge rules — including taxes, service charges, city taxes, and other fees — between suppliers and distributors.

The specification supports a wide range of charge behaviours: fixed amounts, percentage-based taxes, net-rate percentages, tax-on-tax stacking.

ℹ️ Scope: This spec applies to Shop, LiveCheck, Hotel Detail, Prebook, Book, and Modify flows. 

2. Fee & Tax Field Reference

Each entry in the feeTaxes array is a FeeTax object with the following fields:

FieldTypeRequiredDescriptionExample
feeTaxesarrayNo

The 'feeTaxes' node, which sits at the same level as the legacy 'fees' node. This new structure supports tiered rates, tax-on-tax calculations, and net-rate percentages as defined in the FeeTaxes documentation.

Notes:

Since 'feeTaxes' contains the advanced tax and fee rules, if both the 'fees' node and the 'feeTaxes' node are provided, feeTaxes will take priority and ignore the 'fees' node.


@codestringYesRepresents the specific fee or tax category, such as Tax, Service Charge, City Tax, etc.

It must be unique within the same date range, and the same code will be considered the same Fee.

VAT
@descriptionstringNoText description of the fee or taxvalue added tax
dateRangeobjectYes

Effective period for this rule


@startDatestringYesThe start date of the date range,it's formatted as yyyy-MM-dd.2018-01-01
@endDatestringYes

The end date of the date range,it's formatted as yyyy-MM-dd.

2018-01-04
chargeModeenumYesEnum:[ TAX_ON_TAX_PERCENT, RATE_PERCENT, SUMMARY_RATE_PERCENT, NET_RATE_AMOUNT_PERCENT, FIXED ]

Please note the tax and rate percent modes below:

  - TAX_ON_TAX_PERCENT, RATE_PERCENT, SUMMARY_RATE_PERCENT, and NET_RATE_AMOUNT_PERCENT: Values represent percentage points (e.g., 10 = 10%).

  - FIXED: Indicates a fixed amount per chargeUnit.

  - SUMMARY_RATE_PERCENT and TAX_ON_TAX_PERCENT: The value for applyToTaxCodes will be provided.

  - SUMMARY_RATE_PERCENT: The chargeValue.value will be provided; the tierValue node will not be included.

  - TAX_ON_TAX_PERCENT, SUMMARY_RATE_PERCENT, and NET_RATE_AMOUNT_PERCENT: The inclusive value must be set to "false".

RATE_PERCENT
chargeUnitenumYesEnum: [ PER_ROOM_PER_STAY, PER_ROOM_PER_NIGHT, PER_PERSON_PER_STAY, PER_PERSON_PER_NIGHT ]

Note:

For PER_ROOM_PER_STAY and PER_PERSON_PER_STAY, the rule applies to the entire stay if the check-in date falls within the specified date range. If the check-in date is outside of this range, the rule will not be applied.

PER_ROOM_PER_NIGHT
collectByenumNoEnum:
[ Property, Distributor]

Notes:

1. Distributor (Default or if collectBy node is omitted): The distributor collects the fee/tax.

2. Property: The property collects the fee/tax. Please note that these may be excluded from distributor-side tax calculations.

Distributor
currencystringNoISO 4217 currency code.USD
applyToTaxCodesarrayNo

Notes: 

1. This field is required and must not be empty when chargeMode is set to TAX_ON_TAX_PERCENT or SUMMARY_RATE_PERCENT.

2. The listed code values must not form any circular dependencies.

["VAT"]

chargeValueobjectYes

Notes:

1. Either the field "value" or the node "tierValue" will be provided.

2. When the parent chargeMode is set to SUMMARY_RATE_PERCENT, only field "value" will be provided at the rule level.


valuenumberNo

Notes:

1. Percent Charge Modes: Use percentage points (e.g., enter 10 for 10%).

2. FIXED Mode: Use the direct numeric value (e.g., 10 represents a fixed amount).

10
tierValueobjectNo

inclusivebooleanYes

Indicate whether the fee is already included in the amount before tax or not.

Note:

If chargeUnit is PER_ROOM_PER_STAY or PER_PERSON_PER_STAY, the 'inclusive' field's value will be 'false'

false

3. Charge Modes

The chargeMode field determines how a fee is calculated against the base amount.

RATE_PERCENT

Percentage applied to the room base rate (may include some fees per business rules). Default value.

NET_RATE_AMOUNT_PERCENT

Percentage applied to the net room price, excluding all fees and taxes.

TOTAL_RATE_PERCENT

Percentage applied to the total booking amount (including all previously computed fees).

TAX_ON_TAX_PERCENT

Percentage applied on top of one or more previously-computed tax amounts. Requires applyToTaxCodes.

FIXED

A flat monetary amount per unit. Requires currency (ISO 4217).

4. Sample Payloads

Sample 1 – Tax 20% per room per night (inclusive, Distributor Collected)

A 20% tax per room, per night is included in the room rates. By default, this tax is charged by the distributor.


Calculation example:

AmountBeforeTax(ABT) = $100 

AmountAfterTax(AAT) = $100(tax is included in the ABT)

{
  "feeTaxes": [
    {
      "code": "Tax",
      "description": "Tax",
      "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-01-04"
      },
      "chargeMode": "RATE_PERCENT",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "collectBy": "Distributor",
      "chargeValue": {
        "value": 20
      },
      "inclusive": true
    }
  ]
}

Sample 2 – Fees: 10 USD per room per night included. Tax: 10.5% per room per night on the net rate, plus 30 USD per room per night

Breakdown of the fees and taxes:

  - Fees: 10 USD per room, per night (included).

  - Taxes: 10.5% of the Net Rate per room, per night.

  - Additional Charges: 30 USD per room, per night.


Calculation example:

AmountBeforeTax(ABT): $110 

AmountAfterTax(AAT): 110 +(110 -10)* 0.105 + 30 = $150.5

{
  "feeTaxes": [
  {
      "code": "Fees",
      "description": "extrafees",
      "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31"
      },
      "chargeMode": "FIXED",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "chargeValue" :{
          "value": 10,
      },
      "inclusive": true
    },
    {
      "code": "TaxP",
      "description": "TaxP",
      "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31"
      },
      "chargeMode": "NET_RATE_AMOUNT_PERCENT",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "chargeValue" :{
          "value": 10.5
      },
      "inclusive": false
    },
    {
      "code": "TaxA",
      "description": "TaxA ",
      "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31"
      },
      "chargeMode": "FIXED",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "chargeValue" :{
          "value": 30,
      },
      "inclusive": false
    }
  ]
}

Sample 3 – Tax1: 10 USD per room per stay, ServiceCharge: 10.5% of the sum of Tax1 and the base rate per room per night; Tax2: 20 USD per room per stay

Breakdown of the fees and taxes:

- Tax1: 10 USD per room, per stay.

- ServiceCharge: 10.5% of the combined total of the base rate and Tax 1, applied per room, per night.

- Tax2: 20 USD per room, per stay.


Calculation example:

AmountBeforeTax(ABT): $100 

AmountAfterTax(AAT): 100 + 10 + (100+10) * 10.5% + 20 = $141.55 

{
  "feeTaxes": [
    {
      "code": "Tax1",
      "description": "Tax",
      "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31"
      },
      "chargeMode": "FIXED",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "chargeValue": {
        "value": 10,
      },
      "inclusive": false
    },
    {
      "code": "ServiceCharge",
      "description": "Service Charge",
      "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31"
      },
      "chargeMode": "SUMMARY_RATE_PERCENT",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "applyToTaxCodes": [
        "Tax1"
      ],
      "chargeValue": {
        "value": 10.5,
      },
      "inclusive": false
    },
    {
      "code": "Tax2",
      "description": "Tax",
      "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31"
      },
      "chargeMode": "FIXED",
      "chargeUnit": "PER_ROOM_PER_STAY",
      "chargeValue": {
        "value": 10
      },
      "inclusive": false
    },
  ]
}


Sample 4 – Tax: 10% per room per night, ServiceCharge: 5 USD per person per night

Breakdow the fees and texes:

- Tax: 10% per room, per night.

- Service Charge: 5 USD per person, per night.

Calculation example:

AmountBeforeTax(ABT): $100 

AmountAfterTax(AAT)for 2 persons: 100 + 100 * 0.1 + 5 * 2 = $120

{
  "feeTaxes": [
    {
      "code": "Tax",
      "description": "Tax",
      "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31"
      },
      "chargeMode": "RATE_PERCENT",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "chargeValue": {
        "value": 10,
      },
      "inclusive": false
    },
    {
      "code": "ServiceCharge",
      "description": "Service Charge",
      "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31"
      },
      "chargeMode": " FIXED",
      "chargeUnit": "PER_PERSON_PER_NIGHT",
      "chargeValue": {
        "value": 5
      },
      "inclusive": false
    }
  ]
}


Sample 5 – Fee taxes varies based on date ranges

TaxP1 is a 10 USD per room per night charge included in the room rate, applicable from April 1 to May 1, 2018. TaxP2 is a 15% per room per night tax, included in the room rate, and applies from May 2 to June 3, 2018. A 30 USD service charge per room per night is added on top of the room rate. A 10.5% charge applies to the summary of the room rate and service charge, per room per night.

Breakdow the fees and texes:

  - April 1 – May 1, 2018: TaxP1 is 10 USD per room per night, included in the room rate.

  - May 2 – June 3, 2018: TaxP2 is 15% per room per night, included in the room rate.

  - Service Charge: A 30 USD service charge per room per night is added on top of the room rate.

  - Additional Tax: A 10.5% charge applies to the total sum of the room rate and service charge, per room per night.


Calculation example:

DateABTTaxP1(10 USD)TaxP2(15%)ServiceCharge(30 USD)TaxP3AAT
April 30
100
10N/A30(100+30)*10.5%=13.65
100+30+13.65=143.65
May 110010N/A3013.65
143.65
May 2100N/A100*0.15=1530(100+30)*10.5%=13.65
100+30+13.65=143.65
May 3100N/A100*0.15=153013.65
143.65
{
  "feeTaxes": [
    {
      "code": "TaxP1",
      "description": "TaxP1",
      "chargeMode": "FIXED",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "dateRange": {
        "start": "2018-04-01",
        "end": "2018-05-01"
      },
      "chargeValue": {
        "value": 10
      },
      "inclusive": true
    },
    {
      "code": "TaxP2",
      "description": "TaxP2",
      "chargeMode": "RATE_PERCENT",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "dateRange": {
        "start": "2018-05-02",
        "end": "2018-06-03"
      },
      "chargeValue": {
        "value": 15
      },
      "inclusive": true
    },
    {
      "code": "ServiceCharge",
      "description": "Service Charge",
      "chargeMode": "FIXED",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "dateRange": {
        "start": "2018-01-01",
        "end": "2018-12-31"
      },
      "chargeValue": {
        "value": 30
      },
      "inclusive": false
    },
    {
      "code": "Tax",
      "description": "Tax",
      "chargeMode": "SUMMARY_RATE_PERCENT",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "dateRange": {
        "start": "2018-01-01",
        "end": "2018-12-31"
      },
      "applyToTaxCodes": [
        "ServiceCharge"
      ],
      "chargeValue": {
        "value": 10.5
      },
      "inclusive": false
    }
  ]
}

5. FAQ

Q: How do I apply per-person, per-night scaling?
Compute the fee/tax per unit using the rules, then multiply by (persons × nights) according to chargeUnit.
Q: How do I tax on tax?
Use TAX_ON_TAX_PERCENT and list target codes in applyToTaxCodes. Ensure those referenced fees are computed first.
Q: Is the code field case-sensitive?
Yes. tax and Tax are treated as different codes. Use consistent casing across your integration.