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

# List Product Categories

> Retrieve active, public product categories.

Returns a paginated list of product categories; inactive and internal categories are always excluded.

## Query parameters

**limit** `number` (default: 50)

Maximum number of categories to return.

**offset** `number` (default: 0)

Number of categories to skip before collecting results.

**order** `string`

Field to sort by, prefixed with `-` for descending order.

**fields** `string`

Comma-separated fields and relations to include; prefix with `+`/`-` to add to or remove from the defaults.

**q** `string`

Free-text search term applied to category fields.

**id** `string | string[]`

Filter by one or more category IDs.

**handle** `string | string[]`

Filter by one or more category handles.

**parent\_category\_id** `string | string[]`

Filter by parent category ID; pass `null` to fetch top-level categories.

**include\_ancestors\_tree** `boolean`

Include each category's ancestors in `parent_category`.

**include\_descendants\_tree** `boolean`

Include each category's descendants in `category_children`.

**created\_at** `object`

Filter by creation date using operators like `$gt`, `$gte`, `$lt`, `$lte`.

**updated\_at** `object`

Filter by update date using operators like `$gt`, `$gte`, `$lt`, `$lte`.

**\$and** `object[]`

Join multiple filter objects with a logical AND.

**\$or** `object[]`

Join multiple filter objects with a logical OR.

## Response

**product\_categories** `object[]`

**properties**

**id** `string`

The category's ID.

**name** `string`

The category's name.

**description** `string`

The category's description.

**handle** `string`

URL-safe handle.

**rank** `number`

Sort rank among siblings.

**parent\_category\_id** `string | null`

ID of the parent category.

**parent\_category** `object | null`

The parent category.

**category\_children** `object[]`

Direct child categories.

**metadata** `object | null`

Custom key-value data.

**created\_at** `string`

Creation timestamp.

**updated\_at** `string`

Last update timestamp.

**count** `number`

Total number of matching categories.

**offset** `number`

Number of skipped categories.

**limit** `number`

Maximum number of returned categories.

```bash cURL theme={null}
curl 'http://localhost:9000/store/product-categories?parent_category_id=null&limit=50' \
  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
```

```ts JS Client theme={null}
const { product_categories, count } = await client.store.productCategories.query({
  parent_category_id: "null",
  limit: 50,
})
```

```json 200 theme={null}
{
  "product_categories": [
    {
      "id": "pcat_01JB2K6A2B",
      "name": "Shirts",
      "description": "",
      "handle": "shirts",
      "rank": 0,
      "parent_category_id": null,
      "parent_category": null,
      "category_children": [{ "id": "pcat_01JB2K6H7J", "name": "Linen Shirts" }],
      "metadata": null,
      "created_at": "2026-05-01T10:00:00.000Z",
      "updated_at": "2026-05-01T10:00:00.000Z"
    }
  ],
  "count": 8,
  "offset": 0,
  "limit": 50
}
```


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