Create labels

Time	Status	User Agent
Retrieving recent requests…

Create one or more labels for an organization in a single request. A label is a metadata tag that you can apply to customers, products, or stores to enable segmentation and filtering. You can create up to 10 labels per request.

Example request

curl -X POST "https://{host}/v2/labels" \
  -H "Authorization: Basic {base64_credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": [
      {
        "name": "Summer Sale",
        "externalId": "summer-sale-2026",
        "description": "Labels for summer sale products",
        "entityType": "PRODUCT",
        "expiryConfig": {
          "type": "FIXED_DATE",
          "expiryDate": "2027-12-31T23:59:59+05:30"
        }
      }
    ]
  }'

Prerequisites

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

Body parameters

Field	Type	Required	Description
`labels`	array	Required	List of labels to create. Maximum 10 labels per request.
`.name`	string	Required	Name of the label. Must be unique within the same `entityType` for the organization. Max 255 characters.
`.externalId`	string	Conditional	External identifier for the label. Must be unique within the same `entityType` for the organization. Max 255 characters. Required when the org has external ID enforcement enabled.
`.description`	string	Optional	Description of the label. Max 1,024 characters.
`.entityType`	enum	Required	Entity type the label applies to. Supported values: `CUSTOMER`, `PRODUCT`, `STORE`. Case-sensitive.
`.expiryConfig`	object	Optional	Expiry configuration for the label. If omitted, the label does not expire.
`..type`	enum	Required	Expiry type. Supported values: `NONE`, `FIXED_DATE`, `RELATIVE`. Case-sensitive.
`..expiryDate`	string	Conditional	Required when `type` is `FIXED_DATE`. Expiry date in ISO-8601 format: `YYYY-MM-DDThh:mm:ssZ` (for example, `2026-12-31T23:59:59+05:30`). Must be a future date.
`..unit`	enum	Conditional	Required when `type` is `RELATIVE`. Duration unit. Supported values: `DAYS`, `MONTHS`, `YEARS`.
`..value`	number	Conditional	Required when `type` is `RELATIVE`. Duration value. Must be a non-negative integer.
`..roundingUnit`	string	Optional	Rounding unit for the expiry duration. Applicable when `type` is `RELATIVE`.

Example response

{
  "data": [
    {
      "id": 108,
      "externalId": "summer-sale-2026"
    }
  ],
  "warnings": [],
  "errors": []
}

Partial failure (HTTP 207):

{
  "data": [
    {
      "id": 108,
      "externalId": "summer-sale-2026"
    }
  ],
  "warnings": [],
  "errors": [
    {
      "code": 23019,
      "field": "name",
      "labelExternalId": "clearance-2026",
      "message": "A label with the name 'Clearance' already exists for entity type 'PRODUCT'."
    }
  ]
}

Response parameters

Field	Type	Description
`data`	array	List of successfully created labels.
`.id`	number	Unique identifier assigned to the created label.
`.externalId`	string	External identifier of the created label.
`warnings`	array	List of warnings. Empty when no warnings occur.
`errors`	array	List of errors for labels that failed to create.
`.code`	number	Numeric error code.
`.field`	string	Name of the field that caused the error.
`.labelExternalId`	string	External ID of the label item that failed.
`.message`	string	Description of the error.

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

Error & warning codes

Code	Error number	Type	Description
`LABEL_NAME_REQUIRED`	23001	Error	Label name is required. HTTP 400.
`LABEL_EXPIRY_DATE_PAST`	23004	Error	Expiry date must be a future date. HTTP 400.
`LABEL_UNSUPPORTED_TIME_UNIT`	23005	Error	Unsupported time unit. Supported values: `DAYS`, `MONTHS`, `YEARS`. HTTP 400.
`LABEL_INVALID_ENTITY_TYPE`	23006	Error	Invalid entity type. Supported values: `CUSTOMER`, `PRODUCT`, `STORE`. HTTP 400.
`LABEL_NAME_TOO_LONG`	23007	Error	Label name must not exceed 255 characters. HTTP 400.
`LABEL_EXTERNAL_ID_TOO_LONG`	23008	Error	External ID must not exceed 255 characters. HTTP 400.
`LABEL_DESCRIPTION_TOO_LONG`	23009	Error	Description must not exceed 1,024 characters. HTTP 400.
`LABEL_RELATIVE_EXPIRY_UNIT_REQUIRED`	23010	Error	`unit` is required when `expiryConfig.type` is `RELATIVE`. HTTP 400.
`LABEL_RELATIVE_EXPIRY_VALUE_REQUIRED`	23011	Error	`value` must be a non-negative integer when `expiryConfig.type` is `RELATIVE`. HTTP 400.
`LABEL_FIXED_EXPIRY_DATE_REQUIRED`	23012	Error	`expiryDate` is required when `expiryConfig.type` is `FIXED_DATE`. HTTP 400.
`LABEL_INVALID_EXPIRY_CONFIG_TYPE`	23013	Error	Invalid expiry config type. Supported values: `NONE`, `FIXED_DATE`, `RELATIVE`. HTTP 400.
`LABEL_INVALID_EXPIRY_DATE_FORMAT`	23014	Error	Invalid expiry date format. Expected ISO-8601 format: `YYYY-MM-DDThh:mm:ssZ`. HTTP 400.
`LABEL_LOCK_FAILED`	23015	Error	Could not acquire lock for the label. Another operation is in progress. Retry after a short delay. HTTP 409.
`LABEL_DUPLICATE_NAME`	23019	Error	A label with the same name already exists for this entity type. HTTP 409.
`LABEL_DUPLICATE_EXTERNAL_ID`	23020	Error	A label with the same external ID already exists for this entity type. HTTP 409.
`LABEL_BATCH_SIZE_EXCEEDED`	23021	Error	Maximum 10 labels can be created in a single request. HTTP 400.
`LABEL_REQUEST_BODY_EMPTY`	23022	Error	Request body must contain at least one label. HTTP 400.
`LABEL_ITEM_NULL`	23023	Error	Label item must not be null. HTTP 400.
`LABEL_EXTERNAL_ID_REQUIRED`	23030	Error	External ID is required. HTTP 400.

Example request

Prerequisites

Body parameters

Example response

Response parameters

Error & warning codes

201All labels created.

207Partial success — some labels created, some failed.

400All labels failed validation.