Create label assignments

Time	Status	User Agent
Retrieving recent requests…

Assign one or more labels to entities in a single request. Each assignment links a label to an entity (customer, product, or store) and optionally sets an expiry date for the assignment. You can create up to 100 assignments per request.

Example request

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

Prerequisites

Basic authentication (Authorization: Basic {base64_credentials}) or OAuth (X-CAP-API-OAUTH-TOKEN).
The label must already exist and be active. Create labels using Create labels.

Body parameters

Field	Type	Required	Description
`entityType`	enum	Required	Entity type for all assignments in this request. Supported values: `CUSTOMER`, `PRODUCT`, `STORE`. Case-sensitive.
`assignments`	array	Required	List of label assignments to create. Maximum 100 assignments per request.
`.entityId`	string	Required	Identifier of the entity to assign the label to.
`.labelName`	string	Conditional	Name of the label to assign. Either `labelName` or `labelExternalId` is required — not both.
`.labelExternalId`	string	Conditional	External ID of the label to assign. Either `labelName` or `labelExternalId` is required — not both.
`.expiryDate`	string	Optional	Date when the assignment expires. Format: `yyyy-MM-dd` (for example, `2026-12-31`). Must be a future date. Requires org timezone to be configured.

Example response

{
  "data": [
    {
      "assignmentId": 1,
      "entityId": "<ENTITY_ID>",
      "labelId": 109,
      "labelName": "VIP",
      "labelExternalId": "vip-tier",
      "expiryDate": "2027-06-04T18:29:59Z"
    }
  ],
  "warnings": [],
  "errors": []
}

Response parameters

Field	Type	Description
`data`	array	List of successfully created assignments.
`.assignmentId`	number	Unique identifier of the created assignment.
`.entityId`	string	Identifier of the entity the label was assigned to.
`.labelId`	number	Unique identifier of the assigned label.
`.labelName`	string	Name of the assigned label.
`.labelExternalId`	string	External identifier of the assigned label.
`.expiryDate`	string	Expiry date and time of the assignment in UTC, in ISO-8601 format. When the label has a `RELATIVE` expiry config, this is computed automatically from the label definition.
`warnings`	array	List of warnings. Empty when no warnings occur.
`errors`	array	List of errors for assignments that failed.
`.code`	number	Numeric error code.
`.field`	string	Name of the field that caused the error.
`.message`	string	Description of the error.

Note: If some assignments are created and others fail, the API returns HTTP 207. If all assignments fail, the API returns HTTP 400. If all assignments are created successfully, the API returns HTTP 200.

Note: When expiryDate is provided and the org does not have a timezone configured, the API returns HTTP 400 with no response body. Contact your Capillary account team to configure org timezone.

Error & warning codes

Code	Error number	Type	Description
`ASSIGNMENT_REQUEST_BODY_EMPTY`	23031	Error	Request body must contain at least one assignment. HTTP 400.
`ASSIGNMENT_BATCH_SIZE_EXCEEDED`	23032	Error	Maximum 100 assignments can be created 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_LABEL_IDENTIFIER_REQUIRED`	23035	Error	Either `labelName` or `labelExternalId` is required. HTTP 400.
`ASSIGNMENT_LABEL_NOT_FOUND`	23037	Error	No active label found for the given identifier and entity type. HTTP 400.
`ASSIGNMENT_LABEL_IDENTIFIER_AMBIGUOUS`	23038	Error	`labelName` and `labelExternalId` resolve to different labels. Provide only one. HTTP 400.
`ASSIGNMENT_EXPIRY_DATE_PAST`	23039	Error	Expiry date must be a future date. HTTP 400.
`ASSIGNMENT_INVALID_EXPIRY_DATE_FORMAT`	23040	Error	Invalid expiry date format. Expected: `yyyy-MM-dd` (for example, `2026-08-31`). HTTP 400.
`ASSIGNMENT_MAX_LABELS_PER_ENTITY`	23043	Error	Entity already has the maximum number of active labels allowed. HTTP 400.
`ASSIGNMENT_ALREADY_EXISTS`	23044	Error	This label is already assigned to the entity. HTTP 409.
`ASSIGNMENT_ENTITY_NOT_FOUND`	23045	Error	Entity with the given ID does not exist. HTTP 400.
`ASSIGNMENT_LOCK_FAILED`	23055	Error	Could not acquire lock for the entity. Another assignment operation is in progress. Retry after a short delay. HTTP 409.
`ORG_TIMEZONE_NOT_CONFIGURED`	23056	Error	The organization does not have a timezone configured. HTTP 400.