Categories

Product version: 1.0.0+1 Last updated: 2026-10-02 Audience: Tenant users with product:category:read (mutations use product:category:*)

A. What Are Categories?

A Category is a classification node that groups products by type, department, or function. Categories form a hierarchical tree — a category can have a parent category and multiple child categories.

Examples:

Electronics
├── Computers
│   ├── Laptops
│   └── Desktops
├── Smartphones
└── Accessories
    ├── Cables
    └── Chargers

Categories help customers and staff browse the catalog by department. They also enable variation scoping — variations can be associated with a category so they only apply to products within it.

Note: A product can belong to multiple categories via the product_categories many-to-many association. One category can be marked as the primary category.

B. Viewing the Category List

1. Go to Product Catalog > Categories from the side navigation rail.
2. The category list shows all top-level categories (those without a parent). Pagination defaults to 50 per page.
3. Each row displays:

Tip: Use the Parent filter to view only sub-categories of a specific parent, or unset it to see only top-level categories.

C. Creating a Category

Required permission: product:category:create

1. Go to Product Catalog > Categories.
2. Click Add Category (the "+" button).
3. Fill in the form fields:

4. Click Save.

Important: A slug must be unique across all categories in your tenant. If the auto-generated slug conflicts, you will be prompted to enter a unique one manually.

D. Editing a Category

Required permission: product:category:update

1. From the category list, open a category (row / Edit) to open the category form.
2. Modify the fields. Note the following constraints:

4. Click Save.

Warning: Changing a category's parent can reorganize the entire tree. Products assigned to the category move with it.

E. Category Form (create / edit)

Opening a category from the list (or Add Category) opens the category form. There is no separate category “detail” page with embedded child/product/variation tables in the current app.

The form covers name, description, slug, parent, sort order, and active status (as exposed by the UI).

F. Category Hierarchy (Parent/Child Relationships)

Categories form a tree structure via parent references.

Hierarchy rules

• A category with no parent is a root (top-level) category.
• A category with a parent is a child of that category.
• Circular references are prevented at the application level.
• Deleting a category also deletes all of its subcategories, and the products in those categories appear under Recently deleted on the Products list (restore them individually). Categories themselves cannot be restored from the app.

Browsing the hierarchy

1. Use the categories list (and any tree/indent presentation on larger screens).
2. Open a category form to change its Parent.
3. Use the API hierarchy endpoint / list filters as available for deeper trees.

G. Products in a Category

Products are linked to categories (including an optional primary category). Assignment is done from the product form / setup wizard (and related category-link APIs).

Assigning a product to a category

1. Create or edit a product.
2. Select a category (and primary when the UI offers it).
3. Save.

Viewing products in a category

1. Open Product Catalog > Products.
2. Filter by Category.
3. Open a product to change its category links on the product form.

H. Category Variations

Variations can be scoped to a category. When a variation has a category set, it is intended for products in that classification.

See Variations for creating and managing category-scoped variations. From some product flows you may also open category-scoped variation lists.

Tip: Category-scoped variations keep dimensions relevant (e.g., "Screen Size" under Electronics, not Clothing).

Previous: Brands Next: Variations

Related: Overview · Products · Items · Variation Options

See also: Tenant Owner Manual · Employee Manual