About the Wix Categories API

The Wix Categories API allows you to create and manage a tree of categories on your site.

This API provides essentials tools to establish hierarchical relationships between categories, helping you organize and classify items assigned to these categories.

With the Wix Categories API, you can:

• Manage categories and assign them to parent categories.
• Add and remove items from categories.
• Specify the manual arrangement of items within a category.
• Retrieve information about items assigned to a category, directly or indirectly.

Before you begin

It’s important to note the following points before starting to code:

• The Categories app is currently only available as part of the Wix stores app. Make sure to install the Wix Stores app from the Wix App Market.
• Your app has the necessary permissions to access the Categories API.

Limitations

Wix Categories is currently limited to:

1. 1,000 Categories per Tree.
2. Up to 5 hierarchies levels.
3. Each category can belong to only one parent category.
4. Items can be associated with many categories, up to 1,000.
5. Only the first 100 items within a category can be arranged manually.
6. Updating visible field to false and delete behaviors apply from parent categories to subcategories.

Sample flows

• Create category and subcategory
• Add and arrange items in category
• Move subcategory to a different position within a parent category
• Find all subcategories of a category

Terminology

1. Tree: A hierarchical structure of categories. Each tree can have up to 1,000 categories.
2. Tree Reference: A unique identifier for the tree. Defined by app namespace and optionally tree key. Must be provided in all API requests.
3. App Namespace: A unique identifier for the app that owns the tree. This namespace must be defined in dev-center before using the API.
4. Tree Key: An optional key to differentiate between multiple trees managed by the same app. It can be empty, if an app only manages one tree.
5. Parent Category: Each category can have a single parent category for managing a nested hierarchy. The parent Category can be empty when category is at the top level of the hierarchy or for flat category structures.
6. SubCategory: A category nested under another category. Multiple subcategories can exist under a single parent category.
7. Depth: The maximum nesting level allowed within the tree, limited to 5 levels.
8. Breadcrumbs: A path from top-level category to the current category, helping users understand their location within the hierarchy and navigate back to parent categories.
9. Item Reference: Identifies an item assigned to a category, consisting of an appId and a catalogItemId.
10. Manual Arrangement: Allows merchants to manually set the order of items within a category. Up to 100 items can be rearranged to make them displayed in the beginning, while the rest are displayed in the order they were added to the category.