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

# List all categories

> Returns paginated product categories for the organization your access token is scoped to, with optional filters on status, opaqueId, and parent.

```http theme={null}
GET $BASE_URL/v1/categories
```

**Returns the categories of your access token's organization, newest first, in the standard [list envelope](/api/pagination) (`data` + `meta`). Deleted categories are excluded.**

> **Auth:** `Authorization: Bearer <accessToken>` — an organization-scoped token from [Authentication](/api/authentication). Results are always scoped to the token's organization; you cannot see another organization's categories.

### Query parameters

`limit` (default `50`, max `250`) and `cursor` follow the shared pagination contract — see [Pagination & filtering](/api/pagination).

### Filterable fields

Filters combine with each other (and with the organization scope) using AND.

| Field | Type | Match | Description |
| - | - | - | - |
| `f[status]` | number | exact / IN | Status code. Comma = IN (`f[status]=1,0`). Deleted records (`-99`) are never returned, regardless of the filter. |
| `f[opaqueId]` | string | exact / IN | Your external category id (see [menu sync](/api/process-transaction#menu-synchronization-lazy-sync)). |
| `f[parent]` | string | exact / IN | Parent category id — lists the direct children of a category. |

> Filtering on any other field returns `invalid_filter_field` (400). A non-numeric value on a numeric field returns `invalid_filter_value` (400), and operator syntax (`f[status][gte]=1`) also returns `invalid_filter_value` — category filters do not support operators.

### Example

```bash theme={null}
curl --request GET \
  --url "$BASE_URL/v1/categories?f%5Bparent%5D=1e1cc0fb-55a1-4679-80df-6dccb936273f&f%5Bstatus%5D=1&limit=50" \
  --header 'Authorization: Bearer <accessToken>'
```

### Response

```json theme={null}
{
  "data": [
    {
      "id": "79a83256-2925-44b4-9bdc-a401caccf969",
      "name": { "TR": "Espresso Bazlı", "EN": "Espresso Based" },
      "description": "Espresso based drinks",
      "organization": "07f84834-1184-4eb6-82f5-7eda13231fc3",
      "status": 1,
      "opaqueId": "espresso-based",
      "parent": "1e1cc0fb-55a1-4679-80df-6dccb936273f",
      "createdAt": "2026-09-18T09:23:28.303Z",
      "updatedAt": "2026-09-18T09:23:28.303Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 50
  }
}
```

Notes:

* `name` may be a plain string or a language object (`"STARTERS"` or `{ "TR": "…" }`) — records created through menu sync usually carry a plain string; be ready for both.
* The sort order is fixed: `createdAt` descending. Pass `cursor` back exactly as received; a malformed cursor returns `invalid_cursor` (400), a `limit` outside 1–250 returns `invalid_limit` (400).
* Root categories have no `parent` field at all — do not expect `null`; the same applies to other optional fields.