Google Checkout HTML 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.

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 element 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 names of the alternate tax tables in your shopping cart.

  For example, the following HTML 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.

  <input type="hidden" name="item_name_2"
    value="Three-year extended warranty for 512MB PC2-5300 DDR SO-DIMM"/>
  
  <input type="hidden" name="item_description_2"
    value="Extended warranty for PC2-5300"/>
  
  <input type="hidden" name="item_quantity_2" value="1"/>
  
  <input type="hidden" name="item_price_2" value="29.99"/>
  
  <input type="hidden" name="item_currency_2" value="USD"/>
  
  <input type="hidden" name="shopping-cart.items.item-2.tax-table-selector"
    value="warranty"/>
  

  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":

  <input type="hidden"
    name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-#.name"
    value="warranty"/>
  

  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 parameter value for that tax table to determine how to calculate taxes. If the standalone parameter value is true, Google Checkout will not calculate tax for the item. (The tax amount for that item will be 0.) If the standalone parameter value is false, Google Checkout will use the default tax table to calculate taxes for the item. The default value of the standalone parameter is false.

Ordering Tax Rules in HTML 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 order 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 order the tax rule for the zip code before the tax rule for the state.

The following HTML 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).

Note: Google Checkout determines the order for tax rules (or alternate tax rules) based on the numeric identifier attached to the "default-tax-rule" or "alternate-tax-rule" portion of the input parameter name. In the example below, parameter names for the tax rule associated with the zip codes contain the string default-tax-rule-1, and parameter names for the tax rule associated with the state of New York contain the string default-tax-rule-2.

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.shipping-taxed"
  value="false"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.rate"
  value="0.08375"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.tax-areas.us-zip-area-1.zip-pattern"
  value="100*"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.shipping-taxed"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.rate"
  value="0.0400"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.tax-areas.us-state-area-1.state"
  value="NY"/>

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 mode and rule parameters 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.

HTML Examples for Tax Tables

This section contains a number of HTML 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 parameter 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 parameter from the tax rule for that state or set the parameter's value to false.)

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.shipping-taxed"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.rate"
  value="0.0600"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.tax-areas.us-state-area-1.state"
  value="CT"/>

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.

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.shipping-taxed"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.rate"
  value="0.0600"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.tax-areas.us-state-area-1.state"
  value="CT"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.shipping-taxed"
  value="false"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.rate"
  value="0.0500"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.tax-areas.us-state-area-2.state"
  value="MD"/>

Example 3: Charging tax in two overlapping geographic areas

The following example also demonstrates how to specify 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 ordered first. (See the Ordering Tax Rules in HTML Requests section for more information.)

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.shipping-taxed"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.rate"
  value="0.08375"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.tax-areas.us-zip-area-1.zip-pattern"
  value="100*"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.shipping-taxed"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.rate"
  value="0.0400"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.tax-areas.us-state-area-1.state"
  value="NY"/>

Example 4: Alternate tax rules

This example shows how to specify 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 HTML 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 standalone parameter 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.

<input type="hidden" name="item_name_1" value="Bike Helmet"/>

<input type="hidden" name="item_description_1"
  value="Black helmet that is tax-exempt in CT but not MD."/>

<input type="hidden" name="item_quantity_1" value="1"/>

<input type="hidden" name="item_price_1" value="49.99"/>

<input type="hidden" name="item_currency_1" value="USD"/>

<input type="hidden" name="shopping-cart.items.item-1.tax-table-selector"
  value="bicycle_helmets"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.shipping-taxed"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.rate"
  value="0.0600"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.tax-areas.us-state-area-1.state"
  value="CT"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.shipping-taxed"
  value="false"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.rate"
  value="0.0500"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.tax-areas.us-state-area-2.state"
  value="MD"/>


<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.name"
  value="bicycle_helmets"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.standalone"
  value="false"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.alternate-tax-rules.alternate-tax-rule-1.rate"
  value="0.00"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.alternate-tax-rules.alternate-tax-rule-1.tax-areas.us-state-area-1.state"
  value="CT"/>

Example 5: 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 HTML 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 standalone parameter 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.

<input type="hidden" name="item_name_1" value="Tylenol Caplets"/>

<input type="hidden" name="item_description_1"
  value="Fast relief without a prescription."/>

<input type="hidden" name="item_quantity_1" value="1"/>

<input type="hidden" name="item_price_1" value="79.99"/>

<input type="hidden" name="item_currency_1" value="USD"/>

<input type="hidden" name="shopping-cart.items.item-1.tax-table-selector"
  value="tax_exempt"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.shipping-taxed"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.rate"
  value="0.0600"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.tax-areas.us-state-area-1.state"
  value="CT"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.shipping-taxed"
  value="false"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.rate"
  value="0.0500"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-2.tax-areas.us-state-area-2.state"
  value="MD"/>


<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.name"
  value="tax_exempt"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.standalone"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.alternate-tax-rules.alternate-tax-rule-1.rate"
  value="0.00"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.alternate-tax-rules.alternate-tax-rule-1.tax-areas.world-area-1"
  value=""/>

Example 6: Applying a tax rule in multiple geographic areas

This example demonstrates how 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.

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.shipping-taxed"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.rate"
  value="0.175"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.tax-areas.postal-area-1.country-code"
  value="DE"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.tax-areas.postal-area-2.country-code"
  value="ES"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.tax-areas.postal-area-3.country-code"
  value="GB"/>

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

<input type="hidden" name="item_name_1" value="Regular Test Item"/>

<input type="hidden" name="item_description_1"
  value="This item is taxed at the standard rate."/>

<input type="hidden" name="item_quantity_1" value="1"/>

<input type="hidden" name="item_price_1" value="10.00"/>

<input type="hidden" name="item_currency_1" value="GBP"/>

<input type="hidden" name="item_name_2" value="Reduced Tax Test Item"/>

<input type="hidden" name="item_description_2"
  value="This item is taxed at a reduced rate."/>

<input type="hidden" name="item_quantity_2" value="1"/>

<input type="hidden" name="item_price_2" value="10.00"/>

<input type="hidden" name="item_currency_2" value="GBP"/>

<input type="hidden" name="shopping-cart.items.item-2.tax-table-selector"
  value="reduced"/>

<input type="hidden" name="item_name_3" value="Zero Tax Test Item"/>

<input type="hidden" name="item_description_3"
  value="This item is tax exempt."/>

<input type="hidden" name="item_quantity_3" value="1"/>

<input type="hidden" name="item_price_3" value="10.00"/>

<input type="hidden" name="item_currency_3" value="GBP"/>

<input type="hidden" name="shopping-cart.items.item-3.tax-table-selector"
  value="tax_exempt"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.shipping-taxed"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.rate"
  value="0.175"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.tax-rules.default-tax-rule-1.tax-areas.world-area-1"
  value=""/>



<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.name"
  value="reduced"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.standalone"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.alternate-tax-rules.alternate-tax-rule-1.rate"
  value="0.5"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-1.alternate-tax-rules.alternate-tax-rule-1.tax-areas.world-area-1"
  value=""/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-2.name"
  value="tax_exempt"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-2.standalone"
  value="true"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-2.alternate-tax-rules.alternate-tax-rule-1.rate"
  value="0.00"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-2.alternate-tax-rules.alternate-tax-rule-1.tax-areas.world-area-1"
  value=""/>

HTML Parameter Definitions