Integrations / Shopify

Visual merchandising tool

From December 31, 2023, Algolia’s Search and Discovery application can’t modify the coding of Shopify themes. For more information, refer to Shopify’s Asset API documentation. As an alternative, Algolia offers Shopify’s App Embed and App Blocks features for Autocomplete and InstantSearch interfaces. For more information, refer to the Quick start and Shopify Algolia configuration documentation.

The Merchandising tool helps shop owners actively promote (or demote) items for specific search queries or collections. With the Merchandising tool, 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 uses Algolia’s Rules. Rules are if-then statements that let you to assign actions to specific triggers. For example, if a user types “dress”, then promote the item “Red satin dress”.

How you can 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 wouldn’t be on the first page of the results otherwise. The item is assigned to the first available (not pinned) position.

How the Merchandising tool works

When you modify a search query’s results, the Merchandising tool creates a new Rule. You can assign multiple actions to a Rule: you can promote, demote, pin, and hide as many objects as you want. However, each query and its associated actions is stored as a single Rule.

View the rules in the Algolia dashboard. Rules created with the Merchandising tool have the prefix shopify-merchandising-<query>.

Changes made through the Merchandising tool are 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.

If you created a Rule in the Merchandising tool, don’t delete it in the Algolia dashboard.

The Merchandising tool only supports the first page of search results. The number of results shown in the Merchandising tool is the same as the Number of Products shown in the InstantSearch settings in the Search Options of the application.

How to create a new Rule

  1. Open the Merchandising tool tab and click Create your first query rule.

    The Merchandising tool in the Shopify admin

  2. Type a search query you want to assign actions to, and click Search. You can change the order of the results.

    Merchandising a search query in the Shopify admin

How to promote or demote products

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 following example, the search query “watch” returns video games.

The default results on a search query

To show wrist watches instead:

  1. Click 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 are pinned to the first available (not pinned) position. Other pinned items aren’t 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, select an item and click Hide. The item won’t appear in your search results and is listed at the bottom of the page under Items hidden from search results. 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 change this behavior by selecting Pinned items must match active filters to be displayed in the Merchandising tool > Merchandising settings section.

For example, if you pinned a red item that is on sale, but users filter on blue items, this setting ensures that only blue items appear (discarding your pinned red item).

Pinned items and filtering

Widget updates

The InstantSearch widget was updated 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 in the Algolia dashboard (Visual Editor)

You can also merchandise your collections with the Visual Editor in the Algolia dashboard.

You need to perform these steps:

  1. Create a new rule with the visual editor.
  2. Set the collection context.
  3. Filter the results on that particular collection.
  4. Pin or hide your products.

You need to enable the collection search page feature to merchandise collections.

Create a new Rule with the Visual Editor

  1. Go to the Rules section in the Algolia dashboard and select your index to which you want to add a Rule.
  2. Select either Create your first Rule or New Rule and select Visual Editor.

    Create a rule from the visual editor

Set the collection context

  1. In the Visual Editor, click Set a search query.
  2. In the menu next to Your search, select is and leave the following input field empty.
  3. In Add a context (optional), add a collection handle. To trigger a Rule when a user lands on a collection page, the search query must be empty and the context must be equal to 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 the Algolia Search and Discovery app’s settings. For example, if the URL of the collection “Bright Shirts” is, then its collection handle is bright-shirts.

Filter the results on a particular collection

To display only the products of a particular collection, click Filter results in the What do you want to do? section. In the Category section, you can either choose to filter on:

  • collection_ids—an array of the collection IDs the product belongs to
  • collections—an array of the collection handles the product belongs to

Filtering on the collection_ids attribute is more robust, as changes to the collection ID are less likely.

Filter the search results on that particular collection

You can find the collection_id in the URL, when editing your collection in Shopify. For example, if the URL of the collection edition page is, then is ID is 187530641539.

Pin 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. Save your selection by clicking Review and Publish.

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

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?