Get All Categories

This endpoint retrieves a list of all categories in the system, along with their details.

Endpoint

• URL: /categories
• Method: GET

Authentication

• Header: accessToken
• Type: Bearer Token
• Value: <ACCESS-TOKEN>

Request Headers

Header	Type	Description
accessToken	string	Access token for authentication. (required)

Query Parameters

Parameter	Type	Description
page	number	The page number of results you want to retrieve. Defaults to 1.
limit	number	The number of results to retrieve per page. Defaults to 10.
name	string	Filter categories by matching names. Supports partial matching with regex and case-insensitivity.
parentId	string	Filter categories with a specific parent category ID.
parentId:in	string	Filter categories by matching any of the provided parent category IDs. Accepts a comma-separated list.
isVisible	boolean	Filter by categories that are marked as visible (true) or not visible (false).
hasParent	boolean	Filter categories that have a parent (true) or do not have a parent (false).
hasChildren	boolean	Filter categories that have children (true) or do not have children (false).
id	string	Filter categories with a specific ID.
id:in	string	Filter categories by matching any of the provided IDs. Accepts a comma-separated list.
date_created:min	date	Filter categories created on or after the specified date (inclusive).
date_created:max	date	Filter categories created on or before the specified date (inclusive).
date_modified:min	date	Filter categories last updated on or after the specified date (inclusive).
date_modified:max	date	Filter categories last updated on or before the specified date (inclusive).
metafields:key	string	(Advanced) Filter by metafields with a specific key. Available with prefixes like metafields-in: or metafields:.

Notes

• Date Format: When using date filters, ensure the dates are in an internationally recognized format such as ISO 8601 (YYYY-MM-DD, YYYY-MM-DDTHH:MM:SSZ).
• Logical Operators in Filters: Some parameters like parentId:in and id:in allow you to specify multiple values. The API will match any of the provided values.
• Metafields Filtering: Use metafields-in:<key> or metafields:<key> for complex filtering on metafields. This mechanism supports both equality and inclusion checks.

Sample Request

curl --location '<BASE-TOKEN>/categories' \
--header 'accessToken: <ACCESS-Token>'

Response

• Status Code: 200 OK

Sample Response Body

{
  "success": true,
  "data": [
    {
      "name": "Electrical",
      "url": "Electrical",
      "path": "/663a0cbe516313e5bc94aa87/",
      "hasParent": false,
      "hasChildren": true,
      "productCount": 15,
      "metaFields": [],
      "isShow": true,
      "sortOrder": 1,
      "createdAt": "2024-05-07T11:13:02.066Z",
      "updatedAt": "2024-10-09T13:05:59.036Z",
      "description": null,
      "image": null,
      "parentCategory": "6661711bd3c692a94b34cb86",
      "seo": null,
      "id": "663a0cbe516313e5bc94aa87"
    }
    // Additional category entries
  ],
  "pagination": {
    "page": 1,
    "total": 29,
    "count": 10
  }
}

Response Structure

General Response Fields

Field	Type	Description
success	boolean	Indicates whether the request was successful.
data	array	An array of category objects. See Category Object for details.
pagination	object	Contains pagination details. See Pagination Object.

Category Object

Each object in the data array includes the following fields:

Field	Type	Description
name	string	Name of the category.
url	string	URL path segment for the category.
path	string	The hierarchical path representation of the category.
hasParent	boolean	Indicates if the category has a parent.
hasChildren	boolean	Indicates if the category has children.
productCount	number	Number of products in the category.
metaFields	array	Additional metadata fields, currently empty.
isShow	boolean	Flag indicating if the category is visible.
sortOrder	number	Order for sorting categories.
createdAt	string	Timestamp when the category was created (ISO format).
updatedAt	string	Timestamp when the category was last updated (ISO format).
description	string?	Description or details about the category.
image	string?	URL of the image representing the category.
parentCategory	string?	ID of the parent category, if applicable.
seo	object?	SEO related fields, if any.
id	string	Unique identifier of the category.

Pagination Object

The pagination object includes the following fields:

Field	Type	Description
page	number	The current page of the results.
total	number	The total number of categories available.
count	number	The number of categories returned on this page.

Notes

• Ensure that you provide a valid accessToken in the request header to access the API.
• The response includes pagination details to manage large data sets effectively.
• Some fields such as description, image, parentCategory, and seo may be null if not set.