Using Regions

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: Creating 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 using the following URL and request body:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=456789

{
  postalCodes: {
    regionCode: "US"
    postalCodes: [
      {
        begin: "850*"
        end: "860*"
      }
    ]
   }
}

Example: Creating 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: Using 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”
}