Use this API to retrieve product categories configured for your organisation and to search or filter them based on your requirements.

Fetch all product categories in the organisation.
Search product categories by category code or name using a prefix-based search.
Retrieve specific categories using category codes or category IDs.
Fetch only root-level categories (categories without a parent).
Retrieve parent–child category hierarchies for a single category.
Paginate and sort category results.
Filter categories by organisation unit (OU) when OU support is enabled.
Control the fetch scope using ALL, ORG, or SCOPE.

The response includes category details, hierarchy information (when requested), attribution metadata, pagination details, and any applicable warnings.

Example request

curl --location 'https://eu.api.capillarytech.com/v2/product/categories' \
--header 'Authorization: Basic =' \
--header 'Cookie: _cfuvid=Y.CE0cLFeZ23GEphcU4m6DAiMpC6h0VSaCmCV2JdZ30-1762424176935-0.0.1.1-604800000'

curl --location 'https://nightly.api.capillarytech.com/v2/product/categories?entityCodes=%E8%AF%A6%E7%BB%86%E6%8F%8F%E8%BF%B0%2CfirstName0_190704' \
--header 'Authorization: Basic bY0YjA3MTUyZDIzNGI3MA==' \
--header 'Cookie: _cfuvid=adIdLElC8oafEHIbx7hw7GbX277Vu_kA.mTpq2xD18k-1762750332464-0.0.1.1-604800000'

curl --location 'https://nightly.api.capillarytech.com/v2/product/categories?q=cate' \
--header 'Authorization: Basic ==' \
--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	Search product categories by their code (name). Returns categories starting with the specified string. Case-insensitive, UTF-8, max 30 characters.If provided with entityCodes or entityIds, a warning is returned and other filters are ignored.
`entityCodes`	string	Optional	Single or comma-separated product category codes. Max 30 codes, max 50 characters each. Example: apparel, groceries. Used only when q is not provided. Ignored if q is present.
`entityIds`	string	Optional	Single or comma-separated list of product category IDs. Max 30 IDs. Example: 1999, 2000. Used only when q and entityCodes are not provided. Ignored if q or entityCodes are present.
`root`	boolean	Optional	If set to true, it retrieves only root-level product categories (no parent). Default: false. Cannot be used with entityCodes or entityIds filters.
`includeChildren`	boolean	Optional	Includes parent and children in the response. If used with a child entity, returns its parent and siblings. Default: false. Only works with a single entityCodes or entityIds. If multiple are passed, it applies to the first and issues a warning.
`childrenLimit`	integer	Optional	Maximum number of child product categories to include when includeChildren=true. - Default: 10,- Maximum supported value: 20.
`childrenOffset`	integer	Optional	Number of child product categories to skip when includeChildren=true. Use for paginating through children. Default: 0.
`limit`	integer	Optional	Maximum number of product categories to retrieve. Default: 10, Max: 100.
`offset`	integer	Optional	Number of product categories to skip from the beginning of the result set 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: ASC.
`ouCode`	string	Optional	Organization unit code. Used to filter by OU when enabled.
`fetchType`	string	Optional	Scope of product categories to fetch. Values: ALL (master org and OU), ORG (master only), SCOPE (OU only).

Example response

{
    "data": [
        {
            "id": 10173900,
            "orgId": 50583,
            "ouId": -1,
            "code": "category",
            "name": "category",
            "attribution": {
                "createdBy": 15000449,
                "createdDate": "2022-08-31T00:00:00+05:30",
                "modifiedDate": "2022-08-31T00:00:00+05:30"
            }
        },
        {
            "id": 10173901,
            "orgId": 50583,
            "ouId": 50025951,
            "code": "categoryou",
            "name": "categoryou",
            "attribution": {
                "createdBy": 15000449,
                "createdDate": "2022-09-01T00:00:00+05:30",
                "modifiedDate": "2022-09-01T00:00:00+05:30"
            }
        },
        {
            "id": 10192201,
            "orgId": 50583,
            "ouId": -1,
            "code": "cycleCategory",
            "name": "cycleCategory",
            "parent": {
                "id": 10173900,
                "code": "category",
                "name": "category"
            },
            "attribution": {
                "createdBy": 15000449,
                "createdDate": "2022-12-28T00:00:00+05:30",
                "modifiedDate": "2022-12-28T00:00:00+05:30"
            }
        },
        {
            "id": 10192202,
            "orgId": 50583,
            "ouId": -1,
            "code": "cycle1",
            "name": "cycle1",
            "attribution": {
                "createdBy": 50019411,
                "createdDate": "2022-12-28T00:00:00+05:30",
                "modifiedDate": "2022-12-28T00:00:00+05:30"
            }
        },
        {
            "id": 10192203,
            "orgId": 50583,
            "ouId": -1,
            "code": "cycle2",
            "name": "cycle2",
            "parent": {
                "id": 10192202,
                "code": "cycle1",
                "name": "cycle1"
            },
            "attribution": {
                "createdBy": 50019411,
                "createdDate": "2022-12-28T00:00:00+05:30",
                "modifiedDate": "2022-12-28T00:00:00+05:30"
            }
        },
        {
            "id": 11233726,
            "orgId": 50583,
            "ouId": -1,
            "code": "cate1",
            "name": "cate1",
            "parent": {
                "id": 10173900,
                "code": "category",
                "name": "category"
            },
            "attribution": {
                "createdBy": 50685536,
                "createdDate": "2023-10-30T00:00:00+05:30",
                "modifiedDate": "2023-10-30T00:00:00+05:30"
            }
        },
        {
            "id": 11233727,
            "orgId": 50583,
            "ouId": -1,
            "code": "cate2",
            "name": "cate2",
            "parent": {
                "id": 10173900,
                "code": "category",
                "name": "category"
            },
            "attribution": {
                "createdBy": 50685536,
                "createdDate": "2023-10-30T00:00:00+05:30",
                "modifiedDate": "2023-10-30T00:00:00+05:30"
            }
        },
        {
            "id": 11233728,
            "orgId": 50583,
            "ouId": -1,
            "code": "cate3",
            "name": "cate3",
            "parent": {
                "id": 10173900,
                "code": "category",
                "name": "category"
            },
            "attribution": {
                "createdBy": 50685536,
                "createdDate": "2023-10-30T00:00:00+05:30",
                "modifiedDate": "2023-10-30T00:00:00+05:30"
            }
        },
        {
            "id": 11233729,
            "orgId": 50583,
            "ouId": -1,
            "code": "cate4",
            "name": "cate4",
            "parent": {
                "id": 10173900,
                "code": "category",
                "name": "category"
            },
            "attribution": {
                "createdBy": 50685536,
                "createdDate": "2023-10-30T00:00:00+05:30",
                "modifiedDate": "2023-10-30T00:00:00+05:30"
            }
        },
        {
            "id": 11233730,
            "orgId": 50583,
            "ouId": -1,
            "code": "cate5",
            "name": "cate5",
            "parent": {
                "id": 10173900,
                "code": "category",
                "name": "category"
            },
            "attribution": {
                "createdBy": 50685536,
                "createdDate": "2023-10-30T00:00:00+05:30",
                "modifiedDate": "2023-10-30T00:00:00+05:30"
            }
        }
    ],
    "pagination": {
        "limit": 10,
        "offset": 0,
        "total": 216
    }
}

Response parameters

Field	Type	Description
`data`	array	Array of product category objects matching the query.
`.id`	long	Unique identifier of the product category.
`.code`	string	product categorycode.
`.name`	string	product category name.
`.description`	string	Product category description.
`.ouId`	long	Organization unit ID. `-1` indicates the product category belongs to the master organization.
`.parent`	object	Parent product category information (only when `includeChildren=true`).
`.parent.id`	long	Parent product category ID.
`.parent.code`	string	Parent product category code.
`.parent.name`	string	Parent product category name.
`.children`	array	Array of child product categories (only when `includeChildren=true`).
`..id`	long	Child product category ID.
`..code`	string	Child product category code.
`..name`	string	Child product category name.
`.attribution`	object	Information about who created and last updated the product category.
`..createdBy`	long	User ID who created the product category.
`..createdOn`	string	Timestamp when the product category was created. Returned in ISO 8601 format with the organisation's configured timezone offset.
`..updatedBy`	long	User ID who last updated the product category.
`..updatedOn`	string	Timestamp when the product category was last updated. Returned in ISO 8601 format with the organisation's configured timezone offset.
`pagination`	object	Pagination information.
`.limit`	integer	Number of results per page.
`.offset`	integer	Number of results skipped.
`.total`	integer	Total number of product categories matching the query.
`warnings`	array	Array of warning messages (if any).

Error & warning codes

Code	Type	Description
10007	Error	You can pass a maximum of 30 `entityCodes`. The request included more than 30 values.
10008	Error	You can pass a maximum of 30 `entityIds`. The request included more than 30 values.
10004	Error	The `limit` value cannot be more than 100.
10005	Error	The `limit` value must be greater than 0.
10006	Error	The `offset` value cannot be negative.
10002	Error	OU-level product filtering is disabled for your organisation, but an `ouCode` was provided. Remove the `ouCode` parameter or contact your administrator.
10001	Error	The provided `ouCode` does not exist or is invalid. Check the code and try again.
10009	Warning	The `q` parameter was used. The `entityCodes` and `entityIds` filters were ignored.
10010	Warning	The `entityCodes` filter was used. The `entityIds` filter was ignored.
10014	Warning	The `sortBy` parameter is invalid. Results are sorted by `id` by default.
10016	Warning	The `includeChildren` parameter works only for a single entity. It was ignored for this request.
10017	Warning	The `root` parameter cannot be used with `entityCodes` or `entityIds`. It was ignored for this request.
10011	Warning	One or more blank values were found in `entityCodes` or `entityIds`. These values were ignored.
10012	Warning	Some `entityIds` contain non-numeric values. These values were ignored.
10013	Warning	All provided `entityIds` were invalid. The API returned all available entities instead.