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.