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

Starting with API Version v4.10, DS GO will use the new 'feeTaxes' node instead of the 'fees' node.


@codestringYesRepresents the charge category represents specific types of fees, such as Tax, Service Charge, City Tax, or Pet Fees. Each category will be unique; any duplicate types will be treated as the same charge.
Notes: Duplicate codes are allowed for multiple date ranges. However, duplicate codes are not allowed within the same date range.		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]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

The node exists only when the charge mode is TAX_ON_TAX_PERCENT or SUMMARY_RATE_PERCENT.

Notes:

1. When ChargeMode = TAX_ON_TAX_PERCENT: The value of the node is required and cannot be blank or null. It specifies the tax codes used to calculate this tax.

2. When ChargeMode = SUMMARY_RATE_PERCENT: The field specifies the tax or fee codes used to calculate this summary tax/fee. If it is null, the tax/fee should be calculated based on the room rate amount only.

["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.


valuenumberYes

Notes:

1.  ChargeMode=FIXED (Value=80): Represents a fixed amount of 80.

2.  ChargeMode=TAX_ON_TAX_PERCENT / RATE_PERCENT / NET_RATE_AMOUNT_PERCENT (Value=10): Represents 10% of the basis amount.

3.  ChargeMode=SUMMARY_RATE_PERCENT (Value=5): Represents 5% of the summary amount.

10
tierValueobjectNoSupporting soon
inclusivebooleanYes

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

  - true: Tax is included in the ABT and does not need to be added for the Amount After Tax (AAT) calculation.

  - false: Tax is not included in the ABT and must be added for the AAT calculation.

Note:

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

false

3. Fees & Taxes definition

The definitions and common types of fees and taxes outlined below.

Fee

These are additional charges set by the hotel to cover specific services, amenities, or operational costs and are not government-mandated.


  - Resort Fee: Covers access to facilities such as pools, gyms, or Wi-Fi.

  - Service Fee: Includes staff gratuities or charges for specific services like housekeeping.

  - Early Check-in/Late Check-out Fee: Applied for non-standard arrival or departure times.

  - Cleaning Fee: Added for short-term rentals or extended stays.


Tax

These are mandatory charges collected on behalf of the government or local authorities as required by law.


  - Sales Tax: A percentage applied to room rates and services.

  - Occupancy Tax (Lodging Tax): A local tax specific to hotel stays.

  - VAT (Value-Added Tax): Common in Europe and other regions.

  - Tourism Tax: Used to fund local tourism infrastructure.

4. Charge Modes

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

RATE_PERCENT

Fees or taxes are calculated based on a percentage of the product price, including other applicable taxes or fees. 

NET_RATE_AMOUNT_PERCENT

Fees or taxes are calculated based on a percentage of the net product price. The net amount is the product price minus any included taxes or fees. For example, if the rate is $100 and includes a $5 cleaning fee, the net amount is $95.

SUMMARY_RATE_PERCENT

Fees or taxes are calculated as a percentage of the summary amount (the room rate plus applicable exclusive fees and taxes). For example, if a room is $100 with a $30 service charge and a 10.5% of the summary, the total would be calculated as: 100 + 30 + (100 + 30) * 0.105. Requires applyToTaxCodes.

TAX_ON_TAX_PERCENT

Tax is calculated as a percentage of the sum of other applicable taxes within the same product. Please note that circular dependencies involving two or more taxes are not permitted. Requires applyToTaxCodes.

FIXED

A set fee or tax amount is applied regardless of the base rate, other fees, or taxes.

5. 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).

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

  - TaxA: 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: 10 USD per room per stay

Breakdown of the fees and taxes:

- Tax1: 10 USD per room, per night.

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

- Tax2: 10 USD per room, per stay.


Calculation example:

AmountBeforeTax(ABT): $100 

AmountAfterTax(AAT): 100 + 10 + (100+10) * 10.5% + 10 = $131.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.

- ServiceCharge: 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.

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

  - TaxP3: 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 3010010N/A30(100+30)*10.5%=13.65100+30+13.65=143.65
May 110010N/A30(100+30)*10.5%=13.65143.65
May 2100N/A100*0.15=1530(100+30)*10.5%=13.65100+30+13.65=143.65
May 3100N/A100*0.15=1530(100+30)*10.5%=13.65143.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": "TaxP3",
      "description": "Additional 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
    }
  ]
}

6. Node Structure compare

Example snippets for both the old "fees" structure and the new "feeTaxes"


API v4.9.8 or lowerAPI v4.10 or higher
"fees": [
  {
    "dateRange": {
      "startDate": "2018-01-01",
      "endDate": "2018-01-04"
    },
    "fee": {
      "name": "Service Charge",
      "type": "Exclusive",
      "amount": 10,
      "amountType": "Percent",
      "chargeType": "PerRoomPerNight",
      "collectBy": "Distributor"
    }
  }
]
"feeTaxes": [
  {
    "code": "ServiceCharge",
    "description": "Service Charge",
    "dateRange": {
      "startDate": "2018-01-01",
      "endDate": "2018-01-04"
    },
    "chargeMode": "RATE_PERCENT",
    "chargeUnit": "PER_ROOM_PER_NIGHT",
    "collectBy": "Distributor",
    "chargeValue": {
      "value": 10
    },
    "inclusive": false
  }
]

7. FAQ

Q: Does GO support calculating AAT if the hotel supplier only provides ABT plus tax/fee rules? If yes, Is there any special logic or notes on tax calculation?
Yes, GO supports calculating AAT if the hotel supplier only provides ABT plus tax/fee rules.
Please keep the following notes in mind:
1. For GO Push Distributors, if the tax amount is fixed and the charge type is per room per stay or per person per stay: This kind of tax will not be calculated or summed up into AAT when GO pushes ARI to the distributor's end.
2. When calculating tax for per-person tax, the number of children will be applied to the calculation, unless the child policy specifies they are free of charge.
Q: TAX_ON_TAX_PERCENT vs. SUMMARY_RATE_PERCENT
Here is the explanation regarding the difference between TAX_ON_TAX_PERCENT and SUMMARY_RATE_PERCENT: 
TAX_ON_TAX_PERCENT: This calculation is based solely on the specific tax codes defined in "applyToTaxCodes" and does not include the base room pricing (ABT).
SUMMARY_RATE_PERCENT: If no tax is specified in "applyToTaxCodes", the calculation is based directly on the ABT. If specific tax codes are defined in "applyToTaxCodes", it is calculated based on the sum of the ABT and those specific taxes.
TAX_ON_TAX_PERCENTSUMMARY_RATE_PERCENT
{
  "feeTaxes": [
    {
      "code": "ServiceCharge",
      "description": "Service Charge",
      "chargeMode": "FIXED",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "dateRange": {
        "start": "2018-01-01",
        "end": "2018-12-31"
      },
      "chargeValue": {
        "value": 20
      },
      "inclusive": false
    },
    {
      "code": "VAT",
      "description": "VAT",
      "chargeMode": "TAX_ON_TAX_PERCENT",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "dateRange": {
        "start": "2018-01-01",
        "end": "2018-12-31"
      },
      "applyToTaxCodes": [
        "ServiceCharge"
      ],
      "chargeValue": {
        "value": 10
      },
      "inclusive": false
    }
  ]
}

{
  "feeTaxes": [
    {
      "code": "ServiceCharge",
      "description": "Service Charge",
      "chargeMode": "FIXED",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "dateRange": {
        "start": "2018-01-01",
        "end": "2018-12-31"
      },
      "chargeValue": {
        "value": 20
      },
      "inclusive": false
    },
    {
      "code": "TaxP3",
      "description": "Additional Tax",
      "chargeMode": "SUMMARY_RATE_PERCENT",
      "chargeUnit": "PER_ROOM_PER_NIGHT",
      "dateRange": {
        "start": "2018-01-01",
        "end": "2018-12-31"
      },
      "applyToTaxCodes": [
        "ServiceCharge"
      ],
      "chargeValue": {
        "value": 10
      },
      "inclusive": false
    }
  ]
}

Calculation:

ABT = $100

AAT = 100 + 20 + (20 * 0.1) = 122

Calculation:

ABT = $100

AAT = 100 + 20 + (100 + 20) * 0.1 = 132

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.