| Note: This is the latest documentation. The previous version of this page is identical — only the left nav differs. |
Google Checkout defines flat-rate shipping options as options for which a change in the shipping address does not affect the shipping cost. Flat-rate shipping options are a good solution for merchants who do not calculate shipping rates based on the total weight of the order or on the buyer's shipping address.
This document explains how to include flat-rate shipping options in a Checkout API request. It also explains how to set shipping restrictions to limit the geographic areas where a flat-rate shipping option is available. Finally, this document provides several HTML examples that demonstrate how you would provide flat-rate shipping options for several different shipping scenarios.
Shipping restrictions allow you to limit 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:
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.
The following checklist will help you to ensure that you have correctly implemented flat-rate shipping.
Checkout API requests may not include two or more shipping methods that have the same name. As such, you must specify a unique name for each shipping method that you offer. Shipping method names are specified using the name hidden input parameter. To verify that all names are unique, Google Checkout trims whitespace characters from the beginning and the end of the name string. Google Checkout then does a case-insensitive comparison of the names to ensure that they are unique. For example, Google Checkout would consider all of these names to be identical:
|
Regular shipping
REGULAR SHIPPING
Regular shipping
ReGuLaR sHiPPing
Verify that you have specified the correct shipping cost using the price element. If you offer more than one flat-rate shipping option in your Checkout API request, you must specify the price for each of those options. If you do not specify a price for a shipping option, Google will not add shipping charges if the buyer selects that shipping option.
The HTML examples below demonstrate several use cases for implementing flat-rate shipping. Please note that the examples only include the HTML input parameters relevant to the shipping methods for the sample orders.
The following example shows two flat-rate shipping methods. The first shipping method, which is for UPS Next Day Air shipping, costs $20.00. The second option, which is for UPS Ground Shipping, costs $15.00.
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.name" value="UPS Next Day Air"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.price" value="20.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="UPS Ground"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price" value="15.00"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price.currency" value="USD"/>
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 both shipping methods. These restrictions specify that neither option will be offered if the shipping address is a P.O. box. In addition, the next-day shipping option will also be unavailable if 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:
Google Checkout will not allow the buyer to complete the order if the selected shipping address is a P.O. box.
If the buyer selects a shipping address in Alaska or Hawaii (that is not a P.O. box), then Google Checkout will only offer the second shipping option (for ground shipping) to the buyer.
If the buyer selects any shipping address that is not a P.O. box and is not in Alaska or Hawaii, then Google Checkout will offer both shipping options to the buyer.
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.name" value="UPS Next Day Air"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.price" value="20.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-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.flat-rate-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.flat-rate-shipping-1.shipping-restrictions.allow-us-po-box" value="false"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.name" value="UPS Ground"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price" value="15.00"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price.currency" value="USD"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.shipping-restrictions.allow-us-po-box" value="false"/>
This example demonstrates how you could offer free delivery using a flat-rate shipping method. The example also includes a pickup shipping method. In this example, the request uses shipping restrictions to specify that delivery is only available in two zip codes in Manhattan's Upper East Side neighborhood. You can charge a fee for delivery by setting the value of the price parameter to the delivery fee amount.
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.name" value="Delivery"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.price" value="0.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-1.shipping-restrictions.allowed-areas.us-zip-area-1.zip-pattern" value="10021"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.shipping-restrictions.allowed-areas.us-zip-area-2.zip-pattern" value="10022"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.shipping-restrictions.allow-us-po-box" value="false"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.pickup-1.name" value="Pickup"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.pickup-1.price" value="0.00"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.pickup-1.price.currency" value="USD"/>
| allow-us-po-box |
The allow-us-po-box parameter 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 parameter with a value of false in the shipping-restrictions for the shipping option. The default value for this parameter is true. Associated recurring elements The flat-rate-shipping element needs to be numbered to associate the shipping restriction (or address filter) with the appropriate shipping method.
API commands Content format for parameter value Boolean
Sample use(s)
<input type="hidden" name="checkout-flow-support.
|
| country-area |
| The country-area parameter identifies a region of the United States. Valid values for this parameter 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. Associated recurring elements When the country-area parameter is associated with a shipping method, the us-country-area and flat-rate-shipping elements need to be numbered. When the country-area parameter is associated with a default tax table, the default-tax-rule and us-country-area elements must both be numbered. When the country-area parameter is associated with an alternate tax table, the alternate-tax-table, alternate-tax-rule and us-country-area elements must all be numbered.
API commands Content format for parameter value String
Sample use(s)
<input type="hidden" name="checkout-flow-support.
<input type="hidden" name="checkout-flow-support. <input type="hidden" name="checkout-flow-support. |
| currency |
| The currency parameter identifies the unit of currency associated with a price, shipping cost or other monetary value. Every monetary value in a Google Checkout API request must specify the currency associated with that value. The value of the currency parameter must be a three-letter ISO 4217 currency code.
Associated recurring elements The currency parameter includes recurring elements any time the monetary value associated with the currency also contains a recurring element. For example, in a Checkout API request, the unit-price parameter identifies the price of an item and contains the recurring item element. As such, the currency associated with the unit-price parameter value will also contain the repeating price parameter.
API commands Checkout, Charge Order, Refund Order, New Order Notification, Charge Amount Notification, Refund Amount Notification, Chargeback Amount Notification, Authorization Amount Notification
Content format for parameter value String
Sample use(s) In a Checkout API request:
item type="hidden" name="shopping-cart.items.item-1.unit-price" value="12.99" item type="hidden" name="shopping-cart.items.item-1.unit-price.currency" value="USD" In a new order notification: order-adjustment.total-tax=1.38&order-adjustment.total-tax.currency=USD In a refund order request: amount=12.99&amount.currency=USD |
| name |
In a Checkout API request, the name parameter value contains a string that can be used to identify a tax table or shipping method. The parameter value must be at least one non-space character and may not be longer than 255 characters. The name parameter can also be used in a Checkout API request to identify the name of a query string parameter that will be included in a web beacon URL for third-party conversion tracking. The parameter's value is the name that the third-party tracking provider uses in its web beacon URLs. In a new order notification, the name parameter specifies the name that Google uses to identify a promotion in the Merchant Center. Associated recurring elements When the name parameter specifies the name of a query string parameter that will be included in a web beacon URL for third-party conversion tracking, the parameterized-url element must be numbered to associate the URL with a particular web beacon. In addition, the url-parameter element must be numbered so that the parameter name may be associated with the parameter value, which is expressed using the type parameter. When the name parameter is associated with an alternate tax table, the alternate-tax-table element must be numbered. When the name parameter is associated with a shipping method in a Checkout API request, either the flat-rate-shipping or pickup element needs to be numbered. Finally, when the name parameter is associated with a promotion, the promotion element must be numbered so that the promotion name can be associated with a specific promotion. Content format for parameter value String
Sample use(s) Identifying a shipping method in a Checkout API request:
input type="hidden" name="checkout-flow-support. Identifying a tax table in a Checkout API request: input type="hidden" name="checkout-flow-support. Identifying a URL parameter in a Checkout API request: input type="hidden" name="checkout-flow-support. Identifying a promotion in a new order notification: promotions. |
| postal-code-pattern |
The postal-code-pattern parameter 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. Associated recurring elements When the postal-code-pattern parameter is associated with a shipping method, the postal-area and flat-rate-shipping elements need to be numbered. When the postal-code-pattern parameter is associated with a default tax table, the default-tax-rule and postal-area elements must both be numbered. When the postal-code-pattern parameter is associated with an alternate tax table, the alternate-tax-table, alternate-tax-rule and postal-area elements must all be numbered.
API commands Content format for parameter value String
Sample use(s)
<input type="hidden" name="checkout-flow-support.
<input type="hidden" name="checkout-flow-support. <input type="hidden" name="checkout-flow-support. |
| price |
The price parameter contains the cost to ship an order using a particular shipping method. Associated recurring elements The parameter name must contain either the flat-rate-shipping or pickup elements, and that element must be numbered to associate the price with a particular shipping method.
API commands Content format for parameter value Decimal
Sample use(s)
<input type="hidden" name="checkout-flow-support.
<input type="hidden" name="checkout-flow-support. |
| state |
The state parameter identifies a state where a particular tax rule is applied or where a particular shipping option is available or unavailable. Associated recurring elements When the state parameter is associated with a shipping method, the us-state-area and flat-rate-shipping elements need to be numbered. When the state parameter is associated with a default tax table, the default-tax-rule and us-state-area elements must both be numbered. When the state parameter is associated with an alternate tax table, the alternate-tax-table, alternate-tax-rule and us-state-area elements must all be numbered.
API commands Content format for parameter value String
Sample use(s)
<input type="hidden" name="checkout-flow-support.
<input type="hidden" name="checkout-flow-support. <input type="hidden" name="checkout-flow-support. |
| world-area |
The world-area parameter represents the entire world. This parameter indicates that a shipping option is available worldwide or that a particular tax rule applies worldwide. For shipping options, the world-area parameter can only appear as a subtag of the allowed-areas parameter. (Including the world-area parameter as a subtag of the excluded-areas parameter would make the corresponding shipping option unavailable to all shipping addresses.) However, you can use the world-area parameter 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 parameter 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 parameter for tax rules. Associated recurring elements When the world-area parameter is associated with a shipping method, the world-area and flat-rate-shipping elements need to be numbered. When the world-area parameter is associated with a default tax table, the default-tax-rule and world-area elements must both be numbered. When the world-area parameter is associated with an alternate tax table, the alternate-tax-table, alternate-tax-rule and world-area elements must all be numbered.
API commands Content format for parameter value Complex
Sample use(s)
<input type="hidden" name="checkout-flow-support.
<input type="hidden" name="checkout-flow-support. <input type="hidden" name="checkout-flow-support. |
| zip-pattern |
The zip-pattern parameter 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. Associated recurring elements When the zip-pattern parameter is associated with a shipping method, the us-zip-area and flat-rate-shipping elements need to be numbered. When the zip-pattern parameter is associated with a default tax table, the default-tax-rule and us-zip-area elements must both be numbered. When the zip-pattern parameter is associated with an alternate tax table, the alternate-tax-table, alternate-tax-rule and us-zip-area elements must all be numbered.
API commands Content format for parameter value String
Sample use(s)
<input type="hidden" name="checkout-flow-support.
<input type="hidden" name="checkout-flow-support. <input type="hidden" name="checkout-flow-support. |