API reference / Category / List categories

List categories

Returns a paginated list of categories, newest first by default. Filter by name, sku, parent, availability, audience, and created/updated date ranges to narrow the set.

GET/api/v4/admin/categories

Use case

A catalog admin screen loads the first 20 top-level categories with parent=root&limit=20, then lazy-loads children as the operator expands each node. Because this is the admin route, it returns all categories — including hidden, restricted, and password-protected ones — regardless of storefront visibility.

i

Requires a bearer token with catalog read access. The public route /api/v4/categories returns only storefront-visible categories.

Query parameters

All optional. Combine freely — filters are AND-ed together.

Parameter	Description
limit integerOptional	Max records per page. Default `20`.
offset integerOptional	Pagination offset. Default `0`.
ids stringOptional	Restrict to these category ids (comma list, e.g. `101,102`).
exclude stringOptional	Exclude these category ids (comma list).
searchText stringOptional	Case-insensitive search across name or sku.
name stringOptional	Case-insensitive partial match on name.
sku stringOptional	Case-insensitive partial match on sku.
parent stringOptional	Parent category id, or `root` for top-level only. Recursive when omitted.
isAvailable booleanOptional	Filter by availability. `true` or `false`.
availableFor enumOptional	Audience. One of `everyone`, `customer`, `selected`.
url stringOptional	Exact match on the category url slug.
createdFrom / createdTo dateOptional	Created within this range (`yyyy-MM-dd`).
updatedFrom / updatedTo dateOptional	Updated within this range (`yyyy-MM-dd`).
sortBy enumOptional	Preset sort, e.g. `ALPHA_ASC`, `CREATED_DESC`, `SKU_ASC`, `STATUS_ASC`, `ORDERING_ASC`.
sort stringOptional	Sort field (a valid Category property). Default `updated`.
dir enumOptional	Sort direction. `asc` or `desc`. Default `desc`.

Request

Send the bearer token in the Authorization header. Pick your language:

curl "https://your_site_domain/api/v4/admin/categories?parent=root&limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const res = await fetch(
  "https://your_site_domain/api/v4/admin/categories?parent=root&limit=20",
  { headers: { Authorization: `Bearer ${accessToken}` } },
);
const { data, meta } = await res.json();

<?php
$ch = curl_init("https://your_site_domain/api/v4/admin/categories?parent=root&limit=20");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer $accessToken"],
]);
$result = json_decode(curl_exec($ch), true);

import requests

res = requests.get(
    "https://your_site_domain/api/v4/admin/categories",
    params={"parent": "root", "limit": 20},
    headers={"Authorization": f"Bearer {access_token}"},
)
result = res.json()

var req = HttpRequest.newBuilder()
    .uri(URI.create("https://your_site_domain/api/v4/admin/categories?parent=root&limit=20"))
    .header("Authorization", "Bearer " + accessToken)
    .GET().build();
var res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);
var json = await http.GetStringAsync(
    "https://your_site_domain/api/v4/admin/categories?parent=root&limit=20");

req, _ := http.NewRequest("GET",
    "https://your_site_domain/api/v4/admin/categories?parent=root&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+accessToken)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

final res = await http.get(
  Uri.parse('https://your_site_domain/api/v4/admin/categories?parent=root&limit=20'),
  headers: {'Authorization': 'Bearer $accessToken'},
);
final result = jsonDecode(res.body);

Response

Returns a data array of category objects and a meta block with pagination totals.

Body

200 OK · application/json

{
  "data": [
    {
      "id": 101,
      "name": "Outdoor Furniture",
      "sku": "CAT-OUTDOOR-001",
      "url": "outdoor-furniture",
      "available": true,
      "visible": true,
      "available_for": "everyone",
      "parent_category": null,
      "product_count": 42,
      "created": "2026-06-28T10:14:05Z",
      "updated": "2026-07-20T08:31:22Z"
    }
  ],
  "meta": { "total": 37, "limit": 20, "offset": 0 }
}
            

Response fields

Field	Description
data[].id integer	Category's unique id.
data[].name / sku / url string	Display name, unique sku, and url slug.
data[].available / visible boolean	Availability and storefront visibility flags.
data[].parent_category object \| null	`{ id, name }`, or `null` for a root category.
data[].product_count integer	Number of products assigned to the category.
meta.total / limit / offset integer	Pagination totals for building page controls.

Status codes

200Success. Body contains data and meta.

400validation_error — an invalid filter value (e.g. bad dir or date format).

401unauthorized — bearer token missing, expired, or revoked.

500server_error — retry with backoff; check the status page if it persists.