Labels API's

The Labels APIs let you create, retrieve, update, and manage static metadata labels and their assignments to entities such as customers, products, and stores. Use these APIs to classify and organise entities at scale, control label lifecycles through expiry configurations, and query which labels are attached to which entities.

What you can do

You can use the Labels APIs to:

• Create, retrieve, and update labels scoped to entity types — CUSTOMER, PRODUCT, or STORE
• Configure label expiry using fixed dates, relative durations, or no expiry
• Assign labels to entities and remove assignments when they are no longer needed
• Search label assignments by label identifier, or retrieve all assignments for a given set of entities
• Update assignment expiry without removing and re-creating the assignment
• Auto-create labels on assignment when a label name is provided and no active label with that name exists for the entity type

🚧

Notes

• Deletion is not supported for labels. Deactivate a label by setting its status to ARCHIVED.
• An archived label can only be re-activated (status: ACTIVE). No other fields can be changed while a label is archived.
• Label names and external IDs must be unique per entity type within an organisation.

Labels

Static labels are metadata tags attached to entities to classify and organise them. Labels are scoped to an entity type (CUSTOMER, PRODUCT, or STORE) and must be unique by name within the same entity type and organisation.

Each label supports one of three expiry configurations:

Label create and update operations support batch requests of up to 10 labels per request. If some labels in a batch succeed and others fail, the API returns HTTP 207 Multi-Status with successes in data and failures in errors.

Label assignments

A label assignment links a label to a specific entity — for example, a product tagged "Flash-Sale" or a customer tagged "VIP". All assignment operations use the /v2/labels/assignments endpoint, except Search which uses /v2/labels/assignments/search.

Each entity is capped at 200 active label assignments. When you remove an assignment, the entity is untagged immediately — downstream features such as promotions or campaigns that filter by that label will no longer include the entity.

Auto-creation of labels on assignment. If you supply labelName when creating an assignment and no active label with that name exists for the entity type, the API automatically creates a new label with no expiry before creating the assignment.

🚧

Notes

• Only the expiryDate field is updatable on an existing assignment. To identify the assignment to update, provide labelId, labelName, or labelExternalId — any one is sufficient.
• For Remove assignments, supply exactly one identifier type per removal item: labelIds, labelNames, or labelExternalIds (each accepts an array).
• Use includeInactive=true on Get assignments to include expired and removed assignments alongside active ones.
• Removing an assignment is permanent and takes effect immediately.

QuickStart: set up and apply labels

Use this sequence when tagging entities for the first time. Follow the order to avoid dependency errors.

Step 1: Create labels

Define labels scoped to the target entity type (CUSTOMER, PRODUCT, or STORE). Set the expiry type that matches your use case.

Step 2: Retrieve and verify labels

Use the Get Labels API to confirm label names, external IDs, and expiry configuration before assigning. Results default to PRODUCT entity type and ACTIVE status — pass entityType explicitly if you are working with customers or stores.

Step 3: Create label assignments

Assign labels to entities in batches of up to 100 assignments per request.

Step 4: Retrieve assignments

Use Get Label Assignments to confirm which entities are tagged (up to 10 entity IDs per request), or use Search Label Assignments to query all entities tagged with a specific label.

Step 5: Update or remove assignments

Update assignment expiry as needed, or remove assignments when a tag no longer applies.