| Note: This is the latest documentation. The previous version of this page is identical — only the left nav differs. |
The following list explains the different tags that Google Checkout provides for specifying geographic areas. These tags are used to define both the areas where shipping options are available and the areas where tax rules are applied. In addition, the last tag in the list, <allow-us-po-box>, allows merchants to limit the availability of shipping options if the shipping address is a U.S. post-office (P.O.) box. The <allow-us-po-box> tag is not used to define areas where tax rules are applied.
<world-area> - This tag represents the entire world. This tag has no attributes and does not contain any other elements.
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. See the XML Examples section to see a feed excerpt that uses the <world-area> tag for shipping areas.
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 Ordering Tax Rules in API Requests section of the XML API Developer's Guide to see a feed excerpt that demonstrates how the ordering of tax rules affects the tax rule selected for an order.
<postal-area> - This tag contains information about a geographic area. You can use the <postal-area> tag to identify any country in the world, including the United States. You can also specify regions by postal codes. The following list identifies subtags of the <postal-area> tag.
<country-code>* - Required. This tag contains the two-letter ISO 3166-1 country code for the postal area.
<postal-code-pattern>* - Optional. This tag identifies a postal code or a range of postal codes for the postal area. To specify a range of postal codes, use an asterisk as a wildcard operator in the tag's value. For example, you can specify that a shipping option is available for all postal codes beginning with "SW" by entering SW* as the <postal-code-pattern> value.
Each postal area must specify a unique geographic region. For example, a merchant who ships to only two cities or regions in a particular country must create a separate postal area for each region. However, if the merchant ships to all addresses in that country, the merchant can create a single postal area that does not include the <postal-code-pattern> tags. For more information, see the XML Examples section of this document.
<us-country-area> - This tag identifies a region of the United States. This tag requires the country-area attribute, which identifies the region of the United States. The following list identifies valid values for the country-area attribute:
The <us-state-area> tag contains a U.S. state. The <us-state-area> tag has one required subtag, <state>, which identifies the state where a shipping method is available or a tax rule is applied.
The <us-zip-area> tag contains a zip code or range of zip codes. This tag has one required subtag, <zip-pattern>, which specifies the zip code or zip code range where a shipping method is available or a tax rule is applied.
The <allow-us-po-box> tag indicates whether a shipping option is available if the shipping address is a P.O. box in the United States. By default, shipping options are available if the shipping address is a P.O. box.
The first three XML examples below demonstrate how to use the Checkout API tags for specifying geographic areas. All three examples show merchant-calculated shipping methods and that each example uses address filters. The fourth example demonstrates how geographic area tags are used in tax rules.
Note: If you are using flat-rate or pickup shipping methods, you can modify Examples 1 and 2 to work with your shipping methods by replacing the <address-filters> tags with <shipping-restrictions> tags.
The following XML excerpt is from a Checkout API request that contains one shipping method that can be used to ship to all U.S. postal addresses except for P.O. box addresses. This example also uses the <allow-us-po-box> tag to restrict shipping to P.O. boxes.
|
<shipping-methods>
<merchant-calculated-shipping name="SuperShip International">
<price currency="USD">11.00</price>
<address-filters>
<allowed-areas>
<us-country-area country-area="ALL"/>
</allowed-areas>
<allow-us-po-box>false</allow-us-po-box>
</address-filters>
</merchant-calculated-shipping>
</shipping-methods>
The following XML excerpt is from a Checkout API request that contains one shipping method that is available everywhere except North Korea:
<shipping-methods>
<merchant-calculated-shipping name="SuperShip International">
<price currency="USD">14.00</price>
<address-filters>
<allowed-areas>
<world-area/>
</allowed-areas>
<excluded-areas>
<postal-area>
<country-code>KP</country-code>
</postal-area>
</excluded-areas>
</address-filters>
</merchant-calculated-shipping>
</shipping-methods>
The following XML excerpt is from a Checkout API request that contains two shipping methods. The first shipping method is only available in Canada but is not available in Nunavut and the Northwest Territories if the <merchant-calculation-callback> request fails. The second shipping method is also only available in Canada but is not available in Nunavut and the Northwest Territories under any circumstances. Both shipping methods use address filters to restrict shipping options based on address, and the first shipping method also uses shipping restrictions to enforce different rules depending on whether the <merchant-calculation-callback> request is successful.
Note: Canadian postal codes for Nunavut and the Northwest Territories begin with the letter "X".
<shipping-methods>
<merchant-calculated-shipping name="Canada Ground">
<price currency="CAD">30.00</price>
<address-filters>
<allowed-areas>
<postal-area>
<country-code>CA</country-code>
</postal-area>
</allowed-areas>
</address-filters>
<shipping-restrictions>
<excluded-areas>
<postal-area>
<country-code>CA</country-code>
<postal-code-pattern>X*</postal-code-pattern>
</postal-area>
</excluded-areas>
</shipping-restrictions>
</merchant-calculated-shipping>
<merchant-calculated-shipping name="Canada Air">
<price currency="CAD">20.00</price>
<address-filters>
<allowed-areas>
<postal-area>
<country-code>CA</country-code>
</postal-area>
</allowed-areas>
<excluded-areas>
<postal-area>
<country-code>CA</country-code>
<postal-code-pattern>X*</postal-code-pattern>
</postal-area>
</excluded-areas>
</address-filters>
</merchant-calculated-shipping>
</shipping-methods>
The XML excerpt below shows the proper syntax for indicating that you charge 7 percent tax in Mississippi, Rhode Island and Tennessee. The XML shows that in Rhode Island and Tennessee, tax rates also apply to shipping charges.
<default-tax-table>
<tax-rules>
<default-tax-rule>
<rate>0.07</rate>
<tax-area>
<us-state-area>
<state>MS</state>
</us-state-area>
</tax-area>
</default-tax-rule>
<default-tax-rule>
<shipping-taxed>true</shipping-taxed>
<rate>0.07</rate>
<tax-areas>
<us-state-area>
<state>RI</state>
</us-state-area>
<us-state-area>
<state>TN</state>
</us-state-area>
</tax-areas>
</default-tax-rule>
</tax-rules>
</default-tax-table>