Implementing the Merchant Calculations HTML API

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 parameter in your Checkout API request. The merchant-calculations-url parameter'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.

<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.name" value="FedEx Overnight Shipping"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.price" value="19.00"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.currency" value="USD"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.address-filters.excluded-areas.us-state-area-1.state" value="AK"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.shipping-restrictions.excluded-areas.us-state-area-1.state" value="HI"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-2.name" value="UPS Ground"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-2.price" value="8.00"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-2.currency" value="USD"/>

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

<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.merchant-calculated" value="true"/>

 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 parameter 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 parameter to true in your Checkout API request.

If you set the accept-merchant-coupons or the accept-gift-certificates parameter 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:

<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.merchant-calculations.merchant-calculations-url" value="http://www.example.com/calc.php"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.merchant-calculations.accept-merchant-coupons" value="true"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.merchant-calculations.accept-gift-certificates" value="true"/>

Note: 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 parameters 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.

• It contains the complete shopping cart information from the Checkout API request for the order.
• It contains 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 method parameter 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.

<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.name" value="FedEx Overnight Shipping"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.price" value="19.00"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.currency" value="USD"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-2.name" value="UPS Ground"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-2.price" value="8.00"/>
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-2.currency" value="USD"/>

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.

_type=merchant-calculation-callback
  ...
  &calculate.addresses.anonymous-address-1.id=739030698069958
  &calculate.addresses.anonymous-address-1.country-code=US
  &calculate.addresses.anonymous-address-1.city=Mountain%20View
  &calculate.addresses.anonymous-address-1.region=CA
  &calculate.addresses.anonymous-address-1.postal-code=94043
  &calculate.shipping.method-1.name=FedEx%20Overnight%20Shipping
  &calculate.shipping.method-2.name=UPS%20Ground

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 parameter that indicates that the merchant must calculate taxes is shown in bold text.

_type=merchant-calculation-callback
  ...
  &calculate.addresses.anonymous-address-1.id=739030698069958
  &calculate.addresses.anonymous-address-1.country-code=US
  &calculate.addresses.anonymous-address-1.city=Mountain%20View
  &calculate.addresses.anonymous-address-1.region=CA
  &calculate.addresses.anonymous-address-1.postal-code=94043
  &calculate.tax=true

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.

_type=merchant-calculation-callback
  ...
  &calculate.addresses.anonymous-address-1.id=739030698069958
  &calculate.addresses.anonymous-address-1.country-code=US
  &calculate.addresses.anonymous-address-1.city=Mountain%20View
  &calculate.addresses.anonymous-address-1.region=CA
  &calculate.addresses.anonymous-address-1.postal-code=94043
  &calculate.merchant-code-strings.merchant-code-string-1.code=GiftCard12345
  &calculate.merchant-code-strings.merchant-code-string-2.code=FirstVisitCoupon

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 excerpt shows the last of these callback requests. The example contains two method parameters, which identify the shipping methods for which the merchant must calculate shipping costs. The request also contains two merchant-code-string parameters, 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.

_type=merchant-calculation-callback
  &shopping-cart.cart-expiration.good-until-date=2007-12-31T23%3A59%3A59-05%3A00
  &shopping.items.item-1.merchant-item-id=GGLAA1453
  &shopping.items.item-1.item-name=Dry%20Food%20Pack
  &shopping.items.item-1.item-description=One%20pack%20of%20nutritious%20dried%20food%20for%20emergencies.
  &shopping.items.item-1.quantity=1
  &shopping.items.item-1.unit-price=4.99
  &shopping.items.item-1.unit-price.currency=USD
  &shopping.items.item-2.merchant-item-id=MGS2GBMP3
  &shopping.items.item-2.item-name=Megasound%202GB%20MP3%20Player
  &shopping.items.item-2.item-description=This%20portable%20MP3%20player%20stores%900%20songs.
  &shopping.items.item-2.quantity=1
  &shopping.items.item-2.unit-price=79.99
  &shopping.items.item-2.unit-price.currency=USD
  &buyer-language=en_US

  &calculate.addresses.anonymous-address-1.id=739030698069958
  &calculate.addresses.anonymous-address-1.country-code=US
  &calculate.addresses.anonymous-address-1.city=Anchorage
  &calculate.addresses.anonymous-address-1.region=CA
  &calculate.addresses.anonymous-address-1.postal-code=99501
  &calculate.tax=true
  &calculate.shipping.method-1.name=FedEx%20Two-day%20Shipping
  &calculate.shipping.method-2.name=UPS%20Ground
  &calculate.merchant-code-strings.merchant-code-string-1.code=GiftCard12345
  &calculate.merchant-code-strings.merchant-code-string-2.code=FirstVisitCoupon

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 set of calculated costs for each of those methods. In the response, the HTML parameter names will associate an index value with the recurring result element to associate calculated amounts with a particular shipping method. For each result, you must provide all calculated amounts – including shipping costs, taxes and price adjustments – that the callback requested.

  If you do not use merchant-calculated shipping methods, your response will only contain one set of calculated amounts. In the response, all of the HTML parameter names will specify the index value of 1 for the result element.

• The address-id parameter identifies the shipping address associated with the result. The parameter value must correspond to the id parameter value in the callback as shown in the sample parameters 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
  _type=merchant-calculation-callback
    &calculate.addresses.anonymous-address-1.id=739030698069958
    ...
  
  Response
  _type=merchant-calculation-results
    &results.result-1.shipping-name=UPS%20Ground
    &results.result-1.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 shipping-name parameter, which is only present if you are calculating shipping costs, identifies the shipping method associated with the result. The parameter value must correspond to the name of a shipping method specified in the callback as shown in the sample parameters below. Note that this value will be different for each set of calculated results in a response.

      Callback
      _type=merchant-calculation-callback
        ...
        &calculate.shipping.method-1.name=UPS%20Ground
      
      Response
      _type=merchant-calculation-results
        &results.result-1.shipping-name=UPS%20Ground
        &results.result-1.address-id=739030698069958
        ...
      

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

    • The shippable parameter indicates whether the order can be shipped to the specified address using the specified shipping method. For example, you could set the shippable parameter 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 parameter, 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 set of calculated amounts must contain the code and valid parameters for each coupon code identified in the callback request. These parameters identify each coupon and indicate whether that coupon can be used. In addition, the response may also provide the message and calculated-amount parameters for each coupon.

  • Gift Certificates - If you are supposed to calculate price adjustments for gift certificates, each result set of calculated amounts must contain the code and valid parameters for each gift certificate code identified in the callback request. These parameters identify each gift certificate and indicate whether that gift certificate can be used. In addition, the response may also provide the message and calculated-amount parameters for each gift certificate.

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

HTML Parameter Definitions

Checkout API Tags for All Orders Using Merchant Calculations

Additional Checkout API Tags - Shipping

Additional Checkout API Tags - Taxes

Additional Checkout API Tags - Gift Certificates

Additional Checkout API Tags - Coupons

Merchant Calculation Callbacks

Merchant Calculation Results