Google Checkout XML API - Defining Tax Rules

Specifying Tax Rules

Google Checkout calculates taxes based on tax rules that you include in your Checkout API request. Every tax rule must specify the geographic area(s) where the rule applies as well as the tax rate that should be charged in that area. You can specify tax rates that are different for each item in an order, and you can apply those tax rates in areas as small as a postal or zip code or as large as the world.

Each tax rule must include either the <tax-area> tag or the <tax-areas> tag, which will identify the geographic area(s) where the tax rule applies. The difference between these two tags is that the <tax-areas> tag can specify one or more geographic areas, while the <tax-area> tag can only specify one area. Please see the sample XML for applying a tax rule in multiple geographic areas for a sample usage of the <tax-areas> tag.

Checkout API requests can specify two different types of tax rules.

• Default tax rules identify tax rates that will be applied, by default, in a particular geographic area. Default tax rules may also contain an optional subtag, <shipping-taxed>, that indicates whether tax rates apply to shipping costs. Default tax rules are grouped into a default tax table, and each Checkout API request may contain one default tax table. You can override your default tax rules by specifying an alternate tax rule that should be used to calculate tax for an item.

• Alternate tax rules identify tax rates that can be applied to particular types of products. For example, in some states, manufactured goods may be taxed at one rate but extended warranties on those goods may be taxed at a different rate. In your Checkout API request, alternate tax rules are grouped into alternate tax tables. Each alternate tax table contains all of the alternate tax rules for a particular type of product or service, and a Checkout API request may contain zero or more alternate tax tables.

  Like default tax rules, alternate tax rules specify particular geographic areas where each rule applies. (Each geographic area identified in an alternate tax rule can specify its own alternate tax rate.) However, an alternate tax rule will only be used to calculate tax for an item if the Checkout API request specifies a tax-table-selector value for that item. In that case, Google Checkout will try to match the value of the tax-table-selector element to the name attribute of the alternate-tax-table elements in your shopping cart.

  For example, the following XML excerpt from a Checkout API request shows an item that specifies an alternate tax table that should be used to calculate taxes for the item.

  <item>
      <item-name>3-year warranty for 512MB PC2-5300 DDR SO-DIMM</item-name>
      <item-description>Extended warranty for PC2-5300</item-description>
      <quantity>1</quantity>
      <tax-table-selector>warranty</tax-table-selector>
      <unit-price currency="USD">79.99</unit-price>
  </item>
  

  To calculate taxes for this item, Google Checkout would use the alternate tax table in your Checkout API request that had a name of "warranty":

  <alternate-tax-table name="warranty" standalone="false"/>
  

  In some cases, an item might specify an alternate tax table, but that table will not contain an alternate tax rule for the location to which the item is being shipped. In these cases, Google Checkout will refer to the standalone attribute of the alternate-tax-table to determine how to calculate taxes. If the standalone attribute's value is true, Google Checkout will not calculate tax for the item. (The tax amount for that item will be 0.) If the standalone attribute's value is false, Google Checkout will use the default tax table to calculate taxes for the item. The default value of the standalone attribute is false.

Ordering Tax Rules in XML Requests

To select the tax rate for an item, Google Checkout selects the first default tax rule in the API request for which the tax area matches the shipping address. (If you specify a tax-table-selector for the item, Google Checkout will select the first alternate tax rule for which the tax area matches the shipping address.)

As such, your tax tables should list tax rules that apply in more specific geographic areas before rules that apply in less specific areas. For example, if a state has a 4 percent sales tax rate and a zip code in that state has an 8 percent sales tax rate, you should list the tax rule for the zip code before the tax rule for the state.

The following XML excerpt demonstrates this principle. The excerpt is from an order being shipped to the 10022 zip code, which is in New York City. The sales tax rate in New York City is 8.375 percent whereas the New York state sales tax is 4 percent. Note that the tax rule for New York City zip codes is listed before the tax rule for the state of New York. In this example, both tax rules match a shipping address in the 10022 zip code, but Google Checkout will select the first matching tax rate, which is the rule with a zip code pattern of "100*" and a rate of 8.375% (0.08375).

        <tax-tables>
          <default-tax-table>
            <tax-rules>

              <default-tax-rule>
                <shipping-taxed>false</shipping-taxed>
                <rate>0.08375</rate>
                <tax-area>
                  <us-zip-area>
                    <zip-pattern>100*</zip-pattern>
                  </us-zip-area>
                </tax-area>
              </default-tax-rule>

              <default-tax-rule>
                <shipping-taxed>true</shipping-taxed>
                <rate>0.0400</rate>
                <tax-area>
                  <us-state-area>
                    <state>NY</state>
                  </us-state-area>
                </tax-area>
              </default-tax-rule>

            </tax-rules>
          </default-tax-table>
        </tax-tables>

Note: This excerpt does not include all zip codes for New York City or all applicable tax rates for shipping addresses in New York.

Country-Specific Rounding Rules

For all financial calculations, Google Checkout uses a default rounding policy that is selected based on the merchant's home country. You can change the default rounding policy by adding the <rounding-policy> tag and its subtags, <mode> and <rule>, to your Checkout API request. The Google Checkout Rounding Policy document explains how to change the rounding policy used to calculate totals for an order.

• For U.S. merchants, Google Checkout uses banker's rounding as its default policy. Banker's rounding is the same as the traditional method of rounding numbers with one exception. In banker's rounding, if the number to be rounded is followed by a five and no additional nonzero digits, the number is rounded to the nearest even number. The following examples demonstrate the expected behavior in banker's rounding:

  • 12.435 would be rounded up to 12.44. The number to be rounded (3) is rounded to the nearest even digit (4).
  • 12.445 would be rounded down to 12.44. The number to be rounded (4) is not rounded because it is an even digit.
  • 12.44501 would be rounded up to 12.45. The number to be rounded (4) is followed by a five and by additional nonzero digits.

  For U.S. merchants, Google calculates the total amount of tax for all of the items in an order and then uses banker's rounding to round that amount to two decimal places.

• For U.K. merchants, Google Checkout uses the HALF_UP rounding mode. For this rounding mode, if the number being rounded is followed by a five and no additional nonzero digits, then that number is rounded up. All other numbers are rounded to the nearest digit. The following examples demonstrate the expected behavior for HALF_UP rounding:

  • 12.434 would be rounded down to 12.43.
  • 12.435 would be rounded up to 12.44.
  • 12.445 would be rounded up to 12.45.
  • 12.456 would be rounded up to 12.46.

  For U.K. merchants, Google calculates tax for each item in the order and then uses HALF_UP rounding for each calculated amount.

XML Examples for Tax Tables

This section contains a number of XML examples that demonstrate different ways of defining default tax tables and alternate tax tables. You can click the Checkout button below each example to see how the tax tables affect the buyer experience. The examples are for a fictional merchant and link to the Sandbox testing environment.

Adding the following shipping addresses to your Sandbox account will help you to test the buyer experience for the examples:

• Name: John Maryland; Address: 15 Maryland Way, Bethesda MD 20810
• Name: Jim Connecticut; Address 15 Whaler Court, Hartford CT 06126
• Name: Dave New York City; Address: 15 York St., New York NY 10022
• Name: Sally Upstate-NY; Address: 15 Saranac Ave., Saranac NY 12981
• Name: Geoffrey England; Address: 15 London Rd., London SW1W 9QT

Please note that the following examples do not contain complete Checkout API requests:

Example 1: Charging a single tax rate in one state

The following example explains how to charge a single tax rate in one state. The example is for a merchant in Connecticut, where there is a 6 percent sales tax. The example contains a single tax rule. In addition, since shipping charges in Connecticut are taxed, the <shipping-taxed> tag is included in this request with a value of true. (If shipping charges are not subject to tax in a state where you charge tax, you can omit the <shipping-taxed> tag from the tax rule for that state or set the tag's value to false.)

        <tax-tables>
          <default-tax-table>
            <tax-rules>

              <default-tax-rule>
                <shipping-taxed>true</shipping-taxed>
                <rate>0.0600</rate>
                <tax-area>
                  <us-state-area>
                    <state>CT</state>
                  </us-state-area>
                </tax-area>
              </default-tax-rule>

            </tax-rules>
          </default-tax-table>
        </tax-tables>

Example 2: Charging tax in two non-overlapping geographic areas

The following example demonstrates how to create tax tables if you charge tax in more than one geographic area. In this example, the two areas are Connecticut and Maryland. Since the areas do not overlap – a shipping address can only be associated with one state – the tax rules can be specified in any order. As in the previous example, shipping charges in Connecticut are taxed; however, shipping charges in Maryland are not subject to tax.

        <tax-tables>
          <default-tax-table>
            <tax-rules>

              <default-tax-rule>
                <shipping-taxed>true</shipping-taxed>
                <rate>0.0600</rate>
                <tax-area>
                  <us-state-area>
                    <state>CT</state>
                  </us-state-area>
                </tax-area>
              </default-tax-rule>

              <default-tax-rule>
                <rate>0.0500</rate>
                <tax-area>
                  <us-state-area>
                    <state>MD</state>
                  </us-state-area>
                </tax-area>
              </default-tax-rule>

            </tax-rules>
          </default-tax-table>
        </tax-tables>

Example 3: Charging tax in two overlapping geographic areas

The following example also demonstrates how to create tax tables if you charge tax in more than one geographic area. However, in this example, the two areas are in the same state.

• The first area defines a set of zip codes in Manhattan, where there is an 8.375 percent sales tax.
• The second area defines a rule for charging 4 percent sales tax in the state of New York.

Since Google will select the first tax rule that matches the shipping address for the order, the tax rule that defines the narrower geographic area must be listed first. (See the Ordering Tax Rules in XML Requests section for more information.)

        <tax-tables>
          <default-tax-table>
            <tax-rules>

              <default-tax-rule>
                <shipping-taxed>false</shipping-taxed>
                <rate>0.08375</rate>
                <tax-area>
                  <us-zip-area>
                    <zip-pattern>100*</zip-pattern>
                  </us-zip-area>
                </tax-area>
              </default-tax-rule>

              <default-tax-rule>
                <shipping-taxed>true</shipping-taxed>
                <rate>0.0400</rate>
                <tax-area>
                  <us-state-area>
                    <state>NY</state>
                  </us-state-area>
                </tax-area>
              </default-tax-rule>

            </tax-rules>
          </default-tax-table>
        </tax-tables>

Example 4: Providing default tax tables for merchant-calculated shipping

The example below demonstrates how to indicate that you will calculate taxes for an order. This example includes almost the same XML sample as that shown in example 1. However, this example contains two key differences to enable the merchant to calculate taxes:

• The merchant-calculated attribute of the <tax-tables> tag is set to true.

• The <merchant-calculations-url> tag is included in this request and specifies the URL to which Google will send a merchant calculation callback request. The value of the tag must be the URL for your web service that performs custom calculations. Learn more about the Merchant Calculations API.

    <checkout-flow-support>
      <merchant-checkout-flow-support>
        <merchant-calculations>
          <merchant-calculations-url>http://www.example.com/calculate</merchant-calculations-url>
        </merchant-calculations>
        <tax-tables merchant-calculated="true">
          <default-tax-table>
            <tax-rules>

              <default-tax-rule>
                <shipping-taxed>true</shipping-taxed>
                <rate>0.0600</rate>
                <tax-area>
                  <us-state-area>
                    <state>CT</state>
                  </us-state-area>
                </tax-area>
              </default-tax-rule>

            </tax-rules>
          </default-tax-table>
        </tax-tables>
      </merchant-checkout-flow-support>
    </checkout-flow-support>

Example 5: Alternate tax rules

This example shows how to create an alternate tax table for an item that is tax-exempt. The tax tables in this example indicate that the merchant charges sales tax in Connecticut and Maryland. In Connecticut, sales of bicycle helmets are tax-exempt. (Google does not return any search results indicating that bicycle helmet sales are also tax-exempt in Maryland.)

In this example, the XML contains an alternate tax table for bicycle helmets. That tax table contains one alternate tax rule, which indicates that Connecticut does not charge tax for items associated with that tax table. Please note that value of the <alternate-tax-table> tag's standalone attribute is set to false, which is that element's default value. As a result, if an item specifies the "bicycle helmets" tax table, and there is no alternate tax rule for the shipping address, Google will use the default tax table to calculate tax for the item. Therefore, if the item is shipped to Connecticut, no tax will be charged. However, if the item is shipped to Maryland, the regular tax rate will be assessed.

    <shopping-cart>
      <items>
        <item>
          <item-name>Bike Helmet</item-name>
          <item-description>Black helmet that is tax-exempt in CT but not MD.</item-description>
          <unit-price currency="USD">49.99</unit-price>
          <quantity>1</quantity>
          <tax-table-selector>bicycle_helmets</tax-table-selector>
        </item>
      </items>
    </shopping-cart>
    <checkout-flow-support>
      <merchant-checkout-flow-support>
        <tax-tables>
          <default-tax-table>
            <tax-rules>

              <default-tax-rule>
                <shipping-taxed>true</shipping-taxed>
                <rate>0.0600</rate>
                <tax-area>
                  <us-state-area>
                    <state>CT</state>
                  </us-state-area>
                </tax-area>
              </default-tax-rule>

              <default-tax-rule>
                <rate>0.0500</rate>
                <tax-area>
                  <us-state-area>
                    <state>MD</state>
                  </us-state-area>
                </tax-area>
              </default-tax-rule>

            </tax-rules>
          </default-tax-table>

          <alternate-tax-tables>
            <alternate-tax-table standalone="false" name="bicycle_helmets">
              <alternate-tax-rules>
                <alternate-tax-rule>
                  <rate>0</rate>
                  <tax-area>
                    <us-state-area>
                      <state>CT</state>
                    </us-state-area>
                  </tax-area>
                </alternate-tax-rule>
              </alternate-tax-rules>
            </alternate-tax-table>
          </alternate-tax-tables>

        </tax-tables>
      </merchant-checkout-flow-support>
    </checkout-flow-support>

Example 6: Alternate tax rules for items that are always tax-exempt

This example shows how to identify an item that is always tax-exempt, regardless of the shipping address. The tax tables indicate that the merchant charges sales tax in Connecticut and Maryland, and sales of nonprescription drugs are tax-exempt in both states. In this example, the XML contains an alternate tax table for tax-exempt goods, and that tax table does not specify any alternate tax rules. However, since the value of the <alternate-tax-table> tag's standalone attribute is set to true, Google will not calculate taxes for an item if it specifies the tax-exempt tax table and there is no alternate tax rule for the shipping address. Since the item in the example is always tax-exempt for this merchant, the tax table does not need to specify any tax rules.

    <shopping-cart>
      <items>
        <item>
          <item-name>Tylenol Caplets</item-name>
          <item-description>Fast relief without a prescription.</item-description>
          <unit-price currency="USD">7.99</unit-price>
          <quantity>1</quantity>
          <tax-table-selector>tax_exempt</tax-table-selector>
        </item>
      </items>
    </shopping-cart>
    <checkout-flow-support>
      <merchant-checkout-flow-support>
        <tax-tables>
          <default-tax-table>
            <tax-rules>

              <default-tax-rule>
                <shipping-taxed>true</shipping-taxed>
                <rate>0.0600</rate>
                <tax-area>
                  <us-state-area>
                    <state>CT</state>
                  </us-state-area>
                </tax-area>
              </default-tax-rule>

              <default-tax-rule>
                <rate>0.0500</rate>
                <tax-area>
                  <us-state-area>
                    <state>MD</state>
                  </us-state-area>
                </tax-area>
              </default-tax-rule>

            </tax-rules>
          </default-tax-table>

          <alternate-tax-tables>
            <alternate-tax-table standalone="true" name="tax_exempt">
              <alternate-tax-rules/>
            </alternate-tax-table>
          </alternate-tax-tables>
        </tax-tables>
      </merchant-checkout-flow-support>
    </checkout-flow-support>

Example 7: Applying a tax rule in multiple geographic areas

This example demonstrates how to use the <tax-areas> tag to apply a tax rule in multiple geographic areas. This example applies the same tax rule in multiple European countries. The same principle could be used to apply a tax rule in multiple U.S. states or zip code ranges.

        <tax-tables>
          <default-tax-table>
            <tax-rules>

              <default-tax-rule>
                <shipping-taxed>true</shipping-taxed>
                <rate>0.175</rate>
                <tax-areas>
                  <postal-area>
                    <country-code>DE</country-code>
                  </postal-area>
                  <postal-area>
                    <country-code>ES</country-code>
                  </postal-area>
                  <postal-area>
                    <country-code>GB</country-code>
                  </postal-area>
                </tax-areas>
              </default-tax-rule>

            </tax-rules>
          </default-tax-table>
        </tax-tables>

Example 8: Alternate tax tables for U.K. merchants

This example shows a common way to structure tax tables in the United Kingdom. The order includes three items. The first item uses the default tax rate of 17.5 percent, the second item uses a reduced tax rate of 5 percent, and the third item is untaxed. Note that the cost of each item is £10.00. When you click the Checkout button for this order, Google Checkout displays the price for each item inclusive of tax.

    <shopping-cart>
      <items>
        <item>
          <item-name>Regular Test Item</item-name>
          <item-description>Regular Test Item</item-description>
          <unit-price currency="GBP">10.0</unit-price>
          <quantity>1</quantity>
        </item>
        <item>
          <item-name>Reduced Test Item</item-name>
          <item-description>Reduced Test Item</item-description>
          <unit-price currency="GBP">10.0</unit-price>
          <quantity>1</quantity>
          <tax-table-selector>reduced</tax-table-selector>
        </item>
        <item>
          <item-name>Zero Test Item</item-name>
          <item-description>Zero Test Item</item-description>
          <unit-price currency="GBP">10.0</unit-price>
          <quantity>1</quantity>
          <tax-table-selector>tax_exempt</tax-table-selector>
        </item>
      </items>
    </shopping-cart>
    <checkout-flow-support>
      <merchant-checkout-flow-support>
        <tax-tables>
          <default-tax-table>
            <tax-rules>

              <default-tax-rule>
                <shipping-taxed>true</shipping-taxed>
                <rate>0.175</rate>
                <tax-area>
                  <world-area/>
                </tax-area>
              </default-tax-rule>

            </tax-rules>
          </default-tax-table>

          <alternate-tax-tables>
            <alternate-tax-table name="reduced" standalone="true">
              <alternate-tax-rules>
                <alternate-tax-rule>
                  <rate>0.05</rate>
                  <tax-area>
                    <world-area/>
                  </tax-area>
                </alternate-tax-rule>
              </alternate-tax-rules>
            </alternate-tax-table>

            <alternate-tax-table standalone="true" name="tax_exempt">
              <alternate-tax-rules/>
            </alternate-tax-table>
          </alternate-tax-tables>

        </tax-tables>
      </merchant-checkout-flow-support>
    </checkout-flow-support>

XML Tag Definitions

Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are: