Update labels (PUT)

Updates one or more labels in bulk. An organization can update up to 10 labels per request. Supplying expiryConfig replaces the label's existing expiry configuration entirely.

Example request

curl -X PUT "https://{host}/api_gateway/v2/labels" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": [
      {
        "id": 101,
        "name": "Winter Sale",
        "status": "ACTIVE",
        "expiryConfig": {
          "type": "RELATIVE",
          "duration": 30,
          "durationType": "DAYS"
        }
      }
    ]
  }'

Prerequisites

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

Body parameters

Note: The Updatable column indicates whether a field can be changed after creation. Fields marked No are identifiers used to locate the label.

Field	Type	Required	Description	Updatable
`labels`	array	Required	List of label update objects. Maximum 10 per request.	—
`.id`	integer	Required	System-assigned identifier of the label to update.	No
`.name`	string	Optional	New display name. Max 255 characters. Must be unique within the entity type.	Yes
`.externalId`	string	Optional	New caller-defined identifier. Max 255 characters. Must be unique within the entity type if provided.	Yes
`.description`	string	Optional	New description. Max 1024 characters.	Yes
`.status`	enum	Optional	New label status. One of: `ACTIVE`, `ARCHIVED`.	Yes
`.expiryConfig`	object	Optional	New expiry configuration. Replaces the existing configuration entirely when supplied.	Yes
`..type`	enum	Required	Expiry type. One of: `NONE`, `FIXED_DATE`, `RELATIVE`.	Yes
`..date`	string	Conditional	Required when `type` is `FIXED_DATE`. ISO-8601 UTC date-time (`YYYY-MM-DDThh:mm:ssZ`). Must be a future date.	Yes
`..duration`	integer	Conditional	Required when `type` is `RELATIVE`. Positive integer representing the number of duration units.	Yes
`..durationType`	enum	Conditional	Required when `type` is `RELATIVE`. One of: `DAYS`, `MONTHS`, `YEARS`.	Yes

Example response

{
  "data": [
    {
      "id": 101,
      "externalId": "SUMMER_SALE",
      "name": "Winter Sale",
      "description": "Products eligible for winter promotions",
      "entityType": "PRODUCT",
      "expiryConfig": {
        "type": "RELATIVE",
        "duration": 30,
        "durationType": "DAYS"
      },
      "status": "ACTIVE",
      "createdOn": "2026-01-15T10:00:00Z",
      "createdBy": 5001,
      "lastUpdatedOn": "2026-05-29T08:30:00Z",
      "lastUpdatedBy": 5001
    }
  ]
}

Response parameters

Field	Type	Description
`data`	array	Updated label objects.
`.id`	integer	System-assigned unique identifier.
`.externalId`	string	Caller-defined identifier, or null if not set.
`.name`	string	Current display name.
`.description`	string	Current description, or null if not set.
`.entityType`	string	Entity type: `CUSTOMER`, `PRODUCT`, or `STORE`.
`.expiryConfig`	object	Current expiry configuration.
`..type`	string	Expiry type: `NONE`, `FIXED_DATE`, or `RELATIVE`.
`..date`	string	Expiry date in UTC. Present only when type is `FIXED_DATE`.
`..duration`	integer	Number of duration units. Present only when type is `RELATIVE`.
`..durationType`	string	Duration unit: `DAYS`, `MONTHS`, or `YEARS`. Present only when type is `RELATIVE`.
`.status`	string	Current status: `ACTIVE` or `ARCHIVED`.
`.createdOn`	string	ISO-8601 timestamp when the label was created.
`.createdBy`	integer	User ID of the creator.
`.lastUpdatedOn`	string	ISO-8601 timestamp of the most recent update.
`.lastUpdatedBy`	integer	User ID of the most recent editor.

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.