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

# List categories

> Returns the paginated list of categories in your store.

**app\_id** `string` *required*

Your store ID in Jelou Shop.

**paginate** `boolean` (default: true)

Send `false` to get all categories without pagination.

**include** `string`

Use `products` to include each category's products in the response.

**sort** `string`

Ordering, as a comma-separated list. Prefix with `-` for descending order (e.g. `sort=order,-name`). Sortable fields: `order`, `name`, `created_at`. Unknown fields are ignored.

**branch\_id** `string`

Filter categories by branch. Controls which categories are returned:

* **Omitted** → only **global** categories (no branch, `branch_id` null).
* `branch_id=<uuid>` → only that branch's categories.
* `branch_id=*` → categories from **all** branches (and global ones).

**branch** `string`

Filter categories by a branch **code**. If the code does not exist, the response is empty. Takes precedence over `branch_id`.

**tree** `boolean` (default: false)

Send `true` to get categories as a **nested tree** by `parent_id`. See [Tree mode](#tree-mode).

```bash cURL theme={null}
curl "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/categories?sort=order&branch_id=*" \
  -H "x-api-key: YOUR_API_KEY"
```

```json 200 Success theme={null}
{
  "data": [
    {
      "id": 1,
      "name": "Pizzas",
      "image": "categories/664f1a2b3c4d5.jpg",
      "description": "All our artisan pizzas",
      "order": 1,
      "status": true,
      "app_id": "8af29efb-9864-4f29-888c-b2dd0d7ac1dd",
      "branch_id": "9e3f2c1a-8b7d-4e6f-a5c4-d3b2a1e0f9c8",
      "parent_id": null,
      "created_at": "2026-02-19T15:30:00.000000Z",
      "updated_at": "2026-02-19T15:30:00.000000Z"
    },
    {
      "id": 2,
      "name": "Beverages",
      "image": null,
      "description": "Hot and cold beverages",
      "order": 2,
      "status": true,
      "app_id": "8af29efb-9864-4f29-888c-b2dd0d7ac1dd",
      "branch_id": null,
      "parent_id": null,
      "created_at": "2026-02-19T15:35:00.000000Z",
      "updated_at": "2026-02-19T15:35:00.000000Z"
    }
  ],
  "links": {
    "first": "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/categories?page=1",
    "last": "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/categories?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 15,
    "to": 2,
    "total": 2
  }
}
```

> [!TIP]
>
> **Filterable fields:** `status`, `branch_id`
> **Searchable fields:** `name`
> **Sortable fields:** `order`, `name`, `created_at`

> [!NOTE]
>
> The `parent_id` field indicates the parent category (hierarchy). It is `null` for root categories. The `products_count` value is **only** returned in [tree mode](#tree-mode), not in the flat listing.

## Tree mode

With `tree=true`, the response returns categories nested by `parent_id`. Each node adds:

* `children`: array of subcategories (same structure, recursive).
* `children_count`: number of direct children.
* `products_count`: number of **active** products in that category.

The `branch`, `branch_id`, `status` and `sort` filters also apply in this mode. The tree response is **not** paginated.

```json 200 Tree theme={null}
{
  "data": [
    {
      "id": 1,
      "name": "Pizzas",
      "image": "categories/664f1a2b3c4d5.jpg",
      "description": "All our artisan pizzas",
      "order": 1,
      "status": true,
      "app_id": "8af29efb-9864-4f29-888c-b2dd0d7ac1dd",
      "branch_id": null,
      "parent_id": null,
      "products_count": 12,
      "created_at": "2026-02-19T15:30:00.000000Z",
      "updated_at": "2026-02-19T15:30:00.000000Z",
      "children_count": 1,
      "children": [
        {
          "id": 5,
          "name": "Premium Pizzas",
          "order": 1,
          "status": true,
          "app_id": "8af29efb-9864-4f29-888c-b2dd0d7ac1dd",
          "branch_id": null,
          "parent_id": 1,
          "products_count": 4,
          "children_count": 0,
          "children": []
        }
      ]
    }
  ]
}
```

> [!NOTE]
>
> Replace `{app_id}` with your store ID and `YOUR_API_KEY` with your [API key](https://docs.jelou.ai/en/guides/settings/api-keys.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.