A Merchant API region represents a geographic region that you can use as a
target related to the accounts.products.regionalInventories resource. You can
define regions as collections of either postal codes or, in some countries,
using predefined geotargets. For more information, see Set up
regions.
Merchant API provides batch endpoints for managing your regions, allowing you to create, update, and delete up to 100 regions in a single API call. This is ideal for merchants managing regional availability and pricing (RAAP) at scale, improving efficiency and simplifying integration.
Overview
Batch API lets you accomplish the following with the associated methods:
- Create multiple regions in a single request:
regions:batchCreate - Delete multiple regions at once:
regions:batchDelete - Update multiple regions simultaneously:
regions:batchUpdate
Prerequisites
All batch requests require the ADMIN user role for authentication.
Create multiple regions
This example shows how to create two new regions — one defined by postal codes
and another by geo targeting — in a single call of BatchCreateRegions.
Request
Construct the request URL as follows:
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate
The request body contains a list of requests, where each object specifies a
regionId and the region data to create.
{
"requests": [
{
"regionId": "seattle-area-98340",
"region": {
"displayName": "Seattle Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98340"
}
]
}
}
},
{
"regionId": "co-de-states",
"region": {
"displayName": "Colorado and Delaware",
"geoTargetArea": {
"geotargetCriteriaIds": [
"21138",
"21141"
]
}
}
}
]
}
Response
A successful request returns a list of the new region objects.
{
"regions": [
{
"name": "accounts/{ACCOUNT_ID}/regions/seattle-area-98340",
"displayName": "Seattle Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98340"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
},
{
"name": "accounts/{ACCOUNT_ID}/regions/co-de-states",
"displayName": "Colorado and Delaware",
"geotargetArea": {
"geotargetCriteriaIds": [
"21138",
"21141"
]
},
"regionalInventoryEligible": false,
"shippingEligible": false
}
]
}
Update multiple regions
This example shows how to use BatchUpdateRegions to update the displayName
and postalCodeArea for two existing regions. You must supply a region.name
to update the targeted region.
Request
Construct the request URL as follows:
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
The request body contains a list of requests. Each object must specify the
region data to update. The region.name field must contain the ID of the
region to update, for example,"98005". Specify the resource as name rather
than accounts/{ACCOUNT_ID}/regions/name. Including updateMask to indicate
the fields to change is optional.
{
"requests": [
{
"region": {
"name": "98005",
"displayName": "Seattle Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98330"
}
]
}
},
"updateMask": "displayName,postalCodeArea"
},
{
"region": {
"name": "07086",
"displayName": "NewYork Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "11*"
}
]
}
},
"updateMask": "displayName,postalCodeArea"
}
]
}
Response
A successful request returns a list of the updated region objects.
{
"regions": [
{
"name": "accounts/{ACCOUNT_ID}/regions/98005",
"displayName": "Seattle Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98330"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
},
{
"name": "accounts/{ACCOUNT_ID}/regions/07086",
"displayName": "NewYork Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "11*"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
}
]
}
Delete multiple regions
You can delete multiple regions in a single call.
Request
This example shows how to use BatchDeleteRegions to delete two regions in a
single call.
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete
The request body contains a list of requests, where each object specifies the
name (without "accounts/{ACCOUNT_ID}/regions/") of the region to delete.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Response
A successful request returns an empty response body, indicating that the specified regions were deleted (or did not exist).
{}
Limitations
Before you begin, keep these rules in mind:
- Atomic operations: Batch requests are atomic. If any single operation within the batch fails (for example, one region fails to be created), the entire batch will fail, and no changes will be made. The API will return an error detailing the cause of the failure.
- Batch limits: Each batch request can contain a maximum of 100 region operations.
- Quotas: These endpoints use the same quota groups as their
single-operation counterparts (
regions.create,regions.delete,regions.update).
Common errors and issues
Here are a few common pitfalls and their solutions.
"The number of requests in a batch is too large"
This error occurs if the number of operations in your requests array exceeds the limit of 100.
"error":
{
"code": 400,
"message": "The number of requests in a batch is too large.",
"status": "INVALID_ARGUMENT"
}
To fix this, split your operations into multiple batch requests of 100 or fewer.
Required field is missing
This error occurs when a required field is missing. The error message specifies the missing parameter.
The error messages are as follows:
- For
batchCreate:[regionId] Required parameter: regionId - For
batchUpdate:[region.name] Required field not provided. - For
batchDelete:[name] Required parameter: name
To fix this, verify all required fields are present in each operation. For
example, every entry in a batchUpdate request must include the region.name.
Posting the following request results in an error:
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
"Region with specified ID already exists"
An error occurs if you try to create a region with a regionId that already
exists.
The error message is [regionId] Region with specified id already exists..
To fix this, verify that all regionId values are unique within the batch and
don't conflict with existing regions.
"Duplicate value found for field region.name or regionId found"
An error occurs if you try to create or update multiple regions with the same ID within a single batch request.
The error message is Duplicate value found for field {fieldName} in this batch
request with value {duplicated_value}..
To fix this, verify that all regionId (for batchCreate) or region.name
(for batchUpdate) values are unique within a single batch request.
"Item not found"
When using batchUpdate, if any region specified in the request does not exist,
the entire batch will fail with a 404 NOT_FOUND error. This is different from
batchDelete, which succeeds for nonexistent regions.
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
To fix this, verify that all regions you are attempting to update exist before sending the request.