The Categories API allows you to create and manage a hierarchical tree of categories for organizing items/products in a Wix Stores catalog.
With this API, you can:
- Create, update, and delete categories.
- Build hierarchical structures with parent and subcategories.
- Add and remove items/products from categories.
- Arrange product order within categories for display.
- Retrieve categories by the specific products they contain.
It's important to note the following points before starting to code:
- Wix Stores required: The Categories API requires Wix Stores. Make sure the user's site has the Wix Stores app installed.
- Catalog version: The Categories API currently works exclusively with the Wix Stores Catalog V3.
- Category tree: A hierarchical structure that organizes all of a site's categories into parent and child (subcategory) relationships. Each Wix Stores site has one category tree.
- Tree reference required: All API requests require a
treeReference object. For Wix Stores, always use appNamespace: "@wix/stores" and treeKey: null.
- Item references: When adding items/products to categories, use the Wix Stores app ID (
"215238eb-22a5-4c36-9e7b-e7c08025e04e") and the product ID as the catalogItemId.
Categories have a visible property that controls whether site visitors can see them.
Key visibility behaviors:
- Default: Categories are visible (
visible: true) by default.
- Cascading: Setting a parent category's visibility to
false automatically hides all its subcategories.
- Restriction: You can't make a subcategory visible if any of its parent categories are hidden.
- API access: Hidden categories and their products are still accessible via API calls. To retrive them, pass
includeHiddenCategories: true to Search Categories or Query Categories.
You can arrange up to 100 items/products within a category to control their display order.
When you call List Items In Category:
- With
useCategoryArrangement: false (default): Products are sorted by the date they were added to the category, newest first.
- With
useCategoryArrangement: true: Manually arranged items/products appear first in their specified order, followed by remaining items/products sorted by date added.
Third-party apps can create categories that only they can modify by setting the managingAppId field. When set, only that app can add or remove items/products from the category.
When you delete a category:
- All subcategories are also deleted (cascading delete).
- Items/products remain in the Wix Stores catalog but are no longer associated with the deleted categories.
- Categories per site: 1,000
- Hierarchy depth: 5 levels maximum
- Parent categories: Each category can have only one parent
- Items per category: Unlimited, but each item/product can be in up to 1,000 categories
- Manual arrangement: Limited to 100 items/products per category
- Tree: A hierarchical structure of categories. Each Wix Stores site has one category tree.
- Tree reference: Identifies which category tree to work with. For Wix Stores, use
appNamespace: "@wix/stores" and treeKey: null.
- Top-level (root) category: A category with no parent (
parentCategory.id is empty or null).
- Parent category: The category above another category in the hierarchy. Top-level categories don't have a parent.
- Subcategory: A category that is nested under a parent category.
- Sibling categories: Categories that share the same parent category.
- Category index: The position of a category among its sibling categories within the same parent.
- Breadcrumbs: The path from the top-level category down to the current category's parent. Useful for navigation UI and SEO.
- Item reference: Identifies an item within a category. Includes
appId (the Wix Stores app ID) and catalogItemId (the Wix Stores product ID).
- Managing app: An app that has exclusive control over adding and removing items from a category.