Skip to main content
Categories can be nested into a tree: a category may have a parent and any number of children. This guide covers creating child categories, listing the top level, and walking the tree.
Hierarchy is a category-only feature. Collections have no parent/child relationship — their responses carry no parent_id, has_children, or position, and their write bodies accept no parent_id. Everything in this guide applies to categories only.

​
The fields that model the tree

Three fields on a category describe its place in the tree:
​
integer | null
The id of the parent category, or null when the category is at the root (top level).
​
boolean
true when the category has at least one child. Use it to decide whether to fetch a level deeper.
​
integer
The category’s order among its siblings. The default sort (position then id) uses it.

​
Create a child category

To nest a category under another, set parent_id to the parent’s id when you create it. Leaving parent_id out (or null) creates a top-level category.
You can also move an existing category by patching its parent_id. Set it to another id to re-parent, or to null to promote it to the top level:
Use position to order siblings within a level.

​
List top-level categories

The public catalog’s filter[parent_id] selects a single level of the tree. Pass the literal string "root" to get only top-level categories:

​
List the children of a category

Pass a category id (as a string) to filter[parent_id] to get that category’s direct children:
Each returned child carries its own has_children, so you know whether it has a further level beneath it.

​
Traverse the tree

Combine filter[parent_id] with has_children to walk down the tree one level at a time:
1

Start at the root

Fetch the top level with filter[parent_id]=root.
2

Descend into categories that have children

For each returned category where has_children is true, fetch its children with filter[parent_id]=<id>.
3

Repeat until has_children is false

Keep descending into any child whose has_children is true. A category with has_children: false is a leaf.
To walk up the tree instead, read a category’s parent_id and fetch that parent by id with the company show endpoint GET /api/v202604/company/categories/{id}. The public show endpoint resolves by slug rather than id, so on the public surface you locate the parent among catalog results (each row carries both id and slug) and then fetch it with GET /api/v202604/categories/{slug}.
filter[parent_id] is accepted on both the public catalog and the company index (GET /api/v202604/company/categories) — the two surfaces share one query contract. They differ only in scope: the public catalog returns only live categories, while the company index returns every lifecycle state (draft, scheduled, and archived included). So to build the full tree as an admin you can either filter the company index by filter[parent_id], or page through it unfiltered and group the rows client-side by their parent_id field, which is present on every row.

​
Next steps