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](https://google.aip.dev/) 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](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.regions)
- [Regions guide](https://developers.google.com/merchant/api/guides/accounts/regions)
- [Set up regions](https://support.google.com/merchants/answer/7410946#zippy=%2Ccreate-a-new-regionS)