Time	Status	User Agent
Retrieving recent requests…

Add stores in bulk

Create up to 50 stores in a single request. Each store 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/stores?inheritLocale=false" \
  -H "Authorization: Basic {base64-encoded-credentials}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "code": "store-north-01",
      "name": "North Store 01",
      "areaParentCode": "zone-north",
      "groupParentCode": "concept-retail",
      "language": "en-IN",
      "currency": "INR",
      "timezone": "Asia/Kolkata",
      "description": "Flagship store in the north region",
      "isActive": true,
      "latitude": "28.6139",
      "longitude": "77.2090",
      "email": "[email protected]",
      "mobile": "9876543210",
      "externalId": ["EXT-001", "EXT-002"]
    }
  ]'

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) and parent concept (groupParentCode) must exist and be active in the org before creating stores.
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 store 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 store objects. Maximum 50 items per request.

Field	Type	Required	Description
`code`	string	Required	Unique code for the store 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 store. Accepts letters, digits, underscores, and spaces. Cannot be `ROOT`.
`areaParentCode`	string	Required	Code of the parent zone this store belongs to.
`groupParentCode`	string	Required	Code of the parent concept this store belongs to.
`language`	string	Conditional	IETF BCP 47 language code for the store (for example, `en-IN`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`currency`	string	Conditional	ISO 4217 currency code for the store (for example, `INR`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`timezone`	string	Conditional	IANA timezone name for the store (for example, `Asia/Kolkata`). Required when `inheritLocale` is `false`. Must be enabled for the org.
`description`	string	Optional	Free-text description of the store.
`isActive`	boolean	Optional	Whether the store is active. Defaults to `true`. A warning is returned when this field is omitted.
`isAdmin`	boolean	Optional	Whether the store has admin access. Defaults to `false`.
`latitude`	string	Optional	Latitude coordinate of the store.
`longitude`	string	Optional	Longitude coordinate of the store.
`email`	string	Optional	Contact email address for the store.
`mobile`	string	Optional	Contact mobile number for the store.
`landline`	string	Optional	Contact landline number for the store.
`externalId`	array	Optional	External IDs for the store. 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 store. Keys must match fields configured for the org (matched case-insensitively).

Example response

{
  "response": [
    {
      "entityId": 10452,
      "result": {
        "code": "store-north-01",
        "name": "North Store 01",
        "areaParentCode": "zone-north",
        "groupParentCode": "concept-retail",
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata"
      },
      "errors": [],
      "warnings": []
    }
  ],
  "totalCount": 1,
  "failureCount": 0
}

Partial failure example (HTTP 207):

{
  "response": [
    {
      "entityId": 10452,
      "result": null,
      "errors": [],
      "warnings": []
    },
    {
      "entityId": null,
      "result": {
        "code": "store-north-01",
        "name": "North Store 01"
      },
      "errors": [
        {
          "code": "CODE_ALREADY_EXISTS_ORG",
          "message": "code already exists in org"
        }
      ],
      "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 store. `null` if the item failed.
`.result`	object	Echo of the submitted store object. Always present for all items, whether the item succeeded or failed.
`.errors`	array	Errors for this item. Empty when the item succeeded.
`..code`	string	Symbolic error code.
`..message`	string	Error message.
`.warnings`	array	Non-fatal warnings for this item.
`..code`	string	Symbolic warning code.
`..message`	string	Warning message.
`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 be `ROOT`. HTTP 400.
`CODE_ALREADY_EXISTS_ORG`	1220	Error	A store 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 store 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`, `groupParentCode`, 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 locale values not enabled for the org, invalid parent codes, 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 stores. HTTP 400.
`PARAM_TYPE_SET_TO_DEFAULT`	1215	Warning	`isActive` was not provided and defaulted to `true`.