| Note: This is the latest documentation. The previous version of this page is identical — only the left nav differs. |
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 XML API.
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.
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 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.
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.
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> tag.
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> element. 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.
The XML examples below demonstrate several use cases for implementing merchant-calculated shipping. Please note that the first example includes a complete Checkout API request. However, the remaining 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 an order for a U.S. merchant with one item and 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.
<shipping-methods>
<merchant-calculated-shipping name="UPS Next Day Air">
<price currency="USD">20.00</price>
<address-filters>
<allow-us-po-box>false<allow-us-po-box>
</address-filters>
</merchant-calculated-shipping>
<merchant-calculated-shipping name="UPS Ground">
<price currency="USD">15.00</price>
</merchant-calculated-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 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 XML 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.
<shipping-methods>
<merchant-calculated-shipping name="UPS Next Day Air">
<price currency="USD">20.00</price>
<address-filters>
<allow-us-po-box>false<allow-us-po-box>
</address-filters>
<shipping-restrictions>
<excluded-areas>
<us-state-area>
<state>AK</state>
</us-state-area>
<us-state-area>
<state>HI</state>
</us-state-area>
</excluded-areas>
</shipping-restrictions>
</merchant-calculated-shipping>
<merchant-calculated-shipping name="UPS Ground">
<price currency="USD">15.00</price>
</merchant-calculated-shipping>
</shipping-methods>
Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:
| address-filters | |
| Definition | The <address-filters> tag identifies areas where a particular merchant-calculated shipping method is available or unavailable. Address filters are applied before Google Checkout sends a <merchant-calculation-callback> to the merchant. Google Checkout will not ask you to calculate the cost of a particular shipping method for an address if the address filters in the Checkout API request indicate that the method is not available for the address. |
| Subtag of | merchant-calculated-shipping |
| Subtags | allow-us-po-box?, allowed-areas, excluded-areas? |
| API Commands | Checkout |
| Content Format | Container |
| Example | <address-filters>false</address-filters> |
| 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> |
| merchant-calculated-shipping | |||||||
| Definition | The <merchant-calculated-shipping> tag contains information about a shipping option in which Google Checkout communicates with the merchant after the shopping cart items are posted and the buyer has selected a shipping address. You may ignore this tag if you are not implementing the Merchant Calculations API, which allows merchants to use a custom process to determine taxes, shipping costs and discounts for an order after the customer has selected a shipping address. |
||||||
| Attributes |
|
||||||
| Subtag of | shipping-methods | ||||||
| Subtags | price, address-filters?, shipping-restrictions? | ||||||
| API Commands | Checkout | ||||||
| Content Format | Container | ||||||
| Example | <merchant-calculated-shipping name="FedEx 2-day"> | ||||||
| merchant-calculations | |
| Definition | The <merchant-calculations> tag contains information about calculations that will be performed by the merchant. |
| Subtag of | merchant-checkout-flow-support |
| Subtags | merchant-calculations-url, accept-merchant-coupons?, accept-gift-certificates? |
| API Commands | Checkout |
| Content Format | Container |
| Example | <merchant-calculations> |
| 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> |