get
https://{Host}/v2/labels
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Retrieve a paginated list of labels for an organization. Filter results by entity type, status, or a search term that matches label names or external IDs.
Example request
curl -X GET "https://{host}/v2/labels?entityType=PRODUCT&status=ACTIVE&limit=50&offset=0" \
-H "Authorization: Basic {base64_credentials}"Prerequisites
- Basic authentication (
Authorization: Basic {base64_credentials}) or OAuth (X-CAP-API-OAUTH-TOKEN).
Resource information
| Pagination support | Yes |
| Batch support | No |
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
entityType | enum | Optional | Filters labels by entity type. Supported values: CUSTOMER, PRODUCT, STORE. Defaults to PRODUCT. |
q | string | Optional | Search term to filter labels by name or external ID. Matches partial strings. |
status | enum | Optional | Filters labels by status. Supported values: ACTIVE, ARCHIVED. Defaults to ACTIVE. |
limit | number | Optional | Maximum number of labels to return per page. Between 1 and 100. Defaults to 50. |
offset | number | Optional | Number of records to skip for pagination. Must be 0 or greater. Defaults to 0. |
Example response
{
"totalCount": 120,
"limit": 50,
"offset": 0,
"labels": [
{
"id": 101,
"externalId": "summer-sale-2026",
"name": "Summer Sale",
"description": "Labels for summer sale products",
"entityType": "PRODUCT",
"expiryConfig": {
"type": "FIXED_DATE",
"expiryDate": "2027-12-31T23:59:59+05:30"
},
"status": "ACTIVE",
"createdOn": "2026-06-04T10:42:24Z",
"createdBy": 75216507,
"lastUpdatedOn": "2026-06-04T10:46:43Z",
"lastUpdatedBy": 75216507
}
]
}Response parameters
| Field | Type | Description |
|---|---|---|
totalCount | number | Total number of labels matching the filter criteria. |
limit | number | Maximum number of labels returned in this response. |
offset | number | Number of records skipped. |
labels | array | List of label objects. |
.id | number | Unique identifier of the label. |
.externalId | string | External identifier of the label. |
.name | string | Name of the label. |
.description | string | Description of the label. |
.entityType | string | Entity type the label applies to. One of CUSTOMER, PRODUCT, or STORE. |
.expiryConfig | object | Expiry configuration for the label. |
..type | string | Expiry type. One of NONE, FIXED_DATE, or RELATIVE. |
..expiryDate | string | Expiry date in ISO-8601 format. Present when type is FIXED_DATE. |
..unit | string | Duration unit. Present when type is RELATIVE. One of DAYS, MONTHS, or YEARS. |
..value | number | Duration value. Present when type is RELATIVE. |
..roundingUnit | string | Rounding unit for the expiry duration. Present when type is RELATIVE and a rounding unit is configured. |
.status | string | Status of the label. One of ACTIVE or ARCHIVED. |
.createdOn | string | UTC timestamp when the label was created. Format: YYYY-MM-DDThh:mm:ssZ. |
.createdBy | number | ID of the user who created the label. |
.lastUpdatedOn | string | UTC timestamp when the label was last updated. Format: YYYY-MM-DDThh:mm:ssZ. |
.lastUpdatedBy | number | ID of the user who last updated the label. |
Error and warning codes
Note: Validation errors for this endpoint are returned as
{"message": "<error description>"}rather than the standarderrorsarray.
| Code | Error number | Type | Description |
|---|---|---|---|
LABEL_INVALID_ENTITY_TYPE | 23006 | Error | Invalid entity type. Supported values: CUSTOMER, PRODUCT, STORE. HTTP 400. |
LABEL_INVALID_STATUS | 23016 | Error | Invalid status value. Supported values: ACTIVE, ARCHIVED. HTTP 400. |
LABEL_INVALID_LIMIT | 23017 | Error | limit must be between 1 and 100. HTTP 400. |
LABEL_INVALID_OFFSET | 23018 | Error | offset must be 0 or greater. HTTP 400. |