Create label assignments (POST)

Assigns one or more labels to entities in bulk. An organization can create up to 10 assignments per request. Returns HTTP 201 if all succeed, HTTP 207 if some fail, or HTTP 400 if all fail.

Example request

curl -X POST "https://{host}/api_gateway/v2/labels/assignments" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "PRODUCT",
    "assignments": [
      {
        "entityId": "SKU-001",
        "labelName": "Summer Sale",
        "expiryDate": "2026-08-31"
      }
    ]
  }'

Prerequisites

Requires authentication with a valid bearer token.
The token must have write access to the Labels resource.

Body parameters

Field	Type	Required	Description
`entityType`	enum	Required	Entity type to assign labels to. One of: `CUSTOMER`, `PRODUCT`, `STORE`.
`assignments`	array	Required	List of assignment objects. Maximum 10 per request.
`.entityId`	string	Required	Identifier of the entity receiving the label.
`.labelName`	string	Conditional	Display name of the label to assign. Required if `labelExternalId` is not provided.
`.labelExternalId`	string	Conditional	Caller-defined identifier of the label to assign. Required if `labelName` is not provided.
`.expiryDate`	string	Optional	Date when this assignment expires. Format: `YYYY-MM-DD`. Must be a future date.

Example response

{
  "data": [
    {
      "assignmentId": 5001,
      "entityId": "SKU-001",
      "labelId": 101,
      "labelName": "Summer Sale",
      "labelExternalId": "SUMMER_SALE",
      "expiryDate": "2026-08-31"
    }
  ],
  "warnings": [],
  "errors": []
}

Response parameters

Field	Type	Description
`data`	array	Assignments created successfully.
`.assignmentId`	integer	System-assigned unique identifier for this assignment.
`.entityId`	string	Entity identifier from the request.
`.labelId`	integer	System-assigned identifier of the label.
`.labelName`	string	Display name of the assigned label.
`.labelExternalId`	string	Caller-defined identifier of the assigned label, or null if not set.
`.expiryDate`	string	Expiry date in `YYYY-MM-DD` format, or null if no expiry was set.
`warnings`	array	Non-fatal issues. Each item includes a code and message.
`errors`	array	Assignments that failed to create. Each item includes a code, message, and the rejected input.

Error & warning codes

Code	Error number	Type	Description
`LABEL_INVALID_ENTITY_TYPE`	23006	Error	`entityType` is not one of `CUSTOMER`, `PRODUCT`, `STORE`. HTTP 400.
`ASSIGNMENT_BATCH_SIZE_EXCEEDED`	23032	Error	More than 10 assignments in a single request. HTTP 400.