Create labels (POST)

Creates one or more labels in bulk. Labels classify entities such as customers, products, or stores. An organization can create up to 10 labels per request.

Example request

curl -X POST "https://{host}/api_gateway/v2/labels" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": [
      {
        "name": "Summer Sale",
        "externalId": "SUMMER_SALE",
        "description": "Products eligible for summer promotions",
        "entityType": "PRODUCT",
        "expiryConfig": {
          "type": "FIXED_DATE",
          "date": "2026-08-31T23:59:59Z"
        }
      }
    ]
  }'

Prerequisites

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

Body parameters

Field	Type	Required	Description
`labels`	array	Required	List of label objects to create. Maximum 10 per request.
`.name`	string	Required	Display name for the label. Max 255 characters. Must be unique within the entity type for the org.
`.externalId`	string	Optional	Caller-defined identifier. Max 255 characters. Must be unique within the entity type if provided.
`.description`	string	Optional	Human-readable description. Max 1024 characters.
`.entityType`	enum	Required	Entity type this label applies to. One of: `CUSTOMER`, `PRODUCT`, `STORE`.
`.expiryConfig`	object	Optional	Expiry settings for the label. If omitted, the label does not expire.
`..type`	enum	Required	Expiry type. One of: `NONE`, `FIXED_DATE`, `RELATIVE`.
`..date`	string	Conditional	Required when `type` is `FIXED_DATE`. ISO-8601 UTC date-time (`YYYY-MM-DDThh:mm:ssZ`). Must be a future date.
`..duration`	integer	Conditional	Required when `type` is `RELATIVE`. Positive integer representing the number of duration units.
`..durationType`	enum	Conditional	Required when `type` is `RELATIVE`. One of: `DAYS`, `MONTHS`, `YEARS`.

Example response

{
  "data": [
    {
      "id": 101,
      "externalId": "SUMMER_SALE"
    }
  ],
  "warnings": [],
  "errors": []
}

Response parameters

Field	Type	Description
`data`	array	Labels created successfully in this request.
`.id`	integer	System-generated unique identifier assigned to the label.
`.externalId`	string	Caller-defined identifier supplied in the request, or null if not provided.
`warnings`	array	Non-fatal issues. Each item includes a code and message.
`errors`	array	Labels that failed to create. Each item includes a code, message, and the rejected input.

Error & warning codes

Code	Error number	Type	Description
`LABEL_NAME_REQUIRED`	23001	Error	Label name is missing. HTTP 400.
`LABEL_INVALID_ENTITY_TYPE`	23006	Error	`entityType` is not one of `CUSTOMER`, `PRODUCT`, `STORE`. HTTP 400.
`LABEL_NAME_TOO_LONG`	23007	Error	`name` exceeds 255 characters. HTTP 400.
`LABEL_EXTERNAL_ID_TOO_LONG`	23008	Error	`externalId` exceeds 255 characters. HTTP 400.
`LABEL_DESCRIPTION_TOO_LONG`	23009	Error	`description` exceeds 1024 characters. HTTP 400.
`LABEL_DUPLICATE_NAME`	23019	Error	A label with this name already exists for the entity type in this org. HTTP 409.
`LABEL_DUPLICATE_EXTERNAL_ID`	23020	Error	A label with this external ID already exists for the entity type in this org. HTTP 409.
`LABEL_BATCH_SIZE_EXCEEDED`	23021	Error	More than 10 labels in a single request. HTTP 400.