Google Checkout HTML API - Merchant-calculated Shipping

Overview

Merchant-calculated shipping allows you to wait until the buyer selects the shipping address for an order before you determine the availability and cost of different shipping options for that order.

Note: If you offer merchant-calculated shipping options for an order, you may not also provide other types of shipping options, including flat-rate, pickup or carrier-calculated options. In addition, even though you intend to calculate shipping costs, you must still specify a backup shipping cost for each merchant-calculated shipping option. If a merchant calculation fails for any reason, Google will use these backup values for the shipping methods in your order.

To use merchant-calculated shipping methods, you must build and operate a fast, highly reliable web service that calculates shipping costs. For more information about the process for calculating shipping costs for an order, please see the separate document titled Implementing the Merchant Calculations HTML API.

Understanding Merchant-calculated Shipping

To offer merchant-calculated shipping methods, you must include the following information in your Checkout API request:

• The URL of your web service that calculates shipping costs. That service may also calculate taxes as well as price adjustments for coupons and gift certificates.

• A list of merchant-calculated shipping options that are available for the order. For each option, Google strongly encourages you to provide the following information:

  • The default price for the shipping option. After the customer selects the shipping address for the order, Google will send a merchant-calculation-callback request to your calculations web service. If that request fails for any reason, Google will use the default price for the shipping option. If you do not provide a default price for a merchant-calculated shipping option, Google will not charge the customer for that option if the merchant-calculation-callback request fails.

  • A list of address filters, which restrict the shipping option so that it is only available for shipping addresses in specified geographic regions. For example, you could restrict a shipping option so that it is only available for shipping addresses in specific states or countries.

    You can also further restrict the availability of a shipping option only if a merchant-calculation-callback request fails. To add these additional constraints, your Checkout API request must specify shipping restrictions in addition to address filters. Please see the Address Filters and Shipping Restrictions section for more information about these two mechanisms.

Address Filters and Shipping Restrictions

Google Checkout provides two mechanisms, address filters and shipping restrictions, that allow you to restrict a shipping method so that it is only available for shipping addresses in specified geographic regions. You can allow customers to ship items (or prevent customers from shipping items) to specific states, zip codes or regions of the United States. You can also allow shipping to other countries or to the entire world. In addition, you can specify whether each shipping option is available if the shipping address is a U.S. post-office box. For more information about specifying geographic areas for shipping options or tax rules, please see the separate document that explains Checkout API HTML parameters for specifying geographic areas.

Google Checkout will allow your customer to select any shipping option where all of the following conditions are true:

• The shipping address is included in the list of allowed areas for the shipping option.
• The shipping address is not included in the list of excluded areas for the shipping option.
• If the shipping address is a P.O. box, then the shipping option does not contain a shipping restriction specifying that the option cannot be selected to ship an order to a P.O. box. Please see the allow-us-po-box parameter definition for more information.

Note: Google Checkout's default behavior is to allow shipping to all postal addresses for the merchant's home country. For example, for U.S. merchants, Google Checkout default behavior is to allow shipping to all U.S. postal addresses, including military bases. As such, if you do not ship to all U.S. postal addresses, you do need to specify shipping restrictions in your Checkout API requests. For U.K. merchants, the default shipping area is all U.K. postal addresses.

Deciding to Use Shipping Restrictions or Address Filters

If you are implementing the Merchant Calculations API, then you may need to use either or both of these filtering mechanisms.

• If a merchant-calculated shipping option is always available in the same areas, use address filters for that option. After the buyer selects a shipping address, Google Checkout will only display shipping options that are available after applying the address filters in your Checkout API request.

  Note: Most merchants only need to use address filters to limit the availability of merchant-calculated shipping options.

• If you also want to limit the availability of a shipping option if a merchant-calculation-callback fails, then you must use shipping restrictions for that option. You can still use address filters for that shipping option if the option is only available in certain geographies.

  For example, suppose a merchant in the United States offers next-day shipping to addresses in the United States and England. However, the buyer can not select the next-day shipping option if the shipping address is a U.S. post-office (P.O.) box. In addition, if the shipping address is in England, the merchant only offers next-day shipping for orders placed by 12 p.m. EST.

  • The merchant in this example can use an address filter to prevent the buyer from selecting the shipping option if the shipping address is a P.O. box. The first bullet point in this section explains how to use address filters in this manner.

  • If the shipping address is in England, the merchant can choose whether to offer the next-day shipping option based on the time that the merchant receives the merchant-calculation-callback request for the order. However, if the shipping address is in England and the callback fails for any reason, then the merchant does not want to offer next-day shipping for the order. In this case, the merchant can use a shipping restriction to instruct Google not to offer the shipping option.

  If this example applies to you, meaning you need to limit the availability of shipping options when merchant-calculation-callback requests fail, please see the Shipping Restrictions and Address Filters document for more information about these features.

Checklist for Implementing Merchant-calculated Shipping

The following checklist will help you to ensure that you have correctly implemented merchant-calculated shipping.

• Confirm that you have developed a web service that implements the Merchant Calculations API.

• Ensure that your Checkout API request specifies the location of your calculations service as the value of the merchant-calculations-url parameter.

• Ensure that your Checkout API request does not mix merchant-calculated shipping options with other types of shipping options.

• Verify that you have specified a backup shipping cost using the price parameter. If you specify more than one merchant-calculated shipping option in your Checkout API request, you must specify a backup price for each of those options. If you do not specify a backup price for a shipping option and the merchant-calculation -callback fails for any reason, Google will not add shipping charges if the buyer selects that shipping option.

HTML Examples for Merchant-Calculated Shipping

The HTML examples below demonstrate several use cases for implementing merchant-calculated shipping. Please note that the examples only include the HTML input parameters relevant to shipping methods.

Example 1 – Using Merchant Calculated Shipping

The following example shows two merchant-calculated shipping methods. The first shipping method, which is for UPS Next Day Air shipping, has a default price of $20.00. This option also will not be offered if the shipping address is a P.O. box in the United States. The second option, which is for UPS Ground Shipping, has a default price of $15.00. The example also specifies that the merchant will calculate taxes as well as price adjustments associated with coupons or gift certificates.

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.name"
  value="UPS Next Day Air"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.price"
  value="20.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.price.currency"
  value="USD"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.address-filters.allow-us-po-box"
  value="false"/>


<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="15.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-2.price.currency"
  value="USD"/>

Example 2 – Using Address Filters and Shipping Restrictions

In this example, the merchant offers the same two shipping options as in example 1. However, in this example, the merchant has added shipping restrictions to specify that the next-day shipping option will not be available if the <merchant-calculation-callback> request fails and the shipping address is in either Alaska or Hawaii.

The following list explains how Google Checkout will handle different shipping addresses based on the HTML in the example:

• If the customer enters any U.S. postal address that is not a P.O. box, Google Checkout will send a callback request instructing the merchant to calculate shipping costs for both shipping options.

  • If the callback request is successful, then Google will offer the two shipping options to the buyer using the shipping costs from the merchant's <merchant-calculation-response>.

  • If the callback request is not successful, and the shipping address is in the continental United States, Google will let the buyer choose either of the two shipping methods. In this case, the next-day shipping method will cost $20.00 and the ground shipping method will cost $15.00.

  • If the callback request is not successful, and the shipping address is in Alaska or Hawaii, Google will only offer the second shipping option at a cost of $15.00.

• If the customer enters a U.S. postal address that is a P.O. box, Google Checkout will send a callback request instructing the merchant to calculate the shipping cost for the second shipping option, which is for ground shipping. Since the address filter for the first shipping option indicates that that option is not available for P.O. boxes, Google will not allow the customer to select that shipping option and will not ask the merchant to calculate the cost of that shipping option.

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.name"
  value="UPS Next Day Air"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.price"
  value="20.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.price.currency"
  value="USD"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-1.address-filters.allow-us-po-box"
  value="false"/>

<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="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-2.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="15.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.merchant-calculated-shipping-2.price.currency"
  value="USD"/>

HTML Parameter Definitions