Time	Status	User Agent
Retrieving recent requests…

Update concepts in bulk

Update up to 100 concepts 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 concept to update using identifierName and identifierValue. All other fields are optional and use patch semantics: fields absent from the request JSON are left unchanged. Null and patch semantics vary per field — see the body parameters table for the exact behavior of each field.

Example request

curl -X PUT "https://{host}/v2/locations/concepts" \
  -H "Authorization: Basic {base64-encoded-credentials}" \
  -H "X-CAP-API-AUTH-ORG-ID: {orgId}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "identifierName": "CODE",
      "identifierValue": "concept-dine-in",
      "description": "Updated description for documentation"
    }
  ]'

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 concept's parent concept when not explicitly provided. Defaults to `false`.

Body parameters

Pass a JSON array of concept 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 concept and are never updated themselves.

Field	Type	Required	Description	Updatable
`identifierName`	string	Required	How the target concept is identified. Must be one of: `ID` (internal system ID), `CODE` (concept 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 concept. 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 concept has admin access.	Yes
`isActive`	boolean	Optional	Whether the concept is active. Deactivation fails if any child entities (stores) are still active. Activation fails if any parent entities are inactive.	Yes
`isOrgUnit`	boolean	Optional	Whether the concept functions as an organizational unit.	Yes
`groupParentCode`	string	Optional	Code of the parent concept. Cannot be set to `null`. Provide a valid concept code to change the parent.	Yes
`externalIds`	object	Optional	Key-value map of external identifiers (`{"typeName": "value"}`). Omit to preserve existing values. Pass `null` to clear all external identifiers. Pass `{}` to make no change. Set a key's value to `null` to remove that specific key. 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. Pass `null` to clear all custom field values. 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 concept (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 concept (for example, `INR`). Must be enabled for the org. Cannot be set to `null`.	Yes
`timezone`	string	Optional	IANA timezone name for the concept (for example, `Asia/Kolkata`). Must be enabled for the org. Cannot be set to `null`.	Yes

Example response

{
  "response": [
    {
      "entityId": 76001001,
      "result": {
        "identifierName": "CODE",
        "identifierValue": "concept-dine-in",
        "description": "Updated description for documentation"
      },
      "errors": [],
      "warnings": []
    }
  ],
  "totalCount": 1,
  "failureCount": 0
}

Partial failure example (HTTP 207):

{
  "response": [
    {
      "entityId": 76001001,
      "result": {
        "identifierName": "CODE",
        "identifierValue": "concept-dine-in",
        "description": "Updated description for documentation"
      },
      "errors": [],
      "warnings": []
    },
    {
      "result": {
        "identifierName": "CODE",
        "identifierValue": "concept-does-not-exist"
      },
      "errors": [
        {
          "status": false,
          "code": 1255,
          "message": "concept 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 updated concept. Present when the concept was identified, regardless of whether the update succeeded. Absent when the concept could not be identified, or when an unexpected error occurs.
`.result`	object	Object containing the fields submitted for this concept, 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.
`CONCEPT_NAME_NOT_FOUND`	1255	Error	Concept not found for the given `CODE` or `EXTERNAL_ID`. HTTP 400.
`DUPLICATE_ENTITY_IN_REQUEST`	1253	Error	Two or more rows in the request resolve to the same concept. HTTP 207 (first wins — the first occurrence in the batch is updated; later duplicates are rejected).
`NAME_ALREADY_EXISTS_ORG`	1206	Error	A name in the request matches another concept in the org, or two rows in the batch share the same name. HTTP 207 (first wins).
`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.
`PARENT_PARAM_REQUIRED`	1257	Error	`groupParentCode` is set to `null` explicitly. HTTP 400.
`PARAM_TYPE_IS_NOT_VALID`	1217	Error	`groupParentCode` does not match a concept in the org; or a locale field (`language`, `currency`, `timezone`) is not enabled for the org; or adding external identifiers would exceed the five-entry limit. HTTP 400.
`PARENT_ID_NOT_VALID`	1214	Error	`groupParentCode` resolves to the concept itself — a concept cannot be its own parent. 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 concept has active child entities (stores). HTTP 400.
`OU_CANNOT_BE_ENABLED`	1226	Error	`isOrgUnit` is set to `true` but the org is not configured for organizational units. HTTP 400.
`DUPLICATE_EXTERNAL_ID_IN_REQUEST`	1248	Error	Duplicate values in `externalIds` within the same request. 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.
`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`; or an `externalIds` key or value is blank; or `inheritLocale=true` is set but the concept's parent has no locale configured. HTTP 400.