Google Checkout HTML API - Carrier-calculated Shipping

Overview

This document describes a Google Checkout feature that enables Google to dynamically request rates from shipping carriers based on the information in your Checkout API request. Google supports the carrier-calculated shipping feature for three carriers: FedEx, UPS and the U.S. Postal Service (USPS). This document explains how the carrier-calculated shipping feature works and provides HTML examples that demonstrate how to use carrier-calculated shipping for several different shipping scenarios. This document also defines the HTML parameters that are used for carrier-calculated shipping and the Google Checkout XML schema changes that support this feature.

This document contains the following sections.

• The Understanding Carrier-calculated Shipping section explains how the carrier-calculated shipping feature works. It also explains the information that you must include in your Checkout API request to use the feature as well as additional optional information that can be included in your request.

• The Submitting Valid API Requests section explains several cases in which Google will reject a Checkout API request that uses carrier-calculated shipping even though the request is valid according to the Google Checkout XML schema.

• The HTML Examples for Carrier-calculated Shipping provides several different HTML examples that show how you would provide carrier-calculated shipping in a Checkout API request.

• The HTML Parameter Definitions section defines the HTML hidden input parameters used for carrier-calculated shipping.

Note: This feature is only supported for shipments sent to and from U.S. postal addresses. In addition, any costs associated with carrier-calculated shipping methods must be specified in U.S. dollars (USD).

Understanding Carrier-calculated Shipping

When you submit a Checkout API request that includes carrier-calculated shipping methods, Google will dynamically determine the shipping rate for each of those methods. You can offer one or more carrier-calculated shipping methods and you can also offer carrier-calculated shipping methods from multiple carriers.

Please note that Google calculates shipping rates based on the assumption that all of the items in an order will be shipped in a single box. Google determines the total package weight by adding the weights of all of the items in the order. Typically, carriers will round the total order weight up to the nearest pound to determine shipping costs.

After calculating the shipping rates, Google will display those rates to buyers on the Place Order page along with the rates for any flat-rate shipping options specified in the request. If the buyer changes the shipping address, Google will use the new address to recalculate the shipping rates for each carrier-calculated shipping method. Note: If you offer flat-rate shipping options as well as carrier-calculated shipping options, the flat-rate shipping options must have different names than the carrier-calculated options that you offer. For example, if you offer the carrier-calculated shipping option for FedEx Standard Overnight shipping, you cannot also have a flat-rate shipping option named Standard Overnight.

If you have implemented the Notification API, Google will send you a new order notification after the customer places the order. If the customer has selected a carrier-calculated shipping option, the notification will include a carrier-calculated shipping adjustment identifying the selected shipping method and the calculated shipping rate.

Required Information for Using Carrier-Calculated Shipping

To use carrier-calculated shipping, you must include the following information in your Checkout API request:

• The weight of each item in the order.

• A list of carrier-calculated shipping options that are available for the order. For each option, you must provide the following information:

  • The shipping company for the order. Google supports FedEx, UPS and USPS.
  • The type of shipping method being offered. The list of valid shipping types varies for each carrier.
  • The default cost for the shipping option. The default cost will be assessed if Google's attempt to obtain the carrier's shipping rates fails for any reason.

• The address from which you will ship the order.

Optional Information for Using Carrier-Calculated Shipping

You can also specify the following additional information for carrier-calculated shipping:

• A percentage amount that the calculated shipping rate returned from the carrier should be increased or decreased. For example, some merchants may increase shipping rates by a small percentage while others may pass negotiated discounts with shipping carriers on to their customers.

• A fixed charge for the order. In this document, the term "fixed charge" refers to a fixed amount that you add to the cost of an order when a particular shipping method is selected.

• An indication of how the carrier will pick up the package. Supported carrier pickup types are REGULAR_PICKUP, SPECIAL_PICKUP and DROP_OFF. The pickup type may affect shipping rates.

• The dimensions – heightlength and width – of the package that you will ship. Package dimensions may affect shipping rates.

• An indication of whether the delivery address is a commercial or a residential location. This value may affect shipping rates.

Additional Information to Consider when Using Carrier-calculated Shipping

• As discussed earlier, Google calculates shipping rates based on the assumption that all of the items in an order will be shipped in a single box. Google determines the total package weight by adding the weight of each item in the order and then rounding up to the nearest pound. However, if you typically ship items in separate packages rather than a single package, Google's calculated shipping rate may vary significantly from what you actually pay the carrier to ship the order. For example, the costs of shipping one 150 lb. package, three 50 lb. packages, or ten 15 lb. packages may be significantly different even though each scenario has the same total shipment weight.

• Shipping carriers typically impose a weight limit of 150 lbs. per package. Items heavier than 150 lbs. are generally subject to overweight charges. If the total weight of an order exceeds 150 lbs. and you would typically ship the order in multiple packages, Google may not be able to accurately calculate shipping costs. Please note that the weight limit for USPS is 70 lbs.

Submitting Valid XML Requests Using Carrier-calculated Shipping

When you post a Checkout API request, Google verifies that your request is valid. If the request is invalid, Google Checkout will reject the shopping cart.

In addition, Google Checkout performs several other checks to verify the integrity of the information in the request. Several of these checks are explained in the Submitting Valid Checkout API Requests section of the Google Checkout HTML API Developer's Guide. If the request does not pass these checks, Google Checkout will reject the shopping cart. However, these checks cannot be enforced through the Google Checkout XML schema. As such, a request that is valid according to the XML schema will still be rejected if it fails to pass any of these tests.

The list below identifies additional checks that Google performs to ensure that requests that use carrier-calculated shipping are valid:

• If your API request includes carrier-calculated shipping methods, you must provide the weight of each item in the order.

• Carrier-calculated shipping may not be combined with pickup shipping options.

HTML Examples for Carrier-calculated Shipping

The HTML examples below explain two use cases for implementing carrier-calculated shipping. Please note that the first example includes a complete Checkout API request. However, the remaining examples only include the HTML parameters for the carrier-calculated shipping options. Each shipping method specifies that the order will be shipped from New York City.

In the examples, each HTML parameter name links to a definition for the parameter. Links shown in bold text identify parameters that are defined in this document. Remaining links point to parameter definitions in the HTML Parameter Definitions document.

Example 1 – Multiple Shipping Options and Business Rules

In this example, the merchant offers two carrier-calculated shipping methods for the order. The one-day shipping method ships with FedEx. The merchant also adds a $6.00 fixed charge for this shipping method but gives a 10 percent discount on the FedEx shipping charges. The two-day method ships with UPS. The merchant adds a $10.00 fixed charge for this shipping method but but gives a 15 percent discount on the UPS shipping charges. The example also specifies the dimensions of the packaging that will be used to ship the order.

As in the previous example, the Checkout API request must also specify the weight of all items in the order.

<input type="hidden" name="item_name_1" value="5 lbs. Dog Food"/>
<input type="hidden" name="item_description_1"
  value="5 lb. bag of nutritious Dog Food"/>
<input type="hidden" name="item_price_1" value="35.00"/>
<input type="hidden" name="item_currency_1" value="USD"/>
<input type="hidden" name="item_quantity_1" value="1"/>
<input type="hidden" name="item_merchant_id_1" value="5LBDOGCHOW"/>
<input type="hidden" name="shopping-cart.items.item-1.item-weight.value"
  value="5.5"/>
<input type="hidden" name="shopping-cart.items.item-1.item-weight.unit"
  value="LB"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.price"
  value="10.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.price.currency"
  value="USD"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.shipping-company"
  value="FedEx"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.carrier-pickup"
  value="REGULAR_PICKUP"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.shipping-type"
  value="Priority Overnight"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.additional-fixed-charge"
  value="6.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.additional-fixed-charge.currency"
  value="USD"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.additional-variable-charge-percent"
  value="-10"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.price"
  value="10.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.price.currency"
  value="USD"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.shipping-company"
  value="UPS"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.carrier-pickup"
  value="REGULAR_PICKUP"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.shipping-type"
  value="Second Day Air"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.additional-fixed-charge"
  value="10.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.additional-fixed-charge.currency"
  value="USD"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.additional-variable-charge-percent"
  value="-15"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.height.unit"
  value="IN"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.height.value"
  value="6"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.length.unit"
  value="IN"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.length.value"
  value="24"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.width.unit"
  value="IN"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.width.value"
  value="15"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.ship-from.id"
  value="ABC"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.ship-from.city"
  value="New York"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.ship-from.region"
  value="NY"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.ship-from.country-code"
  value="US"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.ship-from.postal-code"
  value="10022"/>



<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.0400"/>

<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="NY"/>

Example 2 – Combining Carrier-calculated Shipping with Flat-rate Shipping

In this example, the merchant offers two carrier-calculated shipping methods and two flat-rate shipping methods. The example does not specify the dimensions of the packaging that will be used to ship the order. The second flat-rate shipping option is for free shipping.

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.price"
  value="10.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.price.currency"
  value="USD"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.shipping-company"
  value="FedEx"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.carrier-pickup"
  value="REGULAR_PICKUP"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-1.shipping-type"
  value="Priority Overnight"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.price"
  value="10.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.price.currency"
  value="USD"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.shipping-company"
  value="UPS"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.carrier-pickup"
  value="REGULAR_PICKUP"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.shipping-type"
  value="Second Day Air"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.additional-fixed-charge"
  value="10.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.additional-fixed-charge.currency"
  value="USD"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-2.additional-variable-charge-percent"
  value="-15"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.ship-from.id"
  value="ABC"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.ship-from.city"
  value="New York"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.ship-from.region"
  value="NY"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.ship-from.country-code"
  value="US"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-1.ship-from.postal-code"
  value="10022"/>

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.name"
  value="USPS Priority Mail"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.price"
  value="4.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.price.currency"
  value="USD">

<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.name"
  value="Free Shipping"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price"
  value="0.00"/>
<input type="hidden"
  name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price.currency"
  value="USD">

HTML Parameter Definitions

The following tables define the XML tags used for the carrier-calculated shipping feature.

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