Configure Catalog-Level Search Refinement Definitions

Search refinement definitions determine the selections shown in the storefront search refinement list.

Search refinement definitions enable you to configure one or more attributes (including variation attributes such as Color) to be used as refinement options in the storefront. This bucketing feature enables you to optionally define any number of buckets per refinement definition to group the actual refinement values.

To configure catalog-level search refinement definitions:

  1. Select site > Merchant Tools > Products and Catalogs > Catalogs > catalog . Click the Edit link for the category (in this example, Communication).
  2. On the Search Refinement Definitions tab for a category, you see the list of search refinements defined for the catalog:
  3. Click New to define a new search refinement for the catalog.
  4. Specify the name of the search refinement as it appears in the storefront list (for example, Brand).
  5. Specify the refinement type:
    • Attribute refinement indicates that the refinement is based on a specific product attribute (for example, Brand appears as a list of brands).

      For the Attribute ID, click the ellipsis box to show the list of product attributes from which to choose. (Custom object attributes are not included here and can't be used for refining searches.)

    • Category refinement indicates that the refinement is at the category level and includes all subcategories (this shows a list of the subcategories).
    • Price refinement indicates that the refinement is at the price level (for example, you might have price refinements buckets defined as $0 - $50, $50 - $100, and $100 - $200.
    • Promotion refinement indicates that the refinement is based on specific promotions (for example, you might have a promotion going on that has certain products 25% off).
  6. Specify the sorting mode, how search refinement will be sorted in the storefront list:
    • By Value Name (alphabetically)
    • By Value Count (number of values found for that attribute)
    • By Category Position (For category refinements only). This is the refinements' explicitly defined position within the parent category.)
  7. Specify the sorting direction, whether the search refinements should be listed in ascending or descending order.
  8. Click Apply.
  9. If your developer has customized the template to enable setting the cutoff threshold, you can now enter the Cutoff Threshold, if applicable. This is the number of refinement categories that should be listed before the rest are scrollable in the list box.

    The cutoff threshold depends on the type of refinement. For example, for price refinements there is no cutoff threshold, because you are bucketing all search results into custom-defined price buckets.

Important: Before you can see the new search refinement options in the storefront, you need to rebuild your search indexes (via the Search > Search Indexes module).

The new catalog refinement appears in the storefront when a category with that attribute is selected, for example, Video.

Search refinement buckets let you manage the value buckets (grouped attributes) to be used when refining searches by this attribute. The bucket display name is used as a refinement option whenever the actual product value matches one of the values that are pre-defined here as a comma-separated list.

Merchandisers can define buckets of refinement values and provide a label for each bucket, which is eventually presented when drilling down on that attribute.

For example, consider the following product search result and the corresponding refinement values if Color is defined as a refinement attribute:

Product Color Color
P1 Light Red + Light Red (1)
P2 Lipstick Red + Lipstick Red (1)
P3 Dark Red + Dark Red (1)
P4 Dark Blue + Dark Blue
P5 Navy Blue + Navy Blue

The number of product options can easily become overwhelming for a user. Customers typically search for basic colors, such as red, green, or blue. The merchandiser should limit the refinement options to more general values (that is, the main colors). With this definition in place, the color drill-down links for the same product search result reads as follows:

Bucket Values Color
Red Light Red, Lipstick Red, Dark Red + Red (3)
Blue Dark Blue, Navy Blue + Blue (2)

Testing Tips

If you use bucketing and the value list changes, or you have updated the catalog, remember to rebuild the index, and view the buckets to ensure that all changes have been made correctly. Repeat this after every catalog update.


If you want to use localized bucket labels, supply a localized label for the bucket values for attribute refinements.

  1. Define the refinement.
    Field Value
    Name Color
    Refinement Type Attribute Refinement
    Attribute ID A00373
    Sorting Mode Sort By Value Count
    Sorting Direction Ascending
    Cutoff Threshold 5
  2. Define the bucket values:

    Bucketed Values Bucket Display
    Red Fire Engine Red
    Blue Sky Blue

Then make sure to rebuild the product index. When a customer searches on Fire Engine Red, the bucket values appear:

If the attribute used for the refinement is defined as localizable, the values provided in the bucket value list are as well. For localized refinement attributes, one value list must be supported per active locale (for example, Red = Dark Red and Rot = Dunkelrot). If the attribute used for refinement is non-localized, only one bucket value list is necessary.

Category Refinement Sorting Modes Example

The following example shows the results of the three sorting modes using category refinement.

Assume that the storefront catalog, with sorted subcategories is as follows:

Women's Apparel
Men's Apparel
Children's Apparel

The customer searches for shoes.

If the category refinement is... Then the sorted order is... The hit count is...
Sorted by Value Name (alphabetical) Children's apparel (56)
Men's apparel (12)
Women's apparel (235)
Sorted by Value Count Women's apparel (235)
Children's apparel (56)
Men's apparel (12)
Sorted by Category Position Same as the Storefront Catalog positions Women's apparel (235)
Men's apparel (12)
Children's apparel (56)

Price Refinements

Bucket definitions for price refinements capture the following information:

The localized bucket label can be used to render the price range independently of the actual numerical bounds (for example, Inexpensive as the label for price bucket <= $10).

Promotion Refinements

Note: Promotion Refinements are available only by Merchant Request now.

This promotion refinement type is managed as part of the configuration of a category. Promotion refinements do not have explicitly managed buckets or values like price refinements do, and instead have values which are active at query time in the storefront.

At query time, when the promotion refinement values are returned, the values consist of all promotion IDs which are:

Note: Promotion Refinements are limited to displaying 30 promotions within the refinement filter.
X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.