Use this API to retrieve product attribute definitions configured for your organisation. Product attributes define customizable properties of products and SKUs, such as material, colour, and size.

You can fetch attributes in bulk or retrieve specific attributes using attribute codes or attribute IDs.
You can search attributes by code using the first few words of the code.
You can include default (possible) attribute values when retrieving a single attribute.
Pagination is supported for both attributes and their possible values.
When OU support is enabled, you can:
- Filter attributes by organisation unit (OU)
- Control the fetch scope using ALL, ORG, or SCOPE

The response includes attribute metadata, data types, optional default values, attribution information, and pagination details.

Example request

curl --location 'https://eu.api.capillarytech.com/v2/product/attributes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ' \
--header 'Cookie: _cfuvid=0fWt9yy.y2VwqKIUGVfG8rQPhyPlJgq44GDboQpHIdE-1762514855992-0.0.1.1-604800000'

curl --location 'https://nightly.api.capillarytech.com/v2/product/attributes?entityCodes=firstName_9749135%2CfirstName_7998165' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic 0YjA3MTUyZDIzNGI3MA==' \
--header 'Cookie: _cfuvid=adIdLElC8oafEHIbx7hw7GbX277Vu_kA.mTpq2xD18k-1762750332464-0.0.1.1-604800000'

curl --location 'https://nightly.api.capillarytech.com/v2/product/attributes?q=first' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic b3JnMi50aWxsMMTUyZDIzNGI3MA==' \
--header 'Cookie: _cfuvid=adIdLElC8oafEHIbx7hw7GbX277Vu_kA.mTpq2xD18k-1762750332464-0.0.1.1-604800000'

Prerequisites

Basic/OAuth authentication

Resource information


Pagination support	Yes
Batch support	Yes

Query Parameters

Field	Type	Required	Description
`q`	string	Optional	Searches product attributes by their name/code. This returns product attributes whose names start with the specified query string. • If provided with entityCodes or entityIds, a warning is returned and the other filters are ignored. • Case-insensitive; supports UTF-8 characters. • Maximum 30 characters.
`entityCodes`	string	Optional	A single or comma-separated list of product attributes `code. Use the code parameter from the response of the Add Product attribute API.Used when` q` parameter is not provided. This parameter is ignored if `q` parameter is provided. Format: Case-insensitive; supports UTF-8 characters. Limits: Maximum 30 codes; 50 characters per code.
`entityIds`	string	Optional	A single or comma-separated list of product attribute `id`. Use the value of the `id` parameter from the response of the Add Product attribute API. Limits: Maximum 30 ID's. This parameter is ignored if the query parameter `q` or `entityCodes` are provided. Example: 1999, 2000
`includeValues`	boolean	Optional	Includes the default values for the attribute in the response. Only works when retrieving a single product category using `entityCodes` or `entityIds`. If multiple are passed, the API applies it to the first one and issues a warning. Default: false
`valuesLimit`	integer	Optional	Maximum number of attributes to include when includeValues=true. Default: 10. Maximum supported values: 20
`valuesOffset`	integer	Optional	Number of default attribute values to skip when includeValues=true. Default: 0.
`limit`	integer	Optional	Maximum number of product attributes to retrieve. Default limit: 10. Maximum supported limit: 100.
`offset`	integer	Optional	Number of product attributes to skip from the beginning of the result set. Use for pagination.
`sortBy`	string	Optional	Field to sort by. Supported values: `id`, code. Default: `id`.
`sortOrder`	string	Optional	Sort direction. Supported values: `ASC`, `DESC`. Default:`DESC` .
`ouCode`	string	Optional	Organization unit code. Use to filter product attributes by organizational unit when OU support is enabled.
`fetchType`	string	Optional	Scope of product attributes to fetch. Supported Values: ALL (master org and OU), ORG (master org only), SCOPE (OU only).

Example response

{
    "data": [
        {
            "id": 91381,
            "orgId": 50583,
            "ouId": -1,
            "code": "Material",
            "name": "Fabric Material",
            "type": "String",
            "possibleValues": {
                "data": [
                    {
                        "id": 13544113,
                        "code": "Cotton",
                        "name": ""
                    },
                    {
                        "id": 13544114,
                        "code": "Polyester",
                        "name": ""
                    }
                ],
                "pagination": {
                    "limit": 10,
                    "offset": 0,
                    "total": 2
                }
            },
            "attribution": {
                "createdBy": 50019411,
                "createdDate": "2025-09-19T00:00:00+05:30"
            }
        }
    ],
    "pagination": {
        "limit": 50,
        "offset": 0,
        "total": 1
    }
}

{
    "data": [
        {
            "id": 56319,
            "orgId": 50583,
            "ouId": -1,
            "code": "attribute1",
            "name": "attribute1",
            "type": "String",
            "attribution": {
                "createdBy": 15000449,
                "createdDate": "2022-08-31T00:00:00+05:30"
            }
        },
        {
            "id": 56320,
            "orgId": 50583,
            "ouId": 50025951,
            "code": "attributeou",
            "name": "attributeou",
            "type": "String",
            "attribution": {
                "createdBy": 15000449,
                "createdDate": "2022-09-01T00:00:00+05:30"
            }
        },
        {
            "id": 58593,
            "orgId": 50583,
            "ouId": -1,
            "code": "orange",
            "type": "String",
            "defaultValue": {
                "id": 12536916,
                "code": "na",
                "name": "na1"
            },
            "attribution": {
                "createdBy": 0
            }
        },
        {
            "id": 58594,
            "orgId": 50583,
            "ouId": -1,
            "code": "Category4_code",
            "name": "Category4_code",
            "type": "String",
            "attribution": {
                "createdBy": 50685437,
                "createdDate": "2024-07-02T00:00:00+05:30"
            }
        },
        {
            "id": 58595,
            "orgId": 50583,
            "ouId": -1,
            "code": "Category4_description",
            "name": "Category4_description",
            "type": "String",
            "attribution": {
                "createdBy": 50685437,
                "createdDate": "2024-07-02T00:00:00+05:30"
            }
        },
        {
            "id": 58596,
            "orgId": 50583,
            "ouId": -1,
            "code": "Brand",
            "name": "Brand",
            "type": "String",
            "attribution": {
                "createdBy": 50685437,
                "createdDate": "2024-07-02T00:00:00+05:30"
            }
        },
        {
            "id": 58597,
            "orgId": 50583,
            "ouId": -1,
            "code": "Return_window",
            "name": "Return_window",
            "type": "String",
            "attribution": {
                "createdBy": 50685437,
                "createdDate": "2024-07-02T00:00:00+05:30"
            }
        },
        {
            "id": 58598,
            "orgId": 50583,
            "ouId": -1,
            "code": "Parent_Category",
            "name": "Parent_Category",
            "type": "String",
            "attribution": {
                "createdBy": 50685437,
                "createdDate": "2024-07-02T00:00:00+05:30"
            }
        },
        {
            "id": 58599,
            "orgId": 50583,
            "ouId": -1,
            "code": "L1_Category_code",
            "name": "L1_Category_code",
            "type": "String",
            "attribution": {
                "createdBy": 50685437,
                "createdDate": "2024-07-02T00:00:00+05:30"
            }
        },
        {
            "id": 58600,
            "orgId": 50583,
            "ouId": -1,
            "code": "Category1_description",
            "name": "Category1_description",
            "type": "String",
            "attribution": {
                "createdBy": 50685437,
                "createdDate": "2024-07-02T00:00:00+05:30"
            }
        }
    ],
    "pagination": {
        "limit": 10,
        "offset": 0,
        "total": 21
    }
}

Response Parameters

Field	Type	Description
`data`	array	Array of attribute objects matching the query.
`.id`	long	Unique identifier of the attribute.
`.orgId`	long	Organisation ID that owns the attribute.
`.ouId`	long	Organisational unit ID. `-1` indicates the attribute belongs to the master organisation.
`.code`	string	Attribute code/name.
`.name`	string	Attribute display name (label on the UI).
`.type`	string	Data type of the attribute (for example, `String`, `Integer`, `Boolean`, `Decimal`).
`.possibleValues`	object	Container for the attribute’s permissible values and their pagination details. Appears only if `includeValues=true`.
`..data`	array	Array of possible attribute value objects.
`...id`	long	Possible Attribute value ID.
`...code`	string	Possible attribute value name.
`...name`	string	Attribute value display name (can be blank).
`..pagination`	object	Pagination information for `possibleValues`.
`...limit`	integer	Number of values returned per page.
`...offset`	integer	Number of values skipped.
`...total`	integer	Total number of values matching the query.
`.attribution`	object	Information about who created and last updated the attribute.
`..createdBy`	long	User ID that created the attribute.
`..createdDate`	string	Timestamp when the attribute was created. Returned in ISO 8601 format with the organisation’s configured timezone offset (for example, `+05:30`).
`..updatedBy`	long	User ID that last updated the attribute. Present only if the platform records updates for this entity.
`..updatedDate`	string	Timestamp when the attribute was last updated. ISO 8601 with organisation timezone offset. Present only if recorded.
`pagination`	object	Pagination information for the top-level `data` list.
`.limit`	integer	Number of results per page.
`.offset`	integer	Number of results skipped.
`.total`	integer	Total number of attributes matching the query.
`warnings`	array	Array of warning messages (if any).

Error & warning codes

Code	Type	Description
10007	Error	entityCodes cannot have more than 30 comma-separated values.
10008	Error	entityIds cannot have more than 30 comma-separated values.
10004	Error	Pagination limit cannot exceed more than 100.
10005	Error	Pagination limit cannot be zero or negative.
10006	Error	Pagination offset cannot be negative.
10002	Error	OU level product filtering is disabled for your organization, but an `ouCode` was provided.
10001	Error	The provided `ouCode` is invalid or does not exist.
10009	Warning	Searching by `q` parameter; `entityCodes` and `entityIds` were ignored.
10010	Warning	Searching by `entityCodes`; `entityIds` was ignored.
10015	Warning	`includeValues` is only supported for single entity search and was ignored.
10014	Warning	Invalid `sortBy` parameter. Defaulting to sort by `id`.
10011	Warning	One or more blank values provided in `entityCodes` or `entityIds` were ignored.
10012	Warning	One or more non-numeric values provided in `entityIds` were ignored.
10013	Warning	All provided `entityIds` were invalid and ignored; the query fetches all entities.