Tax and Fee Message

Overview

The TaxFeeInfo message defines the taxes and fees that are applicable to a user when booking a property and based on the property's tax regulations outlined on the website. To add tax and fee data, you use the Rate message (OTA_HotelRateAmountNotifRQ).

Note: The TaxFeeinfo message type is recommended, and it isn't required if AmountAfterTax is specified in the Rate message.

The only supported action for this message is overlay which is used to replace the tax and fee data for each property. It's important to send tax and fee updates whenever there are changes.

Key Point: You must include all taxes and fees that a user must pay (VAT, stay tax, city tax, etc.), even if it's not paid at booking time, or not paid directly to the property.

Methods to add taxes and fees

There are two general ways to add taxes and fees:

In the first method, you specify AmountAfterTax in the Rate message; you add the taxes and fees by sending rate messages that contain both the base nightly rates (exclusive of all taxes and fees) and the total nightly rates (inclusive of all taxes and fees). Because these rates are nightly, this approach only works for percentage-based taxes and fees or flat amounts that are nightly, and per-stay taxes and fees can't be used.

The second (preferred) method is to only send tax and fee-exclusive base nightly rates in the rate messages, and use TaxFeeInfo to convey taxes and fees at a property level. The individual taxes and fees can still be scoped to specific room types and rate plans, that are applicable to certain date ranges.

Key Point: There is s limit of 300 taxes and fees per property. You can use TaxFeeInfo message to remove taxes and fees from a property.

This page describes and refers only to the preferred method of using TaxFeeInfo and not the method of specifying AmountAfterTax in the Rate message (OTA_HotelRateAmountNotifRQ).

Methods to set taxes

You have the following options to set taxes:

• Basis = [room|person]
• Period = [stay|night]
• Type = [percent|amount]

When Period is stay and Type is percent, Google applies taxes and fees for the entire stay even if a single date in the itinerary overlaps with the StayDates range. You can't specify applying a tax and fee only if ALL dates in the itinerary overlap with the stay-dates date-range.

For examples of various tax-related scenarios, see How-tos. The examples cover some of the top tax scenarios, including How-tos for:

• Percentage tax
• Flat tax applied per property
• Percentage tax applied only to nights after the first night
• Method to replace old with new taxes
• Include or exclude taxes for countries
• Set slab tax with brackets
• Set tax and taxable fee

The following sections cover general guidelines, a basic example, and how-to scenarios to get you started with adding and updating your tax information.

Required and optional elements

The XML reference provides descriptions of the required and optional elements. For details on attributes and child elements, see TaxFeeInfo Elements & Attributes.

Syntax and schemas

Use the TaxFeeInfo Syntax example as a reference when you create the message to ensure you are following the correct format. You can use a third-party XML tool such as xmllint to validate your feeds with the published schemas before submitting them to Google. For the TaxFeeinfo message schema, see Hotel ads schemas.

Guidelines

This section covers the common guidelines and special instructions for setting taxes and fees.

Actions

Overlay

Use the overlay action to replace all of the taxes for a property. The overlay action is the default and the only action that is supported. Any previous taxes and fees for this property will be cleared once this update is applied.

General

• Each Tax is evaluated and, if applicable, computed based on the AmountBeforeTax amount that was specified in BaseByGuestAmt.

• After all applicable taxes and fees are computed, they are added to the base price to form the total price.

• Syntax for <Tax> and <Fee> are the same.

• Taxes and fees can have constraints, such as:

  • Only applies to specific room types and rate plans.
  • Only applies to specific stay dates.

  These constraints are optional and you don't have to set every type of constraint; you can leave these empty if it's applicable to all.

• Send a TaxFeeInfo update whenever there's a change to taxes or fees.

Example

This section provides a basic example of a TaxFeeInfo message using required and optional elements. Once you prepare your file, you will need to send it to Google using a POST message to this endpoint:

https://www.google.com/travel/hotels/uploads/taxes

To learn more about how to push/POST the message, see Pushing messages.

Key Point: Send Google an updated TaxFeeInfo message every time your taxes and fees change.

For the hotel_id attribute, use the unique Hotel ID you used within your system for identifying the property. This value must match the Hotel ID specified using <id> in the <listing> element in the Hotel List feed. Consistency with your system is critical for ensuring that Google is correctly displaying your data.

This example shows how to set a 10% tax percentage and $50 fee amount for a property for the total stay (not per night):

<?xml version="1.0" encoding="UTF-8"?>
<TaxFeeInfo timestamp="2022-08-20T16:20:00-04:00"
            partner="partner_key"
            id="12345678">
  <Property>
    <ID>HOTELID</ID>
    <Taxes>
      <Tax>
        <Type>percent</Type>
        <Basis>room</Basis>
        <Period>stay</Period>
        <Amount>10</Amount>
      </Tax>
    </Taxes>
    <Fees>
      <Fee>
        <Type>amount</Type>
        <Basis>room</Basis>
        <Period>stay</Period>
        <Amount>50</Amount>
        <Currency>USD</Currency>
      </Fee>
    </Fees>
  </Property>
</TaxFeeInfo>

Note: If <Currency> isn't specified but the <Amount> is specified then the <Currency> value defaults to base rate currency.

For examples of adding age-related taxes and other examples, see Tax examples.

How-tos

This section provides solutions to scenarios you might encounter while setting taxes and fees.

Scenario 1: How to add a flat tax

This tax example shows how to set a flat tax per property.

Description

You want to apply a flat tax for the room or stay per property rather than a percentage tax.

Solution

Use amount rather than percentage to add the flat tax option.

Sample

This sample shows how to add a flat tax by using amount rather than percentage:

<?xml version="1.0" encoding="UTF-8"?>
<TaxFeeInfo timestamp="2022-08-16T16:20:00-04:00"
            id="12345678"
            partner="partner_key">
  <Property>
    <ID>Property_1</ID>
    <Taxes>
      <Tax>
        <Type>amount</Type>
        <Basis>room</Basis>
        <Period>stay</Period>
        <Amount>30</Amount>
      </Tax>
    </Taxes>
  </Property>
</TaxFeeInfo>

Scenario 2: How to target taxes using ApplicableNights

Description

You want to apply a flat fee tax only to nights after the first night. For example, there is a mandatory fee for daily use of a certain amenity that is excluded from the first night, where the guest(s) wouldn't have had the chance to use that particular amenity.

Solution

Use <ApplicableNights excluded="1"/> to control which nights have taxes applied.

Sample

This sample shows how to use ApplicableNights:

<?xml version="1.0" encoding="UTF-8"?>
<TaxFeeInfo timestamp="2022-08-16T16:20:00-04:00"
            id="12345678"
            partner="partner_key">
  <Property>
    <ID>Property_1</ID>
    <Taxes>
      <Tax>
        <Type>amount</Type>
        <Basis>room</Basis>
        <Period>night</Period>
        <Amount>50</Amount>
        <ApplicableNights excluded="1"/>
      </Tax>
    </Taxes>
  </Property>
</TaxFeeInfo>

Scenario 3: How to replace old with new taxes and fees

Description

The current taxes and fees have changed and need to be replaced with new ones.

Solution

Use the overlay action to remove all of the existing taxes and fees.

Note: The overlay action is the default action if unspecified meaning it's only possible to replace all taxes and fees for each property and you can't incrementally add new taxes/fees.

Sample

The following sample shows how to remove all taxes and fees for a property:

    <?xml version="1.0" encoding="UTF-8"?>
    <TaxFeeInfo timestamp="2022-08-16T16:20:00-04:00"
                id="12345678"
                partner="partner_key">
      <Property action="overlay">
        <ID>Property_1</ID>
      </Property>
    </TaxFeeInfo>

Scenario 4: How to include or exclude taxes for countries

Description

You need to include the tax for certain countries while excluding the tax from another. For example, you need to exclude taxes for a smaller confederation with non-EU taxes while taxing all other countries.

Solution

Use the include or exclude options for UserCountries type. Use include to apply the tax only to the country listed or use exclude to apply the tax to all countries except the one listed.

Sample

The following sample shows how to set taxes for users outside of the hotel country (Israel):

<?xml version="1.0" encoding="UTF-8"?>
<TaxFeeInfo timestamp="2022-08-16T16:20:00-04:00"
            id="12345678"
            partner="partner_key">
  <Property>
    <ID>Property_1</ID>
    <Taxes>
      <Tax>
        <Type>percent</Type>
        <Basis>room</Basis>
        <Period>night</Period>
        <UserCountries type="exclude">
          <Country code="IL"/>
        </UserCountries>
      </Tax>
    </Taxes>
  </Property>
</TaxFeeInfo>

Scenario 5: How to set slab tax with brackets

Description

You want to add a GST slab tax applied based on nightly rates.

Note: For this scenario, use the Brackets (set of non-overlapping tax brackets) to set this option.

Solution

For this scenario, suppose the target country's GST tax brackets are:

• No tax if the nightly rate is less than or equal to 1000.
• 12% tax if the nightly rate is greater than 1000 and less than or equal to 7500.
• 18% tax if the nightly rate is greater than 7500.

Sample

The following sample shows how to set a slab tax with brackets:

<?xml version="1.0" encoding="UTF-8"?>
<TaxFeeInfo timestamp="2022-08-28T16:20:00-04:00"
            id="12345678"
            partner="partner_key">
  <Property>
    <ID>Property_1</ID>
    <Taxes>
      <Tax>
        <Type>percent</Type>
        <Basis>room</Basis>
        <Period>night</Period>
        <Brackets base_amount="0">
          <Bracket starts_at="1000.01" amount="12"/>
          <Bracket starts_at="7500.01" amount="18"/>
        </Brackets>
      </Tax>
    </Taxes>
  </Property>
</TaxFeeInfo>

Scenario 6: How to set tax and taxable fee

Description

You want to add a tax such as VAT, and another service fee which is also applicable to that tax.

Solution

This scenario considers two example use cases of taxable fees:

• Both the tax and the taxable fee are defined as percentage charges.
• The tax is a percentage charge, while the taxable fee is a flat amount per stay.

Examples

Taxable fee as percent

This example has an AmountBeforeTax of $100, a GST tax of 18%, and an additional 5% service charge—making the total taxable fee percentage of 5.9% (5*1.18), and the total rate amount of $123.90 [= $118 (18% GST) + $5.9 (5.9% service charge)].

The following snippet defines the tax (GST) and taxable fee (service charge) as percentages:

<TaxFeeInfo timestamp="2022-08-16T16:20:00-04:00"
  id="12345678"
  partner="partner_key">
  <Property>
    <ID>Property_1</ID>
    <Taxes>
      <Tax>
        <Type>percent</Type>
        <Basis>room</Basis>
        <Period>stay</Period>
        <Amount>18</Amount>
      </Tax>
    </Taxes>
    <Fees>
      <Fee>
        <Type>percent</Type>
        <Basis>room</Basis>
        <Period>stay</Period>
        <Amount>5.9</Amount>
      </Fee>
    </Fees>
  </Property>
</TaxFeeInfo>

Taxable fee as amount

This example has an AmountBeforeTax of $100, a GST tax of 18%, and an additional $20 flat rate fee—making the total taxable fee of $23.60 ($20*1.18), and the total rate amount of $141.60 [= $118 (18% GST) + $23.60 ($20 flat rate)].

The following snippet defines the tax (GST) in percentage and taxable fee (service charge) as a flat rate amount:

<TaxFeeInfo timestamp="2022-08-16T16:20:00-04:00"
  id="12345678"
  partner="partner_key">
  <Property>
    <ID>Property_1</ID>
    <Taxes>
      <Tax>
        <Type>percent</Type>
        <Basis>room</Basis>
        <Period>stay</Period>
        <Amount>18</Amount>
      </Tax>
    </Taxes>
    <Fees>
      <Fee>
        <Type>amount</Type>
        <Basis>room</Basis>
        <Period>stay</Period>
        <Amount>23.6</Amount>
      </Fee>
    </Fees>
  </Property>
</TaxFeeInfo>