Add Stores in Bulk

Time	Status	User Agent
Retrieving recent requests…

Create up to 100 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.

Example request

curl --location 'https://eu.api.capillarytech.com/v2/locations/stores' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-OAUTH-TOKEN: eyJraWQiOi' \
--data-raw '[
  {
    "code": "store-north-05",
    "name": "North Store 05",
    "areaParentCode": "zone-api-test-01",
    "groupParentCode": "concept-retail3",
    "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",
    "externalIds": {"erpId": "ERP-005"},
    "customFields": {
      "StoreCF": "value1",
      "age": "3"
    }
  }
]'

curl --location 'https://eu.api.capillarytech.com/v2/locations/stores?inheritLocale=false' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-OAUTH-TOKEN: eyJraWQiOibTf2beQ' \
--data-raw '[
  {
    "code": "store-north-04",
    "name": "North Store 04",
    "areaParentCode": "zone-api-test-01",
    "groupParentCode": "concept-retail3",
    "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",
    "externalIds": {"erpId": "ERP-004"},
    "customFields": {
      "StoreCF": "value1",
      "age": "3"
    }
  }
]'

curl --location 'https://eu.api.capillarytech.com/v2/locations/stores?inheritLocale=true' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-OAUTH-TOKEN: eyJraWQiOebTf2' \
--data-raw '[
  {
    "code": "store-north-03",
    "name": "North Store 03",
    "areaParentCode": "zone-api-test-01",
    "groupParentCode": "concept-retail3",
    "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",
    "externalIds": {"erpId": "ERP-003"},
    "customFields": {
      "StoreCF": "value1",
      "age": "3"
    }
  }
]'

Prerequisites

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 100 items per request.

Field	Type	Required	Description
`code`	string	Required	Unique code for the store in the org. Accepts only lowercase letters, digits, periods (`.`), underscores (`_`), and hyphens (`-`). Must start with a lowercase letter or digit. Max 50 characters.
`name`	string	Required	Unique name for the store. Accepts letters, digits, underscores, and spaces. Cannot be `ROOT`. Max 100 characters. Case-insensitive.
`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` when 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.
`externalIds`	object	Optional	Object containing key-value pairs of external identifiers for the store (for example, `{"erpId": "ERP-001"}`). Maximum five entries. Keys and values must be non-blank and no longer than 200 characters each. Values must be unique within the request and not already assigned to another entity in the org.
`customFields`	object	Optional	Object containing custom field key-value pairs for the store (for example, `{"fieldName": "value"}`). Keys must match custom fields configured for the org (matched case-insensitively).

API Quick Reference

{{https://{host}/v2/locations/stores}}
└─ {{locations}}
├─ {{addStores}}({{CreateStoreRequest}}) -> {{BulkResponse}}
├─ {{CreateStoreRequest}} \[]
│   ├─ {{code}} (string, required)
│   ├─ {{name}} (string, required)
│   ├─ {{areaParentCode}} (string, required)
│   ├─ {{groupParentCode}} (string, required)
│   ├─ {{language}} (string, conditional)
│   ├─ {{currency}} (string, conditional)
│   ├─ {{timezone}} (string, conditional)
│   ├─ {{description}} (string)
│   ├─ {{isActive}} (boolean)
│   ├─ {{isAdmin}} (boolean)
│   ├─ {{latitude}} (string)
│   ├─ {{longitude}} (string)
│   ├─ {{email}} (string)
│   ├─ {{mobile}} (string)
│   ├─ {{landline}} (string)
│   ├─ {{externalIds}} (object)
│   │   └─ {{<key>}} (string)
│   └─ {{customFields}} (object)
│       └─ {{<key>}} (string)
└─ {{BulkResponse}}
├─ {{response}} \[]
│   ├─ {{entityId}} (integer)
│   ├─ {{result}} (object)
│   ├─ {{errors}} \[]
│   │   ├─ {{code}} (integer)
│   │   ├─ {{message}} (string)
│   │   └─ {{status}} (boolean)
│   └─ {{warnings}} \[]
│       ├─ {{code}} (integer)
│       ├─ {{message}} (string)
│       └─ {{status}} (boolean)
├─ {{totalCount}} (integer)
└─ {{failureCount}} (integer)

Example response

{
    "response": [
        {
            "entityId": 75251202,
            "result": {
                "code": "store-north-05",
                "name": "North Store 05",
                "description": "Flagship store in the north region",
                "isActive": true,
                "externalIds": {
                    "erpId": "ERP-005"
                },
                "language": "en-IN",
                "currency": "INR",
                "timezone": "Asia/Kolkata",
                "isAdmin": false,
                "latitude": "28.6139",
                "longitude": "77.2090",
                "email": "[email protected]",
                "mobile": "9876543210",
                "landline": "",
                "areaParentCode": "zone-api-test-01",
                "groupParentCode": "concept-retail3",
                "customFields": {
                    "StoreCF": "value1",
                    "age": "3"
                }
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

{
    "response": [
        {
            "entityId": 75251198,
            "result": {
                "code": "store-north-03",
                "name": "North Store 03",
                "description": "Flagship store in the north region",
                "isActive": true,
                "externalIds": {
                    "erpId": "ERP-003"
                },
                "language": "en-IN",
                "currency": "INR",
                "timezone": "Asia/Kolkata",
                "isAdmin": false,
                "latitude": "28.6139",
                "longitude": "77.2090",
                "email": "[email protected]",
                "mobile": "9876543210",
                "landline": "",
                "areaParentCode": "zone-api-test-01",
                "groupParentCode": "concept-retail3",
                "customFields": {
                    "StoreCF": "value1",
                    "age": "3"
                }
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

{
    "response": [
        {
            "entityId": 75251201,
            "result": {
                "code": "store-north-04",
                "name": "North Store 04",
                "description": "Flagship store in the north region",
                "isActive": true,
                "externalIds": {
                    "erpId": "ERP-004"
                },
                "language": "en-IN",
                "currency": "INR",
                "timezone": "Asia/Kolkata",
                "isAdmin": false,
                "latitude": "28.6139",
                "longitude": "77.2090",
                "email": "[email protected]",
                "mobile": "9876543210",
                "landline": "",
                "areaParentCode": "zone-api-test-01",
                "groupParentCode": "concept-retail3",
                "customFields": {
                    "StoreCF": "value1",
                    "age": "3"
                }
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

Partial failure example (HTTP 207):

{
  "response": [
    {
      "entityId": 75251055,
      "result": {
        "code": "store-north-02",
        "name": "North Store 02",
        "isActive": true,
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata",
        "isAdmin": false,
        "latitude": "",
        "longitude": "",
        "email": "",
        "mobile": "",
        "landline": "",
        "areaParentCode": "zone-north",
        "groupParentCode": "concept-retail"
      },
      "errors": [],
      "warnings": []
    },
    {
      "result": {
        "code": "store-north-01",
        "name": "North Store 01 Duplicate",
        "isActive": true,
        "language": "en-IN",
        "currency": "INR",
        "timezone": "Asia/Kolkata",
        "isAdmin": false,
        "latitude": "",
        "longitude": "",
        "email": "",
        "mobile": "",
        "landline": "",
        "areaParentCode": "zone-north",
        "groupParentCode": "concept-retail"
      },
      "errors": [
        {
          "status": false,
          "code": 1220,
          "message": "Code already Exists Orgs"
        }
      ],
      "warnings": [
        {
          "status": false,
          "code": 1215,
          "message": "Invalid isActive specified, setting to default"
        }
      ]
    }
  ],
  "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. Absent when the item failed.
`.result`	object	Object containing the submitted store fields, 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 create.

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.
`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_LENGTH_EXCEEDS_LIMIT`	1264	Error	`name` exceeds 100 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 `externalIds` keys or values. 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, more than five `externalIds` entries, and invalid `customFields` key names. HTTP 400.
`EXTERNAL_ID_ALREADY_EXISTS_ORG`	1245	Error	One or more `externalIds` values are already assigned to another entity in the org. HTTP 400.
`DUPLICATE_EXTERNAL_ID_IN_REQUEST`	1248	Error	Duplicate `externalIds` values in the same request. 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.
`ORG_ENTITY_TYPE_LIMIT_EXCEEDED`	1225	Error	The org has reached its configured limit for stores. HTTP 400.
`SERVICE_CALL_FAILED`	1213	Error	The store couldn't be created because the ID generation service returned an error. Retry the request. HTTP 400.
`PARAM_TYPE_SET_TO_DEFAULT`	1215	Warning	`isActive` was not provided and defaulted to `true`.