The regions
service allows you to create and manage geographic regions that
you can use as targets with both the
regionalinventory
and shippingsettings
services. You can define regions as collections of either postal codes or, in
some countries, using predefined
geotargets. This guide provides
examples of how to define each type of region, as well how to create a regional
pricing override. For additional information about the regions
service,
including all available methods and parameters, see the reference documentation.
Region eligibility
When you create a region, the regions service determines whether you can use the
region with other Content API services. The response object returned for a
successful regions.create
call includes two boolean fields,
regionalInventoryEligible
and shippingEligible
, which indicate whether you
can use the region with the regionalinventory
and shippingsettings
services,
respectively.
regionalInventoryEligible
To be eligible for use with the regionalinventory
service, a region must meet
the following criteria:
- The
regionId
, which you specify when creating a region, must contain only digits and must contain at least 6 digits. - The region must meet minimum size requirements for geographic area and online population.
shippingEligible
To be eligible for use with the shippingsettings
service, a region must meet
the following criteria:
- The region must be defined using postal codes.
- The region must be part of a country supported by the
shippingsettings
service.
Example: Create a region using postal codes
You can use the regions.create
method to create a region defined as a collection of postal codes. The example
below creates a new region for the US state of Arizona by specifying a range of
postal codes.
To create the region, make a POST
request with the following URL and request
body:
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=456789
{
postalCodeArea: {
regionCode: "US",
postalCodes: [
{
begin: "850*",
end: "860*"
}
]
}
}
Example: Create a region using geotargets
For regions in Brazil and Russia, you can also use the regions.create
method
to create a region defined as a collection of geotargets, which are predefined
geographic areas. Examples of geotarget types include countries, states, cities,
neighborhoods, and airports. However, the regions
service currently only
supports the “State” type for Brazil and the “Region” type for Russia. To
download a csv file of all geotarget IDs, including the geotargets that can be
used with the regions
service, see
Geotargets. The example below creates
a new region by providing the geotarget IDs of three Brazilian states.
To create the region, make a POST
request using the following URL and request
body:
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=123456
{
geoTargetAreas: {
geotargetCriteriaId: [20106, 20102, 20101] //Sao Paulo, Rio de Janeiro, Parana
}
}
Example: Use regions to create regional price overrides
When you create a region, the regions
service returns an response object that
includes a regionId
and two eligibility status fields. If the
regionalInventoryEligible
value is true
, you can use the regionaliventory
service to create an override that sets a different price for the region. The
example below creates a regional price override using the postal-code-based
region created in the example above, which has a regionId
of “456789”.
To create the override, make a POST
request using the following URL and
request body:
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/{productId}/regionalinventory
{
“regionId”: "456789"
“price”: {
value: “10”
currency: “USD”
},
“availability”: “in stock”
}