Supplier Knowledge Base

TABLE OF CONTENTS

1. Overview
2. Fee & Tax Field Reference
2. Fees & Taxes definition
3. Charge Modes
4. Sample Payloads
5. FAQ

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.

2. Fee & Tax Field Reference

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

Field	Type	Required	Description	Example
feeTaxes	array	No	Starting with API Version v4.10, DS GO will use the new 'feeTaxes' node instead of the 'fees' node.
@code	string	Yes	Represents 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.	VAT
@description	string	No	Text description of the fee or tax	value added tax
dateRange	object	Yes	Effective period for this rule
@startDate	string	Yes	The start date of the date range,it's formatted as yyyy-MM-dd.	2018-01-01
@endDate	string	Yes	The end date of the date range,it's formatted as yyyy-MM-dd.	2018-01-04
chargeMode	enum	Yes	Enum:[TAX_ON_TAX_PERCENT, RATE_PERCENT, SUMMARY_RATE_PERCENT, NET_RATE_AMOUNT_PERCENT, FIXED]	RATE_PERCENT
chargeUnit	enum	Yes	Enum: [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
collectBy	enum	No	Enum: [ 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
currency	string	No	ISO 4217 currency code.	USD
applyToTaxCodes	array	No	Notes: 1. This field is required and will not be empty when chargeMode is TAX_ON_TAX_PERCENT or SUMMARY_RATE_PERCENT. 2. The listed code values must not form any circular dependencies.	["VAT"]
chargeValue	object	Yes	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.
value	number	No	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
tierValue	object	No	Supporting soon
inclusive	boolean	Yes	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

2. 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.

3. 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. Default value.

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% tax, the total would be calculated as: 100 + 30 + (100 + 30) * 0.105.

Requires applyToTaxCodes,chargeValue.value

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.

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:

Date	ABT	TaxP1(10 USD)	TaxP2(15%)	ServiceCharge(30 USD)	TaxP3	AAT
April 30	100	10	N/A	30	(100+30)*10.5%=13.65	100+30+13.65=143.65
May 1	100	10	N/A	30	13.65	143.65
May 2	100	N/A	100*0.15=15	30	(100+30)*10.5%=13.65	100+30+13.65=143.65
May 3	100	N/A	100*0.15=15	30	13.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.

Fee & Tax Rules

1. Overview

2. Fee & Tax Field Reference

2. Fees & Taxes definition

3. Charge Modes

4. Sample Payloads

5. FAQ