Implementing the Merchant Calculations XML API

Note: This is the latest documentation. The previous version of this page is identical — only the left nav differs.

Overview

The Merchant Calculations API enables you to use your own business logic to compute order totals using information that is not known when you post a Checkout API request. You can use this API to compute taxes, shipping costs, and price adjustments from coupons or gift certificates. To use this API, you must build and operate a fast, highly reliable web service that calculates these values.

The following sections explain how the Merchant Calculations API works:

Specifying that You Will Perform Custom Calculations

To perform custom calculations for an order before your customer confirms a purchase, you must include the <merchant-calculations-url> tag in your Checkout API request. The <merchant-calculations-url> tag's value is the URL to which Google Checkout will send requests for merchant calculations.

There are then several ways to instruct Google Checkout to send a request to your merchant calculations web service. You should use any methods that correspond to calculations that you intend to perform.

Shipping

To indicate that you will calculate shipping costs for an order, include one or more merchant-calculated shipping methods in your Checkout API request. You must specify a unique name and a default shipping cost for each shipping option. Google will only use the default shipping cost if the merchant calculation callback request, which asks your web service to calculate shipping costs, fails for any reason.

You can also use address filters and shipping restrictions to specify whether a merchant-calculated shipping method is available in a specific geographic region. The example below shows two merchant-calculated shipping methods. The first method uses address filters to indicate that the shipping method is never available for shipping addresses in Alaska. The first shipping method also specifies that it will not be available for shipping addresses in Hawaii if the merchant calculation callback request fails. The second shipping method is available for all addresses.

<shipping-methods>
    <merchant-calculated-shipping name="FedEx Overnight Shipping">
        <price currency="USD">19.00</price>
        <address-filters>
          <excluded-areas>
            <us-state-area>
              <state>AK</state>
            </us-state-area>
          </excluded-areas>
        </address-filters>
        <shipping-restrictions>
          <excluded-areas>
            <us-state-area>
              <state>HI</state>
            </us-state-area>
          </excluded-areas>
        </shipping-restrictions>
    </merchant-calculated-shipping>
    <merchant-calculated-shipping name="UPS Ground">
        <price currency="USD">8.00</price>
    </merchant-calculated-shipping>
</shipping-methods>

Please note that you cannot combine merchant-calculated shipping methods with other types of shipping methods, such as flat-rate shipping or carrier-calculated shipping methods.

Taxes

To indicate that you will calculate taxes, set the value of the merchant-calculated attribute of the <tax-tables> tag to true in your Checkout API request. Even if you plan to calculate taxes for an order, you should still include default and alternate tax tables in your Checkout API request. If the merchant calculation callback fails for any reason, Google Checkout will use the default and alternate tax tables to compute taxes for the order.

<tax-tables merchant-calculated="true">
      ...
</tax-tables>

 Note: You can only use the Merchant Calculations API to calculate taxes if you use the default U.S. rounding rules for financial calculations.

The default U.S. rounding rules specify that taxes are calculated by assessing the tax rate to the total cost of all of the items and then using the HALF_EVEN rounding mode, or banker's rounding, to determine the tax for the order. These rules are substantially different from the default rounding rules for U.K. merchants. For U.K. merchants, the default behavior is to calculate tax separately for each item in the order and then apply the HALF_UP rounding mode to each calculation.

Coupons and Gift Certificates

To indicate that you accept coupons and will calculate discounts for coupons, set the value of the <accept-merchant-coupons> tag to true in your Checkout API request. To indicate that you accept gift certificates and will calculate discounts for gift certificates, set the value of the <accept-gift-certificates> tag to true in your Checkout API request.

If you set the <accept-merchant-coupons> or the <accept-gift-certificates> tag to true, the Google Checkout Place Order page will display a field where your customer can enter coupon or gift certificate codes. Google Checkout does not limit the number of codes that a customer may enter. However, your response to a merchant calculation callback can specify that a coupon or gift certificate code is invalid.

The following snippet from a Checkout API request indicates that the merchant accepts coupons and gift certificates:

<merchant-calculations>
    <merchant-calculations-url>http://www.example.com/custom.php</merchant-calculations-url>
    <accept-merchant-coupons>true</accept-merchant-coupons>
    <accept-gift-certificates>true</accept-gift-certificates>
</merchant-calculations>

Note: For U.S. merchants, when Google Checkout calculates order totals, coupons are applied before shipping and taxes. Gift certificates are applied after shipping and taxes.

 Note: U.K. merchants cannot yet use the Merchant Calculations API for coupons or gift certificates. Google Checkout will ignore the <accept-merchant-coupons> and <accept-gift-certificates> tags if they are included in a Checkout API request from a U.K. merchant.

Handling Merchant Calculation Callbacks

As discussed in the previous section, if you will perform custom calculations for an order, then your Checkout API request must specify the URL for your custom calculations web service. Google Checkout sends a <merchant-calculation-callback> request to your web service each time any of the following events occur:

• The buyer proceeds to the Place Order page to complete a Google Checkout order. To reach the Place Order page, the buyer could create a new Google account or sign in to an existing Google account. If the buyer has recently shopped with Google Checkout and still has a valid cookie, the buyer could also proceed directly to the Place Order after clicking on a Google Checkout button.
• The buyer enters a new shipping address on the Place Order page.
• The buyer enters a coupon or gift certificate code.
• The buyer changes the shipping address for the order.

A <merchant-calculation-callback> request contains two types of information.

• The <shopping-cart> tag contains the complete shopping cart information from the Checkout API request for the order.
• The <calculate> tag encapsulates information that you need for computing shipping costs, taxes or price adjustments for the order.

The following sections explain how the callback request identifies amounts that you are supposed to calculate.

Shipping

You must calculate the shipping cost for each shipping method identified in the <merchant-calculation-callback> request. That request will list the shipping methods that you included in your Checkout API request. However, if your Checkout API request specified address filters for a shipping method, the callback request will only include a shipping method if the buyer's shipping address is located in an allowed area for the method.

In the callback request, the <shipping> tag encapsulates the list of shipping methods for which you must calculate shipping costs, and the <method> tag identifies individual shipping methods.

To protect the buyer's privacy before the order is placed, Google Checkout does not send street address information in <merchant-calculation-callback> requests. Instead, the callback request contains an anonymous address, which only specifies the city, region/state, postal code and country code for the shipping address.

The example below shows two merchant-calculated shipping methods. The name assigned to each shipping method is shown in bold text.

<shipping-methods>
    <merchant-calculated-shipping name="FedEx Overnight Shipping">
        <price currency="USD">19.00</price>
    </merchant-calculated-shipping>
    <merchant-calculated-shipping name="UPS Ground">
        <price currency="USD">8.00</price>
    </merchant-calculated-shipping>
</shipping-methods>

This excerpt shows how these two shipping methods would be identified in a <merchant-calculation-callback> request. Again, the names of the two shipping methods are shown in bold text.

<calculate>
    <addresses>
        <anonymous-address>
            <country-code>US</country-code>
            <city>Mountain View</city>
            <region>CA</region>
            <postal-code>94043</postal-code>
        </anonymous-address>
    </addresses>
    <shipping>
        <method name="FedEx Overnight Shipping"/>
        <method name="UPS Ground"/>
    </shipping>
</calculate>

Taxes

You must calculate taxes for an order if the <tax> element in the <merchant-calculation-callback> request has a value of true.

The following excerpt is from a callback request that indicates that the merchant needs to calculate taxes for an order but does not need to calculate shipping costs or price adjustments for either coupons or gift certificates. The tag that indicates that the merchant must calculate taxes is shown in bold text.

<calculate>
    <addresses>
        <anonymous-address>
            <country-code>US</country-code>
            <city>Mountain View</city>
            <region>CA</region>
            <postal-code>94043</postal-code>
        </anonymous-address>
    </addresses>
    <tax>true</tax>
</calculate>

Coupons and Gift Certificates

You must calculate price adjustments for each code identified in a callback request. Google Checkout uses the code attribute of the <merchant-code-string> tag to identify coupon and gift certificate codes. Please note that you must determine whether each code is for a coupon or a gift certificate.

The following XML excerpt is from a callback request that indicates that the merchant needs to calculate price adjustments for either coupons or gift certificates (or both). In this example the merchant does not need to calculate shipping costs or taxes. The gift certificate and coupon codes in the example are shown in bold text.

<calculate>
    <addresses>
        <anonymous-address>
            <country-code>US</country-code>
            <city>Mountain View</city>
            <region>CA</region>
            <postal-code>94043</postal-code>
        </anonymous-address>
    </addresses>
    <merchant-code-strings>
        <merchant-code-string code="GiftCard12345"/>
        <merchant-code-string code="FirstVisitCoupon"/>
    </merchant-code-strings>
</calculate>

Sample <merchant-calculation-callback> Request

This section describes a merchant's interactions with the Merchant Calculations API for a sample order with the following characteristics:

• The merchant has indicated that it will calculate shipping costs, taxes and price adjustments for coupons or gift certificates.

• The merchant offers three shipping options for overnight, two-day and ground shipping.

• The merchant uses address filters to indicate that the overnight shipping option is not available for shipping addresses in Alaska and Hawaii.

The following list identifies the different user actions that would prompt Google Checkout to send a <merchant-calculation-callback> request for this order.

1. The buyer clicks the Google Checkout button on the merchant's page and proceeds to the Sign In/Sign Up page in the Google Checkout order flow. The buyer creates a new Google user account and enters a billing address in New York, prompting Google to send a <merchant-calculation-callback> request with that address. The callback request asks the merchant to calculate shipping costs for all three of the merchant's shipping options.

2. The buyer adds a new shipping address in Alaska, prompting Google to send a second callback request with the new address. Since overnight shipping to Alaska is not available, this callback request specifies that the merchant only needs to calculate shipping costs for the two-day and ground shipping options.

3. The buyer adds a coupon code, prompting Google to send a third request. Like the previous callback, this request instructs the merchant to calculate costs for two shipping options. The request also provides the buyer's coupon code.

4. The buyer adds a gift certificate code, prompting Google to send a fourth request. This request contains the same instructions for calculating shipping costs as the previous two requests as well as the coupon code and the gift certificate code.

The following XML shows the last of these callback requests. The example contains two <method> tags, which identify the shipping methods for which the merchant must calculate shipping costs. The request also contains two <merchant-code-string> tags, each of which could hold either a coupon code or a gift certificate code. Finally, the request indicates that the merchant should calculate tax for the order.

<?xml version="1.0" encoding="UTF-8"?>
<merchant-calculation-callback xmlns="http://checkout.google.com/schema/2">
    <shopping-cart>
        <cart-expiration>
            <good-until-date>2007-12-31T23:59:59-05:00</good-until-date>
        </cart-expiration>
        <items>
            <item>
                <merchant-item-id>GGLAA1453</merchant-item-id>
                <item-name>Dry Food Pack</item-name>
                <item-description>One pack of nutritious dried food for emergencies.</item-description>
                <quantity>1</quantity>
                <unit-price currency="USD">4.99</unit-price>
            </item>
            <item>
                <merchant-item-id>MGS2GBMP3</merchant-item-id>
                <item-name>Megasound 2GB MP3 Player</item-name>
                <item-description>This portable MP3 player stores 500 songs.</item-description>
                <quantity>1</quantity>
                <unit-price currency="USD">179.99</unit-price>
            </item>
        </items>
    </shopping-cart>

    <buyer-language>en_US</buyer-language>
    <calculate>
        <addresses>
            <anonymous-address id="739030698069958">
                <country-code>US</country-code>
                <city>Anchorage</city>
                <region>AK</region>
                <postal-code>99501</postal-code>
            </anonymous-address>
        </addresses>
        <tax>true</tax>
        <shipping>
            <method name="UPS 2nd Day Air"/>
            <method name="UPS Ground"/>
        </shipping>
        <merchant-code-strings>
            <merchant-code-string code="GiftCert012345"/>
            <merchant-code-string code="FirstVisitCoupon"/>
        </merchant-code-strings>
    </calculate>
</merchant-calculation-callback>

Returning Merchant Calculation Results

Each time you receive a <merchant-calculation-callback> request, you must process the request, calculate the appropriate values and return a <merchant-calculation-results> XML response.

The following guidelines explain how to create a <merchant-calculation-results> response.

• If you use merchant-calculated shipping methods, your response will contain one <result> element for each shipping method for which you need to calculate shipping costs. Each <result> element will also contain any additional calculated amounts – including taxes or price adjustments – that the callback requested.

  If you do not use merchant-calculated shipping methods, your response will contain one <result> element, which includes any calculated amounts that the callback requested.

• The <result> element's address-id attribute identifies the shipping address associated with the result. The attribute value must correspond to the id of the anonymous-address in the callback as shown in the sample tags below. Note that since each <merchant-calculation-callback> request only specifies one address, this value will be the same for each set of calculated results in your response.

  Callback:
  <anonymous-address id="739030698069958">
  
  Response:
  <result shipping-name="UPS Ground" address-id="739030698069958">
  

• Each result also contains additional information depending on the types of calculations that you performed. Follow all applicable guidelines to create a <merchant-calculation-results> response.

  • Shipping - Set the following values if you are calculating shipping costs for an order.

    • The <result> element's shipping-name attribute, which is only present if you are calculating shipping costs, identifies the shipping method associated with the result. The attribute value must correspond to the name of a shipping method specified in the callback as shown in the sample tags below. Note that this value will be different for each set of calculated results in a response.

      Callback:
      <method name="UPS Ground"/>
      
      Response:
      <result shipping-name="UPS Ground" address-id="739030698069958">
      

    • The <shipping-rate> tag specifies the cost of shipping the order to the address location using the specified shipping method.

    • The <shippable> tag indicates whether the order can be shipped to the specified address using the specified shipping method. For example, you could set the <shippable> tag to false to prevent a shipping method from being used to ship an order to a post office box. If a shipping method is not available at a particular address, Google Checkout will not display that shipping option when the customer selects that address.

  • Taxes - If you need to calculate taxes for the order, each result must specify a <total-tax> tag, which identifies the tax that should be charged for the corresponding shipping method and shipping address.

  • Coupons - If you are supposed to calculate price adjustments for coupons, each <result> tag must contain one <coupon-result> element for each coupon code identified in the callback request.

  • Gift Certificates - If you are supposed to calculate price adjustments for gift certificates, each <result> tag must contain one <gift-certificate-result> element for each gift certificate code identified in the callback request.

When you have finished creating the <merchant-calculation-results> response, return it to Google as an HTTP response to the callback.

Sample <merchant-calculation-results> Response

The following XML shows a sample <merchant-calculation-results> response. This response corresponds to the sample <merchant-calculation-callback> request in the previous section. The response contains calculations for two shipping methods, taxes, one coupon code and one gift certificate code.

<?xml version="1.0" encoding="UTF-8"?>
<merchant-calculation-results xmlns="http://checkout.google.com/schema/2">
    <results>
        <result shipping-name="UPS 2nd Day Air" address-id="739030698069958">
            <shipping-rate currency="USD">22.03</shipping-rate>
            <shippable>true</shippable>            
            <total-tax currency="USD">14.67</total-tax>
            <merchant-code-results>
                <coupon-result>
                    <valid>true</valid>
                    <code>FirstVisitCoupon</code>
                    <calculated-amount currency="USD">5.00</calculated-amount>
                    <message>Congratulations! You saved $5.00 on your first visit!</message>
                </coupon-result>
                <gift-certificate-result>
                    <valid>true</valid>
                    <code>GiftCert012345</code>
                    <calculated-amount currency="USD">10.00</calculated-amount>
                    <message>Your balance will be $0.00 after you confirm your order.</message>
                </gift-certificate-result>
            </merchant-code-results>
        </result>

        <result shipping-name="UPS Ground" address-id="739030698069958">
            <shipping-rate currency="USD">19.48</shipping-rate>
            <shippable>true</shippable>
            <total-tax currency="USD">14.67</total-tax>
            <merchant-code-results>
                <coupon-result>
                    <valid>true</valid>
                    <code>FirstVisitCoupon</code>
                    <calculated-amount currency="USD">5.00</calculated-amount>
                    <message>Congratulations! You saved $5.00 on your first visit!</message>
                </coupon-result>
                <gift-certificate-result>
                    <valid>true</valid>
                    <code>GiftCert012345</code>
                    <calculated-amount currency="USD">10.00</calculated-amount>
                    <message>Your balance will be $0.00 after you confirm your order.</message>
                </gift-certificate-result>
            </merchant-code-results>
        </result>
    </results>
</merchant-calculation-results>

XML Tag Definitions

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

Checkout API Tags for All Orders Using Merchant Calculations

merchant-calculations-url
Definition	The <merchant-calculations-url> tag identifies the URL to which Google Checkout should send <merchant-calculation-callback> requests. Merchants only need to include this tag in Checkout API requests if they have implemented the Merchant Calculations API. Note: Your production calculation service must use port 443, which is the default port for HTTPS. You can use either port 443 or port 80 for your callback URL in the Sandbox environment.
Subtag of	merchant-calculations
API Commands	Checkout
Content Format	String (URI)
Example	<merchant-calculations-url>http://www.example.com/custom.php</merchant-calculations-url>

Additional Checkout API Tags - Shipping

address-filters
Definition	The <address-filters> tag identifies areas where a particular merchant-calculated shipping method is available or unavailable. Address filters are applied before Google Checkout sends a <merchant-calculation-callback> to the merchant. Google Checkout will not ask you to calculate the cost of a particular shipping method for an address if the address filters in the Checkout API request indicate that the method is not available for the address.
Subtag of	merchant-calculated-shipping
Subtags	allow-us-po-box?, allowed-areas, excluded-areas?
API Commands	Checkout
Content Format	Container
Example	<address-filters>false</address-filters>

allow-us-po-box
Definition	The <allow-us-po-box> tag indicates whether a particular shipping method can be used to ship an order to a U.S. post office (P.O.) box. To prevent a flat-rate shipping option from being offered to customers who are shipping orders to P.O. boxes in the United States, include this tag with a value of false in the shipping restrictions for the shipping option. The default value for this tag is true.
Subtag of	shipping-restrictions, address-filters
API Commands	Checkout
Content Format	Boolean
Example	<allow-us-po-box>false</allow-us-po-box>

allowed-areas
Definition	The <allowed-areas> tag contains a list of regions where a shipping option is available.
Subtag of	shipping-restrictions, address-filters
Subtags	us-state-area*, us-zip-area*, us-country-area*, postal-area*, world-area?
API Commands	Checkout
Content Format	Container
Example	<allowed-areas>

excluded-areas
Definition	The <excluded-areas> tag identifies a list of regions where a shipping option is not available.
Subtag of	shipping-restrictions, address-filters
Subtags	us-state-area*, us-zip-area*, us-country-area*, postal-area*
API Commands	Checkout
Content Format	Container
Example	<excluded-areas>

merchant-calculated-shipping
Definition	The <merchant-calculated-shipping> tag contains information about a shipping option in which Google Checkout communicates with the merchant after the shopping cart items are posted and the buyer has selected a shipping address. You may ignore this tag if you are not implementing the Merchant Calculations API, which allows merchants to use a custom process to determine taxes, shipping costs and discounts for an order after the customer has selected a shipping address.
Attributes	Name Format Description name String The name attribute value contains a string that can be used to identify a tax table or shipping method. The attribute value must be at least one non-space character and may not be longer than 255 characters.
Subtag of	shipping-methods
Subtags	price, address-filters?, shipping-restrictions?
API Commands	Checkout
Content Format	Container
Example	<merchant-calculated-shipping name="FedEx 2-day">

merchant-calculations
Definition	The <merchant-calculations> tag contains information about calculations that will be performed by the merchant.
Subtag of	merchant-checkout-flow-support
Subtags	merchant-calculations-url, accept-merchant-coupons?, accept-gift-certificates?
API Commands	Checkout
Content Format	Container
Example	<merchant-calculations>

merchant-calculations-url
Definition	The <merchant-calculations-url> tag identifies the URL to which Google Checkout should send <merchant-calculation-callback> requests. Merchants only need to include this tag in Checkout API requests if they have implemented the Merchant Calculations API. Note: Your production calculation service must use port 443, which is the default port for HTTPS. You can use either port 443 or port 80 for your callback URL in the Sandbox environment.
Subtag of	merchant-calculations
API Commands	Checkout
Content Format	String (URI)
Example	<merchant-calculations-url>http://www.example.com/custom.php</merchant-calculations-url>

postal-area
Definition	The <postal-area> tag specifies a geographic region somewhere in the world. As a subtag of <allowed-areas>, the <postal-area> tag contains a country where a particular shipping option is available. The tag may also contain a postal code or range of postal codes in that country where the shipping option is offered. As a subtag of <excluded-areas>, the <postal-area> tag contains a country (and possibly a zip code or range of zip codes within that country) where a particular shipping option is unavailable. As a subtag of <tax-area> or <tax-areas>, the <postal-area> tag contains a country and possibly a zip code or range of zip codes where a tax rule should be applied.
Subtag of	allowed-areas, excluded-areas, tax-area, tax-areas
Subtags	country-code, postal-code-pattern?
API Commands	Checkout
Content Format	Complex
Example	<postal-area>

postal-code-pattern
Definition	The <postal-code-pattern> tag contains a postal code or a range of postal codes for a specific country. To specify a range of postal codes, use an asterisk as a wildcard operator. For example, you can provide a <postal-code-pattern> value of SW* to indicate that a shipping option is available or a tax rule applies in any postal code beginning with the characters SW.
Subtag of	postal-area
API Commands	Checkout
Content Format	String
Example	<postal-code-pattern>94043</postal-code-pattern <postal-code-pattern>SW*</postal-code-pattern>

price
Definition	The <price> tag contains the cost to ship an order using a particular shipping method. This tag has one required attribute, which identifies the currency of the price.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	flat-rate-shipping, pickup, merchant-calculated-shipping
API Commands	Checkout
Content Format	Decimal
Example	<price currency="USD">8.54</price>

shipping-methods
Definition	The <shipping-methods> tag contains information about the different ways that an order may be shipped.
Subtag of	merchant-checkout-flow-support
Subtags	carrier-calculated-shipping*, flat-rate-shipping*, merchant-calculated-shipping*, pickup*
API Commands	Checkout
Content Format	Container
Example	<shipping-methods>

shipping-restrictions
Definition	The <shipping-restrictions> tag contains information about particular areas where items can (or cannot) be shipped.
Subtag of	flat-rate-shipping, merchant-calculated-shipping
Subtags	allowed-areas, excluded-areas?, allow-us-po-box?
API Commands	Checkout
Content Format	Container
Example	<shipping-restrictions>

state
Definition	The <state> tag identifies a state where a particular tax rule is applied or where a particular shipping option is available or unavailable.
Subtag of	us-state-area
API Commands	Checkout
Content Format	String
Example	<state>CA</state>

us-country-area
Definition	As a subtag of <allowed-areas>, the <us-country-area> tag identifies a region of the United States where a particular shipping option is available. As a subtag of <excluded-areas>, the <us-country-area> tag identifies a region of the United States where a particular shipping option is unavailable. As a subtag of <tax-area> or <tax-areas>, the <us-country-area> tag identifies a region of the United States where a tax rule should be applied. This tag has one required attribute, which identifies the region of the United States.
Attributes	Name Format Description country-area String The country-area attribute identifies a region of the United States. Valid values for this attribute are: CONTINENTAL_48 - All U.S. states except Alaska and Hawaii FULL_50_STATES - All U.S. states ALL - All U.S. postal service addresses, including military addresses, U.S. insular areas, etc.
Subtag of	allowed-areas, excluded-areas, tax-area, tax-areas
API Commands	Checkout
Content Format	Complex
Example	<us-country-area country-area="CONTINENTAL_48"/>

us-state-area
Definition	As a subtag of <allowed-areas>, the <us-state-area> tag contains a state where a particular shipping option is available. As a subtag of <excluded-areas>, the <us-state-area> tag contains a state where a particular shipping option is unavailable. As a subtag of <tax-area> or <tax-areas>, the <us-state-area> tag contains a state where a tax rule should be applied.
Subtag of	allowed-areas, excluded-areas, tax-area, tax-areas
Subtags	state
API Commands	Checkout
Content Format	Container
Example	<us-state-area>

us-zip-area
Definition	As a subtag of <allowed-areas>, the <us-zip-area> tag contains a zip code or range of zip codes where a particular shipping option is available. As a subtag of <excluded-areas>, the <us-zip-area> tag contains a zip code or range of zip codes where a particular shipping option is unavailable. As a subtag of <tax-area> or <tax-areas>, the <us-zip-area> tag contains a zip code or range of zip codes where a tax rule should be applied.
Subtag of	allowed-areas, excluded-areas, tax-area, tax-areas
Subtags	zip-pattern
API Commands	Checkout
Content Format	Container
Example	<us-zip-area>

world-area
Definition	The <world-area> tag represents the entire world. This tag indicates that a shipping option is available worldwide or that a particular tax rule applies worldwide. For shipping options, the <world-area> tag can only appear as a subtag of the allowed-areas tag. (Including the <world-area> tag as a subtag of the excluded-areas tag would make the corresponding shipping option unavailable to all shipping addresses.) However, you can use the <world-area> tag to indicate that a shipping option is available worldwide and then identify specific excluded areas where the shipping option is unavailable. Those excluded areas could identify regions that are covered by other shipping options or regions where you do not ship items. For tax rules, Google Checkout will select the first tax rule that matches the customer's shipping address. As such, if you use the <world-area> tag to define the area where a tax rule applies, that tax rule must appear last in the list of tax rules in your API request. See the XML Examples for Tax Areas to see a feed excerpt that uses the <world-area> tag for tax rules.
Subtag of	allowed-areas, tax-area, tax-areas
API Commands	Checkout
Content Format	Complex
Example	<world-area/>

zip-pattern
Definition	The <zip-pattern> tag contains a zip code or a range of zip codes. To specify a range of zip codes, use an asterisk as a wildcard operator. For example, you can specify that a shipping option is available or a tax rule applies to zip codes 94040 through 94049 by entering 9404* as the <zip-pattern> value.
Subtag of	us-zip-area
API Commands	Checkout
Content Format	String
Example	<zip-pattern>94043</zip-pattern <zip-pattern>9404*</zip-pattern>

Additional Checkout API Tags - Taxes

tax-tables
Definition	The <tax-tables> tag contains information about all of the different rules that may be applied to calculate tax for an order.
Attributes	Name Format Description merchant-calculated Boolean The merchant-calculated attribute contains a Boolean value that indicates whether tax for the order is calculated using a special process.
Subtag of	merchant-checkout-flow-support
Subtags	default-tax-table, alternate-tax-tables?
API Commands	Checkout
Content Format	Container
Example	<tax-tables>

Additional Checkout API Tags - Gift Certificates

accept-gift-certificates
Definition	The <accept-gift-certificates> tag indicates whether customers should be able to apply gift certificates to their order totals. If this tag has a value of true, then Google Checkout will display an option for customers to enter gift certificate codes. These codes will then be passed to the merchant in a merchant calculation callback request.
Subtag of	merchant-calculations
API Commands	Checkout
Content Format	Boolean
Example	<accept-gift-certificates>true</accept-gift-certificates>

Additional Checkout API Tags - Coupons

accept-merchant-coupons
Definition	The <accept-merchant-coupons> tag indicates whether customers should be able to apply coupon codes to their order totals. If this tag has a value of true, then Google Checkout will display an option for customers to enter coupon codes. These codes will then be passed to the merchant in a merchant calculation callback request.
Subtag of	merchant-calculations
API Commands	Checkout
Content Format	Boolean
Example	<accept-merchant-coupons>true</accept-merchant-coupons>

Merchant Calculation Callbacks

addresses
Definition	The <addresses> tag contains information about shipping addresses for an order.
Subtag of	calculate
Subtags	anonymous-address*
API Commands	Merchant Calculation Callback
Content Format	Container
Example	<addresses>

anonymous-address
Definition	The <anonymous-address> tag contains a possible shipping address for an order. This address should be used to calculate taxes and shipping costs for the order.
Attributes	Name Format Description id String The id attribute specifies a unique value that identifies a particular address.
Subtag of	addresses
Subtags	city, region, postal-code, country-code
API Commands	Merchant Calculation Callback
Content Format	Complex
Example	<anonymous-address id="BuyerAddress">

buyer-id
Definition	The <buyer-id> tag contains an ID that uniquely identifies the user to Google.
Subtag of	new-order-notification, merchant-calculation-callback
API Commands	New Order Notification, Merchant Calculation Callback
Content Format	Long
Example	<buyer-id>294873009217523</buyer-id>

buyer-language
Definition	The <buyer-language> tag identifies the customer's user interface language. At this time, this value is always en_US.
Subtag of	merchant-calculation-callback
API Commands	Merchant Calculation Callback
Content Format	String
Example	<buyer-language>en_US</buyer-language>

calculate
Definition	The <calculate> tag contains details about calculations that the merchant should perform for an order.
Subtag of	merchant-calculation-callback
Subtags	addresses?, merchant-code-strings?, shipping?, tax
API Commands	Merchant Calculation Callback
Content Format	Container
Example	<calculate>

cart-expiration
Definition	The <cart-expiration> tag encapsulates information about the date that the cart expires.
Subtag of	shopping-cart
Subtags	good-until-date
API Commands	Checkout, Merchant Calculation Callback, New Order Notification
Content Format	Container
Example	<cart-expiration>

city
Definition	The <city> tag identifies the city associated with an order's billing or shipping address.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address
API Commands	New Order Notification, Risk Information Notification, Merchant Calculation Callback
Content Format	String
Example	<city>Mountain View</city>

company-name
Definition	The <company-name> tag identifies the company to which an order is being shipped. Please note that Google does not currently request this information from customers but may do so in the future. However, until then, this tag will contain an empty value.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
API Commands	New Order Notification, Risk Information Notification
Content Format	String
Example	<company-name>Example.com Industries</company-name>

contact-name
Definition	The <contact-name> tag identifies the person to whom an order is being shipped.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
API Commands	New Order Notification, Risk Information Notification
Content Format	String
Example	<contact-name>John McShopalot</contact-name>

country-code
Definition	As a subtag of <postal-area>, the <country-code> tag specifies a country associated with a tax area, shipping restriction or address filter Note that Google Checkout does not allow you to ship orders to countries that are export-embargoed for the United States. Google Checkout will return an error if your shipping restrictions or address filters include one of these countries in a shipping area. For example, Iran (IR) and North Korea (KP) may not be included in a shipping area. In all other contexts, the <country-code> tag identifies the country code associated with an order's billing address or shipping address. The value of this tag must be a two-letter ISO 3166 country code.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address, postal-area
API Commands	New Order Notification, Risk Information Notification, Merchant Calculation Callback
Content Format	String
Example	<country-code>US</country-code>

good-until-date
Definition	The <good-until-date> tag identifies the date that the order in a Checkout API request expires. The date must be specified using the ISO 8601 Date and Time Format. The time must include the time-zone designator for UTC (Coordinated Universal Time), which is "Z", or you may specify a local time along with a time-zone offset in hours and minutes. A time zone offset of "+hh:mm" indicates that the date/time uses a local time zone which is "hh" hours and "mm" minutes ahead of UTC. A time zone offset of "-hh:mm" indicates that the date/time uses a local time zone which is "hh" hours and "mm" minutes behind UTC. The examples show dates formatted using the UTC time-zone designator and using time-zone offsets. Note: If you specify a value for this element, Google Checkout will reject the shopping cart if the user submits the cart after the specified date.
Subtag of	cart-expiration
API Commands	Checkout, Merchant Calculation Callback, New Order Notification
Content Format	Date/Time
Example	<good-until-date>2008-01-01T04:59:59Z</good-until-date> <good-until-date>2007-12-31T11:59:59-05:00</good-until-date>

item
Definition	The <item> tag contains information about an individual item listed in the customer's shopping cart.
Subtag of	items
Subtags	item-name, item-description, unit-price, quantity, item-weight?, merchant-item-id?, tax-table-selector?, digital-content?, merchant-private-item-data?
API Commands	Checkout, Merchant Calculation Callback, New Order Notification
Content Format	Container
Example	<item>

item-description
Definition	The <item-description> tag contains a description of an item.
Subtag of	item
API Commands	Checkout, Merchant Calculation Callback, New Order Notification
Content Format	String
Example	<item-description>Easy-to-use MP3 Player</item-description>

item-name
Definition	The <item-name> tag identifies the name of an item.
Subtag of	item
API Commands	Checkout, Merchant Calculation Callback, New Order Notification
Content Format	String
Example	<item-name>HelloWorld 2GB MP3 Player</item-name>

items
Definition	The <items> tag contains the list of items in the customer's shopping cart.
Subtag of	shopping-cart
Subtags	item*
API Commands	Checkout, Merchant Calculation Callback, New Order Notification
Content Format	Container
Example	<items>

merchant-calculation-callback
Definition	The <merchant-calculation-callback> tag contains all information related to a request that Google Checkout sends to a merchant for custom calculations.
Attributes	Name Format Description serial-number String The serial-number attribute contains an ID that uniquely identifies a Google Checkout notification.
Subtags	buyer-id?, buyer-language, calculate, shopping-cart
API Commands	Merchant Calculation Callback
Content Format	Container
Example	<merchant-calculation-callback>

merchant-code-string
Definition	The <merchant-code-string> tag contains a coupon or gift certificate code that the customer entered for an order.
Attributes	Name Format Description code String The code attribute identifies a coupon or gift certificate code that a customer wants to apply to an order total.
Subtag of	merchant-code-strings
API Commands	Merchant Calculation Callback
Content Format	Container
Example	<merchant-code-string code="CodeXYZ">

merchant-code-strings
Definition	The <merchant-code-strings> tag encapsulates a list of coupon or gift certificate codes that a customer has entered for an order.
Subtag of	calculate
Subtags	merchant-code-string?
API Commands	Merchant Calculation Callback
Content Format	Container
Example	<merchant-code-strings>

merchant-item-id
Definition	The <merchant-item-id> tag contains a value, such as a stock keeping unit (SKU), that you use to uniquely identify an item. Google Checkout will include this value in the merchant calculation callbacks and the new order notification for the order. This value also appears in the order information displayed in the Merchant Center. Note: To use the <merchant-item-id> to modify the shipping information for an item in an order, you must have provided the same <merchant-item-id> for that item in the Checkout API request for the order.
Subtag of	item, item-id
API Commands	Checkout, Merchant Calculation Callback, New Order Notification
Content Format	String
Example	<merchant-item-id>1234abcd</merchant-item-id>

merchant-private-item-data
Definition	The <merchant-private-item-data> tag contains any well-formed XML sequence that should accompany an individual item in an order. Google Checkout will return this XML in the <merchant-calculation-callback> and the <new-order-notification> for the order.
Subtag of	item
API Commands	Checkout, Merchant Calculation Callback, New Order Notification
Content Format	Container
Example	<merchant-private-item-data>    <item-data>Popular item - order more if needed</item-data> </merchant-private-item-data>

method
Definition	The <method> tag identifies a shipping method for which costs need to be calculated.
Attributes	Name Format Description name String The name attribute value contains a string that can be used to identify a tax table or shipping method. The attribute value must be at least one non-space character and may not be longer than 255 characters.
Subtag of	shipping
API Commands	Merchant Calculation Callback
Content Format	Complex
Example	<method name="FedEx">

postal-code
Definition	The <postal-code> tag identifies the zip code or postal code associated with either a billing address or a shipping address.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address
API Commands	New Order Notification, Risk Information Notification, Merchant Calculation Callback
Content Format	String
Example	<postal-code>94043</postal-code>

quantity
Definition	The <quantity> tag identifies how many units of a particular item are included in the customer's shopping cart.
Subtag of	item
API Commands	Checkout, Merchant Calculation Callback, New Order Notification
Content Format	Integer
Example	<quantity>2</quantity>

region
Definition	The <region> tag identifies the state or province associated with a billing address or shipping address.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address
API Commands	New Order Notification, Risk Information Notification, Merchant Calculation Callback
Content Format	String
Example	<region>CA</region>

shipping
Definition	The <shipping> tag contains information about the shipping method and costs associated with an order. When the <shipping> tag appears in a new order notification (as a subtag of <order-adjustment>), it has three possible subtags: <flat-rate-shipping-adjustment>, <merchant-calculated-shipping-adjustment> and <pickup-shipping-adjustment>. When the <shipping> tag appears in a merchant calculation callback (as a subtag of <calculate>), its only subtag is <method>, but that tag may occur multiple times.
Subtag of	order-adjustment, calculate
Subtags	carrier-calculated-shipping-adjustment?, flat-rate-shipping-adjustment?, merchant-calculated-shipping-adjustment?, pickup-shipping-adjustment?, method*
API Commands	Merchant Calculation Callback, New Order Notification
Content Format	Container
Example	<shipping>

shopping-cart
Definition	The <shopping-cart> tag contains the list of items in a customer order and some other basic order information.
Subtag of	checkout-shopping-cart, new-order-notification, merchant-calculation-callback
Subtags	cart-expiration?, items, merchant-private-data?
API Commands	Checkout, Merchant Calculation Callback, New Order Notification
Content Format	Container
Example	<shopping-cart>

tax
Definition	The <tax> tag indicates whether the merchant needs to calculate taxes for the order.
Subtag of	result
API Commands	Merchant Calculation Callback
Content Format	Boolean
Example	<tax>true</tax>

unit-price
Definition	The <unit-price> tag identifies the cost of the item. This tag has one required attribute, which identifies the currency of the price.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	item
API Commands	Checkout, Merchant Calculation Callback, New Order Notification
Content Format	Decimal
Example	<unit-price currency="USD">159.99</unit-price>

Merchant Calculation Results

calculated-amount
Definition	The <calculated-amount> tag contains the calculated amount of a coupon or gift certificate.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	coupon-adjustment, gift-certificate-adjustment, coupon-result, gift-certificate-result
API Commands	New Order Notification
Content Format	Decimal
Example	<calculated-amount currency="USD">11.05</calculated-amount>

code
Definition	The <code> tag contains the code for a coupon or gift certificate that was applied to an order.
Subtag of	coupon-adjustment, gift-certificate-adjustment, coupon-result, gift-certificate-result
API Commands	Merchant Calculation Results, New Order Notification
Content Format	String
Example	<code>GiftCert12345</code>

coupon-result
Definition	The <coupon-result> tag contains information about a coupon used to calculate an order total.
Subtag of	merchant-code-results
Subtags	valid, calculated-amount, code, message
API Commands	Merchant Calculation Results
Content Format	Container
Example	<coupon-result>

gift-certificate-result
Definition	The <gift-certificate-result> tag contains information about a gift certificate used to calculate an order total.
Subtag of	merchant-code-results
Subtags	valid, calculated-amount, code, message
API Commands	Merchant Calculation Results
Content Format	Container
Example	<gift-certificate-result>

merchant-calculation-results
Definition	The <merchant-calculation-results> tag contains a response to a request for custom calculations.
Subtags	results
API Commands	Merchant Calculation Results
Content Format	Container
Example	<merchant-calculation-results>

merchant-code-results
Definition	The <merchant-code-results> tag contains information about coupons and gift certificates that were calculated into an order total.
Subtag of	result
Subtags	coupon-result*, gift-certificate-result*
API Commands	Merchant Calculation Results
Content Format	Container
Example	<merchant-code-results>

message
Definition	The <message> tag contains a message associated with a coupon or gift certificate or, when used in a <send-buyer-message> request, a message that you want to communicate to a buyer about a specific order. The maximum accepted length for the tag value is 255 characters.
Subtag of	coupon-adjustment, gift-certificate-adjustment, coupon-result, gift-certificate-result, send-buyer-message
API Commands	New Order Notification, Send Buyer Message, Merchant Calculation Results
Content Format	String
Example	<message>You saved $10.00 with this gift certificate.</message>

result
Definition	The <result> tag contains calculations for taxes, shipping costs, and discounts for a particular shipping method and shipping address.
Attributes	Name Format Description shipping-name String The shipping-name attribute identifies the name of the shipping option for which a calculation result applies. address-id String The address-id attribute contains an ID that identifies the shipping address associated with a <result> in a merchant calculation results response. The attribute value must correspond to the id of the anonymous address in the merchant calculation callback.
Subtag of	results
Subtags	total-tax?, shipping-rate?, shippable?, merchant-code-results?
API Commands	Merchant Calculation Results
Content Format	Complex
Example	<result shipping-name="FedEx" address-id="938515801">

results
Definition	The <results> tag contains one or more <result> elements, each of which contains shipping, tax and discount calculations for a particular shipping method and shipping address.
Subtag of	merchant-calculation-results
Subtags	result*
API Commands	Merchant Calculation Results
Content Format	Container
Example	<results>

shippable
Definition	The <shippable> tag indicates whether an order can be shipped to the specified shipping address.
Subtag of	result
API Commands	Merchant Calculation Results
Content Format	Boolean
Example	<shippable>true</shippable>

shipping-rate
Definition	The <shipping-rate> tag contains the shipping costs that have been calculated for an order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	result
API Commands	Merchant Calculation Results
Content Format	Complex
Example	<shipping-rate currency="USD">14.50</shipping-rate>

total-tax
Definition	The <total-tax> tag contains the total tax amount for an order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	order-adjustment, result
API Commands	New Order Notification, Merchant Calculation Results
Content Format	Decimal
Example	<total-tax currency="USD">11.05</total-tax>

valid
Definition	The <valid> tag indicates whether a coupon or gift certificate code that was submitted by the customer is actually valid.
Subtag of	coupon-result, gift-certificate-result
API Commands	Merchant Calculation Results
Content Format	Boolean
Example	<valid>true</valid>