Time	Status	User Agent
Retrieving recent requests…

Add zones in bulk

Create up to 50 zones in a single request. Each zone is validated and persisted independently — a failure in one item doesn't block the others. The response reflects the outcome of each item individually, and the HTTP status reflects the overall result: 201 if all items succeeded, 207 if some failed, or 400 if all failed.

Note: Only users with the ADMIN_USER entity type can call this endpoint. Requests from non-admin users return HTTP 400 for every item.

Example request

curl -X POST "https://{host}/v2/locations/zones?inheritLocale=false" \
  -H "Authorization: Basic {base64-encoded-credentials}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "code": "zone-north",
      "name": "North Zone",
      "areaParentCode": "zone-root",
      "language": "en-IN",
      "currency": "INR",
      "timezone": "Asia/Kolkata",
      "description": "Northern region zone",
      "isActive": true,
      "externalId": ["EXT-Z-001"]
    }
  ]'

Note: The example response below is representative and has not been validated against a live API call.

Prerequisites

Authenticate using Basic authentication (Base64-encoded username:password).
The authenticated user must have the ADMIN_USER entity type.
The parent zone (areaParentCode) must exist and be active in the org before creating zones.
When inheritLocale is false (the default), the org must have the specified language, currency, and timezone values configured.

Query parameters

Field	Type	Required	Description
`inheritLocale`	boolean	Optional	When `true`, a zone inherits `language`, `currency`, and `timezone` from its parent zone if those fields are not provided in the request. If the parent zone also lacks locale settings, the request fails. Defaults to `false`.

Body parameters

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

Field	Type	Required	Description
`code`	string	Required	Unique code for the zone in the org. Accepts lowercase letters, digits, periods (`.`), underscores (`_`), and hyphens (`-`). Must start with a lowercase letter or digit. Max 50 characters.
`name`	string	Required	Display name for the zone. Accepts letters, digits, underscores, and spaces. Cannot equal `root` (any case).
`areaParentCode`	string	Required	Code of the parent zone this zone belongs to. Must be an existing active zone in the org.
`language`	string	Conditional	IETF BCP 47 language code for the zone (for example, `en-IN`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`currency`	string	Conditional	ISO 4217 currency code for the zone (for example, `INR`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`timezone`	string	Conditional	IANA timezone name for the zone (for example, `Asia/Kolkata`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`description`	string	Optional	Free-text description of the zone.
`isActive`	boolean	Optional	Whether the zone is active. Defaults to `true`. A warning is returned when this field is omitted.
`externalId`	array	Optional	External IDs for the zone. Max five entries. Each value must be non-blank, unique within the request, and not already assigned to another entity in the org.
`attributes`	object	Optional	Custom field values for the zone. Keys must match fields configured for the org (matched case-insensitively).

Example response

{
  "response": [
    {
      "entityId": 20301,
      "result": {
        "code": "zone-north",
        "name": "North Zone",
        "areaParentCode": "zone-root",
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata"
      },
      "errors": [],
      "warnings": []
    }
  ],
  "totalCount": 1,
  "failureCount": 0
}

Partial failure example (HTTP 207):

{
  "response": [
    {
      "entityId": 20301,
      "result": {
        "code": "zone-north",
        "name": "North Zone",
        "areaParentCode": "zone-root"
      },
      "errors": [],
      "warnings": []
    },
    {
      "result": {
        "code": "zone-north",
        "name": "North Zone Duplicate",
        "areaParentCode": "zone-root"
      },
      "errors": [
        {
          "status": false,
          "message": "Code already Exists Orgs",
          "code": 1220
        }
      ],
      "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 created zone. Absent when the item failed.
`.result`	object	Echo of the submitted zone object. Always present for all items, whether the item succeeded or failed.
`.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 create.

Error & warning codes

Code	Error number	Type	Description
`NOT_AN_ADMIN_USER`	1209	Error	The authenticated user is not an admin. HTTP 400.
`BULK_REQUEST_LIMIT_EXCEEDED`	1246	Error	The request contains more than 50 items. Maximum allowed is 50. HTTP 400.
`CODE_NOT_SET`	1247	Error	`code` is missing or blank. HTTP 400.
`NAME_NOT_SET`	1200	Error	`name` is missing or blank. HTTP 400.
`REGEX_MATCH_FAILED`	1219	Error	`code` or `name` failed format validation. HTTP 400.
`NAME_LENGHT_NOT_VALID`	1218	Error	`code` exceeds 50 characters. HTTP 400.
`NAME_ROOT_NOT_ALLOWED`	1210	Error	`name` cannot equal `root` (any case). HTTP 400.
`CODE_ALREADY_EXISTS_ORG`	1220	Error	A zone with this code already exists in the org, or a duplicate `code` appears in the same request. HTTP 400.
`NAME_ALREADY_EXISTS_ORG`	1206	Error	A zone with this name already exists in the org. HTTP 400.
`GLOBAL_ERR_MISSING_MANDATORY_FIELD`	403	Error	A required field is missing. Applies to `areaParentCode`, locale fields (when `inheritLocale` is `false`), and blank `externalId` entries. HTTP 400.
`PARAM_TYPE_IS_NOT_VALID`	1217	Error	A field value is invalid. Applies to an `areaParentCode` that does not match an active zone, locale values not enabled for the org, and more than five `externalId` entries. HTTP 400.
`EXTERNAL_ID_ALREADY_EXISTS_ORG`	1245	Error	One or more `externalId` values are already assigned to another entity in the org. HTTP 400.
`DUPLICATE_EXTERNAL_ID_IN_REQUEST`	1248	Error	Duplicate `externalId` values in the same request. HTTP 400.
`ORG_ENTITY_TYPE_LIMIT_EXCEEDED`	1225	Error	The org has reached its configured limit for zones. HTTP 400.
`PARAM_TYPE_SET_TO_DEFAULT`	1215	Warning	`isActive` was not provided and defaulted to `true`.