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.