Categories · Commerce · REST API — OmniRetailConnect Docs

GET /api/v1/categories

Needs commerce.read. Equivalent MCP tool: list_categories.

Query parameters of GET /categories
Name	Type	Required	Description
`parent`	string	Optional	Category id or slug. Omit it for the top level.
`depth`	integer	Optional	1 to 3, default 2.

curl

export COMMERCE_API_TOKEN='ocm_<token>'

curl -sS "https://<your-shop-domain>/api/v1/categories?depth=3" \
  -H "Authorization: Bearer $COMMERCE_API_TOKEN"

JavaScript

// Server-side code only: never put the token in browser code.
// Top-level await needs an ES module (a .mjs file or "type": "module").
const token = process.env.COMMERCE_API_TOKEN; // ocm_<token>

const response = await fetch('https://<your-shop-domain>/api/v1/categories?depth=3', {
  headers: { Authorization: `Bearer ${token}` },
});

console.log(response.status, await response.json());

PHP

<?php

$token = getenv('COMMERCE_API_TOKEN'); // ocm_<token>

$curl = curl_init('https://<your-shop-domain>/api/v1/categories?depth=3');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer {$token}"],
]);

$body = json_decode(curl_exec($curl), true);

echo curl_getinfo($curl, CURLINFO_RESPONSE_CODE), PHP_EOL;
print_r($body);

Python

import json
import os
import urllib.error
import urllib.request

token = os.environ["COMMERCE_API_TOKEN"]  # ocm_<token>

request = urllib.request.Request(
    "https://<your-shop-domain>/api/v1/categories?depth=3",
    headers={"Authorization": f"Bearer {token}"},
)

try:
    with urllib.request.urlopen(request) as response:
        print(response.status, json.load(response))
except urllib.error.HTTPError as error:
    # Errors are JSON too: {"error": {"code": ..., "message": ...}}
    print(error.code, json.load(error))

Example response · 200

{
    "data": {
        "categories": [
            {
                "id": 12,
                "slug": "gereedschap",
                "name": "Gereedschap",
                "parent_id": null,
                "product_count": 48,
                "children": [
                    {
                        "id": 14,
                        "slug": "handgereedschap",
                        "name": "Handgereedschap",
                        "parent_id": 12,
                        "product_count": 21,
                        "children": []
                    }
                ]
            }
        ],
        "truncated": false
    }
}

Fields of data
Field	Type	Description
`categories`	array	Nodes with `id`, `slug`, `name`, `parent_id`, `product_count` and `children`.
`product_count`	integer	Published products in the category and its subcategories.
`truncated`	boolean	`true` when the tree was cut at 500 nodes.

Use a category id or slug as collection in Search products.

Errors

Errors of GET /categories
Status	error.code	When
`401`	`unauthenticated`	Missing, malformed, unknown, revoked or expired token, or a token without the `api` channel.
`404`	`not_found`	The `parent` category does not exist.
`422`	`invalid_argument`	`depth` outside 1 to 3, or an unknown parameter.
`429`	`too_many_requests`	Rate limit reached. Wait the number of seconds in `Retry-After`.