Remove label assignments

Time	Status	User Agent
Retrieving recent requests…

Remove one or more label assignments from entities in a single request. Each removal item targets one entity and specifies which labels to remove by label ID, name, or external ID. You can process up to 100 removal items per request.

Example request

curl -X DELETE "https://{host}/v2/labels/assignments" \
  -H "Authorization: Basic {base64_credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "CUSTOMER",
    "removals": [
      {
        "entityId": "<ENTITY_ID>",
        "labelIds": [109]
      }
    ]
  }'

Prerequisites

Basic authentication (Authorization: Basic {base64_credentials}) or OAuth (X-CAP-API-OAUTH-TOKEN).

Body parameters

Field	Type	Required	Description
`entityType`	enum	Required	Entity type for all removals in this request. Supported values: `CUSTOMER`, `PRODUCT`, `STORE`. Case-sensitive.
`removals`	array	Required	List of removal items. Maximum 100 items per request.
`.entityId`	string	Required	Identifier of the entity to remove labels from.
`.labelIds`	array	Conditional	List of label IDs to remove. Provide exactly one of `labelIds`, `labelNames`, or `labelExternalIds`.
`.labelNames`	array	Conditional	List of label names to remove. Provide exactly one of `labelIds`, `labelNames`, or `labelExternalIds`.
`.labelExternalIds`	array	Conditional	List of label external IDs to remove. Provide exactly one of `labelIds`, `labelNames`, or `labelExternalIds`.

Example response

{
  "data": [
    {
      "entityId": "<ENTITY_ID>",
      "removedLabelIds": [109]
    }
  ],
  "warnings": [],
  "errors": []
}

Already-inactive warning (HTTP 200):

{
  "warnings": [
    {
      "code": 23051,
      "field": "labelIds",
      "labelExternalId": "<ENTITY_ID>",
      "message": "Label with id '109' is already inactive or expired for entity '<ENTITY_ID>'."
    }
  ],
  "errors": []
}

Response parameters

Field	Type	Description
`data`	array	List of entities for which labels were successfully removed.
`.entityId`	string	Identifier of the entity.
`.removedLabelIds`	array	List of label IDs that were removed from the entity.
`warnings`	array	List of non-blocking warnings (for example, label already inactive).
`errors`	array	List of errors for removal items that failed.

Note: If some removal items succeed and others fail, the API returns HTTP 207. If all removal items fail, the API returns HTTP 400. If all removal items succeed, the API returns HTTP 200.

Error & warning codes

Code	Error number	Type	Description
`ASSIGNMENT_REQUEST_BODY_EMPTY`	23031	Error	Request body must contain at least one removal item. HTTP 400.
`ASSIGNMENT_BATCH_SIZE_EXCEEDED`	23032	Error	Maximum 100 removal items can be processed in a single request. HTTP 400.
`ASSIGNMENT_ENTITY_TYPE_REQUIRED`	23033	Error	`entityType` is required. HTTP 400.
`ASSIGNMENT_INVALID_ENTITY_TYPE`	23034	Error	Invalid entity type. Supported values: `CUSTOMER`, `PRODUCT`, `STORE`. HTTP 400.
`ASSIGNMENT_NOT_ASSIGNED_TO_ENTITY`	23050	Error	The label is not assigned to this entity. HTTP 400.
`ASSIGNMENT_ALREADY_INACTIVE`	23051	Warning	The label assignment is already inactive or expired for this entity.
`ASSIGNMENT_REMOVAL_ENTITY_ID_REQUIRED`	23052	Error	`entityId` is required for each removal item. HTTP 400.
`ASSIGNMENT_REMOVAL_LABEL_IDS_REQUIRED`	23053	Error	At least one of `labelIds`, `labelNames`, or `labelExternalIds` is required for each removal item. HTTP 400.
`ASSIGNMENT_LOCK_FAILED`	23055	Error	Could not acquire lock for the entity. Retry after a short delay. HTTP 409.
`ASSIGNMENT_REMOVAL_LABEL_IDENTIFIER_AMBIGUOUS`	23058	Error	Only one of `labelIds`, `labelNames`, or `labelExternalIds` is allowed per removal item. HTTP 400.