| 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 XML examples that demonstrate how you would use flat-rate shipping options for several different shipping scenarios.
Note: You can combine flat-rate shipping options with carrier-calculated shipping options. However, you cannot combine flat-rate shipping options with merchant-calculated shipping options.
The Checkout API's shipping restrictions feature allows 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 XML tags 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 contained in the name attribute value of the <flat-rate-shipping> tag. 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
Ensure that your Checkout API request does not mix flat-rate shipping options with merchant-calculated shipping options.
Verify that you have specified the correct shipping cost using the 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 XML examples below demonstrate several use cases for implementing flat-rate shipping. Please note that the examples only include the XML within the <shipping-methods> tag. In the examples, each XML tag name links to a definition for the tag..
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.
<shipping-methods>
<flat-rate-shipping name="UPS Next Day Air">
<price currency="USD">20.00</price>
</flat-rate-shipping>
<flat-rate-shipping name="UPS Ground">
<price currency="USD">15.00</price>
</flat-rate-shipping>
</shipping-methods>
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 XML 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.
<shipping-methods>
<flat-rate-shipping name="UPS Next Day Air">
<price currency="USD">20.00</price>
<shipping-restrictions>
<excluded-areas>
<us-state-area>
<state>AK</state>
</us-state-area>
<us-state-area>
<state>HI</state>
</us-state-area>
</excluded-areas>
<allow-us-po-box>false</allow-us-po-box>
</shipping-restrictions>
</flat-rate-shipping>
<flat-rate-shipping name="UPS Ground">
<price currency="USD">15.00</price>
<shipping-restrictions>
<allow-us-po-box>false</allow-us-po-box>
</shipping-restrictions>
</flat-rate-shipping>
</shipping-methods>
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> tag to the delivery fee amount.
<shipping-methods>
<flat-rate-shipping name="Delivery">
<price currency="USD">0.00</price>
<shipping-restrictions>
<allowed-areas>
<us-zip-area>
<zip-pattern>10021</zip-pattern>
</us-zip-area>
<us-zip-area>
<zip-pattern>10022</zip-pattern>
</us-zip-area>
</allowed-areas>
<allow-us-po-box>false</allow-us-po-box>
</shipping-restrictions>
</flat-rate-shipping>
<pickup name="Pickup">
<price currency="USD">0.00</price>
</pickup>
</shipping-methods>
Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:
| 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> |
| flat-rate-shipping | |||||||
| Definition | The <flat-rate-shipping> tag contains information about shipping costs that do not vary depending on the address to which the order is shipped. The <flat-rate-shipping> cost can be displayed before the buyer selects the shipping address. The <flat-rate-shipping> tag could also contain information about an offer for free shipping. |
||||||
| Attributes |
|
||||||
| Subtag of | shipping-methods | ||||||
| Subtags | price, shipping-restrictions | ||||||
| API Commands | Checkout | ||||||
| Content Format | Complex | ||||||
| Example | <flat-rate-shipping> | ||||||
| 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 |
|
||||||
| 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 | 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 |
|
||||||
| 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> |