Integrations / Platforms / Shopify / Visual Merchandising Tool

Visual Merchandising Tool

The Merchandising tool is part of our Algolia for Shopify plugin. It helps shop owners actively promote (or demote) items for specific search queries.


In order to access the Merchandising tool, your Algolia plan needs to have access to Rules. To see if this is the case, consult our pricing page.


The Merchandising tool lets you promote or demote your products on a given search. You can influence results and boost certain products in specific search contexts:

  • Promote high performing products for popular searches,
  • Add related products to searches with no results.

The Merchandising tool is a wrapper around Algolia’s Query rules. Query rules allow you to assign action to specific search queries. For example - If my customer types “dress”, then promote item “Red satin dress”.

How can I influence search results?

For a given search query, the Merchandising tool lets you:

  • Pin a product - Assign an absolute position to a product
  • Hide a product - Remove the product from the search results
  • Promote a product - Move the product higher in the search results
  • Demote a product - Move the product lower in the search results
  • Add a product - Using the search bar, add a product that is not available in the first page of the results otherwise. The item will be assigned to the first available (not pinned) position.

How does it work?

The Merchandising tool uses query rules. When you modify a query’s search results using the Merchandising tool, an Algolia query rule is automatically created for you. You can assign multiple actions to a query rule: for one given query, you can promote, demote, pin, and hide as many objects as you want. However, each query (along with all its associated actions) is stored as one Rule.

You can view the query rules that you created in the Algolia dashboard. Every query rule created through the Merchandising tool can be identified on the Algolia dashboard by its objectID: “shopify-merchandising-my-query”.

Changes made through the Merchandising tool will be sent to Algolia, but not the other way around. If you create a rule in the Algolia dashboard, it won’t be sent to the Merchandising tool.

When you create a rule through the Merchandising tool, don’t delete it through the Algolia dashboard: doing this can cause inconsistencies.

Please note that the merchandising tool only supports the first page of search results. As such, the number of results shown within the tool is the same as Number of Products shown within the InstantSearch settings in the Search Options tab of the application.

How to create a query rule?

1. Go to the Merchandising tool tab and click on Create your first query rule.

The Merchandising Tool in the Shopify admin

2. Type the search query you want to assign actions to, and click search. The results for the search are displayed, and you can directly modify the order of the results.

Merchandising a query in the Shopify admin

How to promote or demote products?

1. Use the arrow buttons to adjust the desired position of a product, up or down.

Promoting or demoting items with the arrow buttons

How to pin a product that is outside search results?

In the example above, for the search query “watch” we get video games, but suppose we want to promote a wrist watch instead.

The default results on a search query

1. Click on “Add another product to pin” and search for the item you want to promote.

Search for the product you want to pin to this query

2. The items will then be pinned to the first available (not pinned) position. Previously pinned items won’t be impacted.

Your item is now pinned to the results

How to hide a product from search results?

To hide a product from your search results, click the Hide button on a selected item. The item won’t appear in your search results and will be listed at the bottom of the page under the Items hidden from search results section. If you want to return a hidden product to your search result, select it and click Add to results. The item will be restored to either its initial position, if no other product has been pinned to it, or to the next available position.

How to make pinned items filterable?

By default, pinned items show up in the search results even if they don’t match applied filters. You can disable this behavior by checking Pinned items must match active filters to be displayed in the Merchandising settings section of the Merchandising tool tab.

For example, if you’ve pinned a red item that is on sale, but the user filters on blue items, this setting ensures that only blue items appear (discarding your pinned red item).

Pinned items and filtering

Widget changes

We’ve updated our InstantSearch widget to support this new feature for merchandised collections.

You can find the latest version in algolia_instant_search.js.liquid.

@@ -177,17 +177,11 @@
     // targeting collection pages
     if (collectionPage) {
       // Collection page merchandising:
-      // send rulesContext for promoted results only if no filters active
-      if (
-        !hasRefinements(searchFunctionHelper, instant.facets.list) &&
-        Number(page) === 0
-      ) {
         // If we are on a collection page, `collectionRulesContextValue` is defined
         if (collectionRulesContextValue) {
           searchFunctionHelper.setQueryParameter('ruleContexts', [
       } else {
          searchFunctionHelper.setQueryParameter('ruleContexts', []);

Merchandising a collection from the Algolia dashboard visual editor

You can also merchandise your collections from the visual editor in the Algolia dashboard. To merchandise a collection from the Algolia dashboard, you need to:

1. Create a new rule with the visual editor.

2. Set the collection context.

3. Filter the results on that particular collection.

4. Pin and/or hide your products.

The collection search page feature must be enabled to merchandise collections.

Create a new rule from the visual editor

In the Rules section from the left sidebar menu in the Algolia dashboard, select your products index. To create a rule, select either Create your first rule or New rule. In the dropdown, click on the Visual Editor option.

Create a rule from the visual editor

Set the collection context

In the visual editor, click on Set a search query. In the dropdown next to Your search, select is and leave the following input field empty. Finally, enter the collection handle in the input field beneath Add a context (optional). To trigger a Rule when a customer lands on a collection page, the search query must be empty and the context must equal your collection handle.

Set the search context

The collection handle is the last part of your collection page’s URL. You can also find it when editing your collection’s “website SEO” in your Shopify admin interface. For example, if the URL of my collection “Bright Shirts” is “”, then its handle is bright-shirts.

Filter the results on that particular collection

You should now see all the products of your store being displayed. To keep only the ones belonging to your collection, click on Filter results under What do you want to do?. In the Category section you can either choose to filter on the collection_ids attribute or on the collections attribute.

  • collection_ids is an attribute found on each product-it is an array of the collection IDs the product belongs to
  • collections is an attribute found on each product-it is an array of the collection handles the product belongs to

We recommend filtering on collection_ids because it is not subject to change.

Filter the search results on that particular collection

The collection_id can be found in the URL when editing your collection from the Shopify admin interface. For example, if the URL of the collection edition page is “”, then is ID is 187530641539.

Pin and/or hide your products

Move the items at the position you want them to appear in the collection page and hide the ones you don’t want to show. Click on Review and Publish once you are done.

Promote and hide the items the way you want them to appear

In summary, you can use the Visual (and Manual) editors in the Algolia dashboard to create new Rules. For additional examples please refer to our Rules Overview. If you want to use the Algolia dashboard to merchandise a collection, the Rule Condition must be an empty query and the context must be the collection handle.

Did you find this page helpful?