Categories

Product version: 1.0.0+1 Last updated: 2026-08-03 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 parent does not cascade-delete children (children may be re-parented / become roots per backend rules).

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