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.
Обзор
API пакетной обработки позволяет выполнять следующие действия с помощью соответствующих методов:
- Создайте несколько регионов в одном запросе:
regions:batchCreate - Удаление нескольких регионов одновременно:
regions:batchDelete - Обновить несколько регионов одновременно:
regions:batchUpdate
Предварительные требования
Для аутентификации при выполнении всех пакетных запросов требуется роль пользователя ADMIN .
Создайте несколько регионов
В этом примере показано, как создать два новых региона — один, определяемый почтовыми индексами, а другой — географическим таргетингом — за один вызов функции BatchCreateRegions .
Запрос
Сформируйте URL-адрес запроса следующим образом:
POST
https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/regions:batchCreate
Тело запроса содержит список requests , где каждый объект указывает regionId и данные region для создания.
{
"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"
]
}
}
}
]
}
Ответ
В случае успешного выполнения запроса возвращается список новых объектов region .
{
"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
}
]
}
Обновление нескольких регионов
В этом примере показано, как использовать BatchUpdateRegions для обновления значений displayName и postalCodeArea для двух существующих регионов. Для обновления целевого региона необходимо указать region.name .
Запрос
Сформируйте URL-адрес запроса следующим образом:
POST https://merchantapi.googleapis.com/accounts/v1/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"
}
]
}
Ответ
В случае успешного выполнения запроса возвращается список обновленных объектов region .
{
"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
}
]
}
Удалить несколько регионов
Вы можете удалить несколько регионов за один вызов.
Запрос
В этом примере показано, как использовать BatchDeleteRegions для удаления двух регионов за один вызов.
POST
https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/regions:batchDelete
Тело запроса содержит список requests , где каждый объект указывает name (без "accounts/{ACCOUNT_ID}/regions/" ) региона, который необходимо удалить.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Ответ
В случае успешного выполнения запроса возвращается пустое тело ответа, указывающее на то, что указанные регионы были удалены (или не существовали).
{}
Ограничения
Прежде чем начать, помните об этих правилах:
- 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.
- Ограничения по пакетной обработке : каждый пакетный запрос может содержать максимум 100 операций с регионами.
- Квоты : Эти конечные точки используют те же группы квот, что и их аналоги, выполняющие одну операцию (
regions.create,regions.delete,regions.update).
Распространенные ошибки и проблемы
Вот несколько распространенных ошибок и способы их решения.
"Количество запросов в пакете слишком велико"
Эта ошибка возникает, если количество операций в массиве requests превышает лимит в 100.
"error":
{
"code": 400,
"message": "The number of requests in a batch is too large.",
"status": "INVALID_ARGUMENT"
}
Чтобы исправить это, разделите ваши операции на несколько пакетных запросов по 100 или менее запросов.
Отсутствует обязательное поле.
Эта ошибка возникает, когда отсутствует обязательное поле. В сообщении об ошибке указывается отсутствующий параметр.
Сообщения об ошибках выглядят следующим образом:
- Для
batchCreate:[regionId] Required parameter: regionId - Для
batchUpdate:[region.name] Required field not provided. - Для
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"
}
]
}
"Регион с указанным идентификатором уже существует"
Ошибка возникнет, если вы попытаетесь создать регион с уже существующим regionId .
Сообщение об ошибке: [regionId] Region with specified id already exists.
Для решения этой проблемы убедитесь, что все значения regionId в рамках пакета уникальны и не конфликтуют с существующими регионами.
"Обнаружено повторяющееся значение для поля region.name или regionId"
Ошибка возникает при попытке создать или обновить несколько регионов с одним и тем же идентификатором в рамках одного пакетного запроса.
Сообщение об ошибке: Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}.
Чтобы исправить это, убедитесь, что все значения regionId (для batchCreate ) или region.name (для batchUpdate ) уникальны в рамках одного пакетного запроса.
"Элемент не найден"
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"
}
Чтобы исправить это, перед отправкой запроса убедитесь, что все регионы, которые вы пытаетесь обновить, существуют.