> ## Documentation Index
> Fetch the complete documentation index at: https://developer.clopos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Categories

> Retrieve product categories along with their hierarchical structure

## Purpose

Allows you to retrieve your category tree, including subcategories, in a single call.

## HTTP Request

```http theme={null}
GET https://integrations.clopos.com/open-api/v2/categories
```

<Warning>
  This endpoint requires authentication. Include your JWT in the `x-token` header. See [Authentication](/authentication) for how to obtain a token and [Errors](/errors) for error responses.
</Warning>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination (1-based).
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of categories to return (1-999).
</ParamField>

<ParamField query="parent_id" type="integer">
  Filters records under a specific parent category.
</ParamField>

<ParamField query="type" type="string">
  Category type; `PRODUCT`, `INGREDIENT`, `ACCOUNTING`.
</ParamField>

<ParamField query="include_children" type="boolean" default="true">
  Include child categories in the response.
</ParamField>

<ParamField query="include_inactive" type="boolean" default="false">
  Return inactive categories.
</ParamField>

## Request Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://integrations.clopos.com/open-api/v2/categories?page=1&limit=20&filters%5B0%5D%5B0%5D=type&filters%5B0%5D%5B1%5D=PRODUCT" \
    -H "x-token: oauth_example_token" \
  ```

  ```javascript javascript theme={null}
  const params = new URLSearchParams({
      page: "1",
      limit: "20",
      "filters[0][0]": "type",
      "filters[0][1]": "PRODUCT",
      include_children: "true",
  });

  const response = await fetch(
      `https://integrations.clopos.com/open-api/v2/categories?${params}`,
      {
          headers: {
              "x-token": "oauth_example_token",
          },
      },
  );

  const categories = await response.json();
  ```

  ```python python theme={null}
  import requests

  url = "https://integrations.clopos.com/open-api/v2/categories"
  headers = {
      "x-token": "oauth_example_token",
  }
  params = {
      "page": 1,
      "limit": 20,
      "filters[0][0]": "type",
      "filters[0][1]": "PRODUCT",
      "include_children": True,
  }

  response = requests.get(url, headers=headers, params=params)
  result = response.json()
  ```
</CodeGroup>

## Response

### 200 OK — List of categories

```json theme={null}
{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Pizza",
            "status": 1,
            "hidden": false,
            "type": "PRODUCT",
            "position": null,
            "parent_id": null,
            "depth": 0,
            "color": "00bcd4",
            "children": [],
            "media": [],
            "created_at": "2026-01-28T18:23:53.000000Z",
            "updated_at": "2026-01-28T18:23:53.000000Z"
        },
        {
            "id": 2,
            "name": "Drinks",
            "status": 1,
            "hidden": false,
            "type": "PRODUCT",
            "position": null,
            "parent_id": null,
            "depth": 0,
            "color": "00bcd4",
            "children": [],
            "media": [
                {
                    "uuid": "1d76f22b-c209-4fac-be3a-cfde7b8f0d74",
                    "mime_type": "image/jpeg",
                    "size": 87281,
                    "urls": {
                        "original": "https://cdn.clopos.com/omega/1d76f22b-.../original.jpg",
                        "extra_large": "https://cdn.clopos.com/omega/1d76f22b-.../extra_large.jpg",
                        "thumb": "https://cdn.clopos.com/omega/1d76f22b-.../thumb.jpg"
                    },
                    "blur_hash": "LEIpFsE%t1}TxpENEgaK0iowRktQ",
                    "dimensions": {
                        "width": 612,
                        "height": 459
                    }
                }
            ],
            "created_at": "2026-02-13T16:31:36.000000Z",
            "updated_at": "2026-02-13T16:31:36.000000Z"
        }
    ],
    "total": 2
}
```

### 400 Bad Request — Parameter error

```json theme={null}
{
    "success": false,
    "error": "invalid_parameter",
    "message": "type must be one of PRODUCT, INGREDIENT, ACCOUNTING"
}
```

## Field Reference

### Category Object

| Field        | Type               | Description                                                                                                    |
| ------------ | ------------------ | -------------------------------------------------------------------------------------------------------------- |
| `id`         | integer            | Unique identifier.                                                                                             |
| `name`       | string             | Category name.                                                                                                 |
| `status`     | integer            | `1` = active, `0` = inactive.                                                                                  |
| `type`       | string             | `PRODUCT`, `INGREDIENT`, or `ACCOUNTING`.                                                                      |
| `position`   | integer (nullable) | Display order position.                                                                                        |
| `parent_id`  | integer (nullable) | Parent category ID, `null` for root categories.                                                                |
| `_lft`       | integer            | Left boundary in the nested-set tree. Useful for ordering and subtree queries.                                 |
| `_rgt`       | integer            | Right boundary in the nested-set tree. A category's descendants have `_lft` and `_rgt` values between its own. |
| `depth`      | integer            | Hierarchy level (`0` = root).                                                                                  |
| `color`      | string             | HEX color code (without `#` prefix).                                                                           |
| `hidden`     | boolean            | Whether the category is hidden from menus.                                                                     |
| `children`   | array              | Subcategories (same structure, nested recursively).                                                            |
| `media`      | array              | Image attachments. See [Media object](/common-objects#media).                                                  |
| `created_at` | string             | Creation timestamp (ISO 8601).                                                                                 |
| `updated_at` | string             | Last update timestamp (ISO 8601).                                                                              |

## Notes

* With the `type` parameter, you can call different category collections (menu, ingredient, accounting) from a single endpoint.
* By sending `include_children=false`, you can retrieve only top-level categories; sub-branches are retrieved with separate calls.
* The `depth` field indicates the hierarchy level: `0` for root categories, `1` for first-level children, and so on.
* To see inactive categories, send `include_inactive=true`; otherwise, they are hidden by default.
* In a production environment, adjust pagination values (`page`, `limit`) according to the brand's inventory size.