Time	Status	User Agent
Retrieving recent requests…

Update zones in bulk

Update up to 100 zones in a single request. Each row is validated and persisted independently — a failure in one item does not block the others. The response reflects the outcome of each item individually, and the HTTP status reflects the overall result: 200 if all items succeeded, 207 if some failed, or 400 if all failed.

Each row identifies the zone to update using identifierName and identifierValue. All other fields are optional and use patch semantics: fields absent from the request JSON are left unchanged. For nullable fields, setting the value to null clears the stored value; see each field's description for fields that cannot be set to null.

Example request

curl -X PUT "https://{host}/v2/locations/zones?inheritLocale=false" \
  -H "Authorization: Basic {base64-encoded-credentials}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "identifierName": "CODE",
      "identifierValue": "zone-north",
      "name": "North Region Zone Updated",
      "description": "Updated description via bulk update",
      "customFields": {
        "cf_zone_region": "North"
      },
      "externalIds": {
        "erpId": "ERP-NORTH-01"
      }
    }
  ]'

Prerequisites

Authenticate using Basic authentication (Base64-encoded username:password).

Query parameters

Field	Type	Required	Description
`inheritLocale`	boolean	Optional	When `true`, locale fields (`language`, `currency`, `timezone`) are inherited from the zone's parent zone when not explicitly provided. Defaults to `false`.

Body parameters

Pass a JSON array of zone update objects. Maximum 100 items per request.

Note: The Updatable column indicates whether the field can be changed after creation. identifierName and identifierValue identify the target zone and are never updated themselves.

Field	Type	Required	Description	Updatable
`identifierName`	string	Required	How the target zone is identified. Must be one of: `ID` (internal system ID), `CODE` (zone code), `EXTERNAL_ID` (external identifier value). Case-insensitive.	No
`identifierValue`	string	Required	The identifier value matching `identifierName`.	No
`name`	string	Optional	Display name for the zone. Cannot be set to `null` or empty. Cannot equal `ROOT` (any case). Max 100 characters. Accepts letters, digits, underscores, and spaces.	Yes
`description`	string	Optional	Free-text description. Set to `null` to clear the stored value.	Yes
`isAdmin`	boolean	Optional	Whether the zone has admin access.	Yes
`isActive`	boolean	Optional	Whether the zone is active. Deactivation fails if any child entities (stores) are still active. Activation fails if any parent entities are inactive.	Yes
`areaParentCode`	string	Optional	Code of the parent zone. Must be a valid active zone code. Cannot be set to `null`.	Yes
`externalIds`	object	Optional	Key-value map of external identifiers (`{"typeName": "value"}`). Omit to preserve existing values. Set to `null` to clear all external identifiers. Set a key's value to `null` to remove that specific key. Pass `{}` to make no change. Maximum five entries. Keys and values must not exceed 200 characters each.	Yes
`customFields`	object	Optional	Key-value map of custom field values. Omit to preserve existing values. Set to `null` to clear all custom field values. Set a key's value to `null` to remove that specific key. Pass `{}` to make no change. Keys must match custom fields configured for the org.	Yes
`language`	string	Optional	IETF BCP 47 language code for the zone (for example, `en-IN`). Must be enabled for the org. Cannot be set to `null`.	Yes
`currency`	string	Optional	ISO 4217 currency code for the zone (for example, `INR`). Must be enabled for the org. Cannot be set to `null`.	Yes
`timezone`	string	Optional	IANA timezone name for the zone (for example, `Asia/Kolkata`). Must be enabled for the org. Cannot be set to `null`.	Yes

Example response

{
  "response": [
    {
      "entityId": 75001001,
      "result": {
        "identifierName": "CODE",
        "identifierValue": "zone-north",
        "name": "North Region Zone Updated",
        "description": "Updated description via bulk update",
        "externalIds": {
          "erpId": "ERP-NORTH-01"
        },
        "customFields": {
          "cf_zone_region": "North"
        }
      },
      "errors": [],
      "warnings": []
    }
  ],
  "totalCount": 1,
  "failureCount": 0
}

Partial failure example (HTTP 207):

{
  "response": [
    {
      "entityId": 75001001,
      "result": {
        "identifierName": "CODE",
        "identifierValue": "zone-north",
        "name": "North Region Zone Updated"
      },
      "errors": [],
      "warnings": []
    },
    {
      "result": {
        "identifierName": "CODE",
        "identifierValue": "zone-does-not-exist",
        "name": "Should Fail"
      },
      "errors": [
        {
          "status": false,
          "code": 1254,
          "message": "zone not found for passed identifiers"
        }
      ],
      "warnings": []
    }
  ],
  "totalCount": 2,
  "failureCount": 1
}

Response parameters

Field	Type	Description
`response`	array	One entry per input item, in the same order as the request.
`.entityId`	integer	System-assigned ID of the zone. Present when the zone was identified, regardless of whether the update succeeded. Absent when the zone could not be identified or when a batch-level error occurs.
`.result`	object	Object containing the fields submitted for this zone, echoed from the request. Present for all items regardless of success or failure.
`.errors`	array	Errors for this item. Empty when the item succeeded.
`..code`	integer	Numeric error code.
`..message`	string	Error message.
`..status`	boolean	Status flag for the error entry.
`.warnings`	array	Non-fatal warnings for this item.
`..code`	integer	Numeric warning code.
`..message`	string	Warning message.
`..status`	boolean	Status flag for the warning entry.
`totalCount`	integer	Total number of items in the request.
`failureCount`	integer	Number of items that failed to update.

Error & warning codes

Code	Error number	Type	Description
`BULK_REQUEST_LIMIT_EXCEEDED`	1246	Error	The request contains more than 100 items. Maximum allowed is 100. HTTP 400.
`IDENTIFIER_REQUIRED`	1249	Error	`identifierName` or `identifierValue` is missing or blank. HTTP 400.
`INVALID_IDENTIFIER_TYPE`	1250	Error	`identifierName` must be `ID`, `CODE`, or `EXTERNAL_ID`. HTTP 400.
`IDENTIFIER_VALUE_INVALID`	1251	Error	`identifierValue` is not a valid integer when `identifierName` is `ID`. HTTP 400.
`ZONE_NAME_NOT_FOUND`	1254	Error	No zone found for the given identifier. HTTP 400.
`DUPLICATE_ENTITY_IN_REQUEST`	1253	Error	The second (and subsequent) occurrence of the same zone in the request is rejected; the first occurrence succeeds. HTTP 207.
`NAME_CANNOT_BE_NULL`	1252	Error	`name` is set to `null` or an empty string. HTTP 400.
`NAME_ROOT_NOT_ALLOWED`	1210	Error	`name` cannot equal `ROOT` (any case). HTTP 400.
`NAME_ALREADY_EXISTS_ORG`	1206	Error	The second item in the request that sets an already-used `name` value is rejected; the first item succeeds. HTTP 207.
`PARENT_PARAM_REQUIRED`	1257	Error	`areaParentCode` is set to `null` explicitly. HTTP 400.
`PARAM_TYPE_IS_NOT_VALID`	1217	Error	Emitted for multiple causes: `areaParentCode` does not match any active zone in the org; a `customFields` key is not a custom field configured for the org; a locale value (`language`, `currency`, or `timezone`) is not enabled for the org; or the net count of `externalIds` entries after the update would exceed five. HTTP 400.
`PARENT_NOT_ACTIVE`	1258	Error	`isActive` is set to `true` but one or more parent entities are inactive. HTTP 400.
`CHILDREN_STILL_ACTIVE`	1259	Error	`isActive` is set to `false` but the zone has active child entities (stores). HTTP 400.
`DUPLICATE_EXTERNAL_ID_IN_REQUEST`	1248	Error	The second item in the request that assigns an already-claimed `externalIds` value is rejected; the first item succeeds. HTTP 207.
`EXTERNAL_ID_ALREADY_EXISTS_ORG`	1245	Error	One or more `externalIds` values are already assigned to another entity in the org. HTTP 400.
`EXTERNAL_ID_KEY_TOO_LONG`	1261	Error	An `externalIds` key exceeds 200 characters. HTTP 400.
`EXTERNAL_ID_VALUE_TOO_LONG`	1262	Error	An `externalIds` value exceeds 200 characters. HTTP 400.
`REGEX_MATCH_FAILED`	1219	Error	`name` contains characters that are not letters, digits, underscores, or spaces. HTTP 400.
`NAME_LENGTH_EXCEEDS_LIMIT`	1264	Error	`name` exceeds 100 characters. HTTP 400.
`GLOBAL_ERR_MISSING_MANDATORY_FIELD`	403	Error	A locale field (`language`, `currency`, or `timezone`) was set to `null`; an `externalIds` key or value is blank; or `inheritLocale=true` but the parent zone has no locale configured for that field. HTTP 400.