Category Attributes

You can add customized attributes to static and dynamic categories to further define their characteristics. This is useful for identifying special categories or supporting your catalog/storefront design. 

For example, you could use attributes to identify some categories as best-sellers or seasonal. If you are using categories to represent different locations, you could use attributes to define an address for each category.

Create a Category Attribute

To create a category attribute:

1. Go to System > Schema > Category Attributes.
2. Click Create New Category Attribute.
3. Enter an Attribute Label that has meaning to you.
   Keep in mind that it appears on the storefront if you later specify it to display there.
   1. If you want to give it a different name for administration purposes, edit the Administration Name.
      The default name is the Attribute Label.
   2. If you want to customize the Attribute Code, edit the value accordingly.
      This field automatically populates based on the Attribute Label.
4. Select a Display Group.
   This field determines where the attribute displays: either in the Admin only, or in the Admin and on the storefront.
5. Select an Input Type. Depending on your selection, additional configurations may appear.
   1. If you choose List, select a Data Type and enter the selection options in the Values field.
   2. If you choose Text box, select a Data Type. Optionally, you can define input parameters in the Min char/val and Max char/val fields, or enter a regular expression in the Input validation field.
   3. If you choose Text area, you can optionally define a Max char value.
   4. If you choose Date, you can optionally define a start and/or end date for the selectable range.
   5. If you choose Yes/No, there are no additional configurations.

Apply a Category Attribute

To apply a category attribute:

1. Go to Main > Catalog > Categories.
2. Select the category to which you want to apply the attribute. 
3. In the Category Attributes section, all available attributes will be displayed. Select the value of your choice for any given attribute (or leave it blank if you don't want to use it for this category). This example shows four different attributes available for a category.

Filter on Category Attributes

You can use these attributes as filters when searching categories in the Admin UI or Category APIs.

At Main > Catalog > Categories, use the search bar's Advanced Filter dropdown to search for categories based on attributes. You should select both an Attribute Name and Attribute Value. The allowed input type (such as true/false or a string) will depend on the selected attribute and an error message will be displayed if you enter an invalid value.

To filter the Category API, you must use a dedicated endpoint that wraps around the Get Categories call. Attempts to apply an attribute filter to the basic Get Categories call will be ignored. You can either apply the prefix tenant~ to the attribute or leave it off and the system will automatically add it for you. This will return the same response as Get Categories, but only include categories with that attribute value.

Note that the syntax for this endpoint requires you to specify the attribute name and value at the same time. This means that your query will include three fields joined by equals (=) signs: the attribute's fully qualified name (or attribute code),  the value, and the attribute type (string, number, datetime, bool, or productCode). See the following example, querying for a "seasonal" attribute:

GET .../commerce/catalog/admin/categories/searchCategoryAttributes?filter=tenant~attribute eq seasonal=true=bool

GET .../commerce/catalog/admin/categories/searchCategoryAttributes?filter=attribute eq seasonal=true=bool