migration, compatibility

Migrate region management

This guide explains how to migrate your integration from the RegionsService in Content API for Shopping to the RegionsService within the Accounts sub-API.

The Regions service lets you define custom geographic areas for use cases such as regional pricing and shipping overrides. You can use regions with services like RegionalInventory and ShippingSettings.

Key differences

• API structure: The Regions service is now part of the Accounts sub-API in Merchant API (for example, merchantapi.googleapis.com/accounts/v1/...).
• Resource names: Merchant API uses resource names (accounts/{account}/regions/{region}) instead of separate merchant_id and region_id parameters in the URL path for Get, Update, and Delete operations.
• AIP compliance: Merchant API methods follow standard API Improvement Proposal patterns (such as using parent for List/Create, name for Get/Delete, and standard update_mask usage).
• Wrapper types: Fields that previously used google.protobuf.StringValue or google.protobuf.BoolValue in Content API now use standard optional fields in Merchant API.
• New features:
  • Merchant API introduces a RadiusArea type within the Region resource to define regions based on a radius around a point (initially with TRUST_TESTER visibility).
  • Batch methods - BatchCreateRegions, BatchUpdateRegions, BatchDeleteRegions - are available.
• Error handling: Error codes and messages provide more specific feedback.

Requests

Here's how request patterns change:

Item	Content API for Shopping	Merchant API	Description
Endpoint	https://shoppingcontent.googleapis.com	https://merchantapi.googleapis.com	The base domain changes.
Get Path	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	Merchant API uses the accounts sub-API and a resource name.
List Path	/content/v2.1/{merchant_id}/regions	/accounts/v1/{parent=accounts/*}/regions	Merchant API uses parent to specify the account.
Create Path	/content/v2.1/{merchant_id}/regions	/accounts/v1/{parent=accounts/*}/regions	Merchant API uses parent. region_id is a field in the request body.
Update Path	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	The resource name in Merchant API is part of the region object in the body.
Delete Path	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	Uses resource name.

Identifiers

Change your use of identifiers as follows:

Item	Content API for Shopping	Merchant API	Description
Account	merchant_id (integer)	account (integer, part of name or parent string)	Find the account ID embedded in the resource name string, for example, accounts/{account}.
Region	region_id (string)	{region} (string, part of name string)	Find the region ID embedded in the resource name string, for example, accounts/{account}/regions/{region}.
Resource Name	Not strictly used for requests.	name: accounts/{account}/regions/{region}	Standard identifier for Get/Update/Delete requests.
Parent Name	Not strictly used for requests.	parent: accounts/{account}	Standard identifier for List/Create requests.

Resources

The Region resource structure has minor changes:

Item	Content API for Shopping	Merchant API	Description
Resource Identifier	region_id (string), merchant_id (int64)	name (string): accounts/{account}/regions/{region}	Merchant API uses a single name field as the resource identifier.
display_name	google.protobuf.StringValue	optional string	Wrapper type removed.
radius_area	Not Available (N/A)	RadiusArea	This new type defines regions by radius. Includes region_code, lat_lng, radius, radius_units. By default, visibility is restricted.
regional_inventory_eligible	google.protobuf.BoolValue (output only)	optional bool (output only)	Wrapper type removed.
shipping_eligible	google.protobuf.BoolValue (output only)	optional bool (output only)	Wrapper type removed.

Methods

Change your use of methods as follows:

Item	Content API for Shopping	Merchant API	Description
Get Region	GetRegion	GetRegion	The request uses name.
Create Region	CreateRegion	CreateRegion	The request takes the parent from the URL, while the request body includes the region object and the region_id.
Update Region	UpdateRegion	UpdateRegion	The request uses region (which must include region.name) and update_mask.
Delete Region	DeleteRegion	DeleteRegion	The request uses name.
List Regions	ListRegions	ListRegions	The request uses parent. page_size and page_token behavior is consistent.
Batch Create	N/A	BatchCreateRegions	This is a new method.
Batch Update	N/A	BatchUpdateRegions	This is a new method.
Batch Delete	N/A	BatchDeleteRegions	This is a new method.

Renamed fields

Item	Content API for Shopping	Merchant API	Description
Account ID	merchant_id	account (part of name or parent)	Integrated into resource name strings. This affects Region (response) and protobuf messages used to make API requests, such as CreateRegionRequest, GetRegionRequest, UpdateRegionRequest, DeleteRegionRequest and ListRegionsRequest.
Region ID	region_id	region (part of name), region_id	Integrated into name for most, separate region_id field in CreateRegionRequest. This affects Region (response) and protobuf messages used to make API requests, such as CreateRegionRequest, GetRegionRequest, UpdateRegionRequest, DeleteRegionRequest and ListRegionsRequest.
Region Name (Output)	region_id	name	The primary identifier field in the response is now the full resource name. This affects Region.
Display Name	display_name	display_name	The type changes from StringValue to optional string. This affects Region.
Eligibility flags	...eligible	...eligible	The type changes from BoolValue to optional bool. This affects Region.
Update Mask	update_mask	update_mask	Region field paths. This affects UpdateRegionRequest.

Learn more

• Rest Resource: accounts.regions for Merchant API
• Regions guide
• Set up regions