Skip to main content
This is a beta feature according to Algolia’s Terms of Service (“Beta Services”).
Autocomplete, InstantSearch, and Recommend in the Algolia app blocks now support version 5 of the Algolia API client. Most stores only need to switch the search client version setting to Version 5. If you use custom storefront JavaScript, follow the version 5 upgrade guide. Support for version 4 ends on August 14, 2026.
A composition is a saved search configuration that you author in Merchandising Studio. It runs on your products index and can add smart groups to search results. Smart groups are curated or rule-driven sets of products that Algolia merges into results at query time. If a product no longer meets a smart group’s criteria, for example because it’s out of stock, Algolia can replace it with another matching product. When you connect a composition, InstantSearch uses it for search results and collection pages. Autocomplete uses it only for product results. Changes you make in Merchandising Studio apply on the next query.

​
Before you begin

  • Your Algolia app is on the Elevate plan and runs on dynamic scaling infrastructure.
  • The Search client version setting is Version 5. For more information, see Search client version. While a composition is connected, you can’t switch to another search client version.
  • Your store doesn’t use B2B. Compositions aren’t compatible with B2B storefronts.

​
Connect a composition

The Composition section has one row for your primary products index and one for each market and language with its own products index. Each row connects to its own composition.
  1. In the Algolia AI Search & Discovery app, go to the Search options tab. In the Search basics section, find the Composition section.
  2. On the row you want to connect, select Connect composition.
What happens next depends on whether any compositions already use that products index:
The app creates a composition from your current store settings and connects it.
The app saves the connection right away. A new composition shows Creating while Algolia sets it up, which can take a minute. When it’s ready, select Edit in Studio to open it in Merchandising Studio. If the composition no longer exists, or your plan doesn’t include compositions, the app shows an error and doesn’t connect it. If creation fails, the row shows Create failed. Select Retry create to try again, or Cancel to clear the row. If creation fails with a quota error, delete unused compositions or indices, then try again.

​
Sync sort orders

The app syncs your search and collection sort orders, including those based on standard and virtual replicas, to the composition’s sorting strategies. A sync runs when you connect a composition and each time you change sort orders. To sync manually, select Sync on the row. Each sync replaces all sorting strategies on the composition with your store’s sort orders. This overwrites any changes you make to sorting strategies in Merchandising Studio, so manage sort orders in the Shopify app. Syncing doesn’t change the composition’s rules or smart groups. If a sync fails, the app retries automatically. If it still fails, the row shows Sync failed. Select Retry sync to try again.

​
Disconnect a composition

To disconnect a row, select Disconnect on that row. After you create a composition from the app, Disconnect stays unavailable for 2 minutes. Disconnecting doesn’t delete the composition in Algolia. The affected storefront returns to standard search.

​
What to expect on your storefront

  • Where compositions apply. InstantSearch uses the composition on search results pages and collection pages. In Autocomplete, only product results use it. Collections, pages, articles, and query suggestions in Autocomplete stay on standard search.
  • Recommend. The Recommend app block doesn’t use compositions.
  • Markets and languages. Each storefront searches the composition connected to its products index. A market and language without its own products index searches the primary index, so it uses the primary composition. A market and language with its own products index but no composition uses standard search.
  • Analytics. Click and conversion events carry the name of the products index and the query ID, not the composition ID.
  • Fallback. If you delete the composition, or your plan no longer includes compositions, the storefront falls back to standard search. InstantSearch reloads and stays on standard search for 15 minutes. Autocomplete recovers without a reload. The app doesn’t notify you, so check your compositions if search results change.

​
Compositions or the Merchandising tool

Use the Merchandising tool to pin or hide products from the Shopify app. Use a composition to show products that match a condition, even when individual products change. You can’t use both at once. While at least one composition is connected, the app hides the Merchandising tool, including collection merchandising. To pin or promote products, use Merchandising Studio instead. The app doesn’t delete your existing Merchandising tool rules. If you disconnect every composition, the Merchandising tool comes back.

​
Limitations

  • Disjunctive facets. Composition API requests support up to 20 disjunctive facets. If a request includes more than 20, it fails. On your storefront, if users select more than 20 filters, the page refreshes without applying the new filter. Standard search doesn’t have this limit.
  • Removed parameters. Search requests to a composition can’t include distinct, facetingAfterDistinct, highlightPreTag, or highlightPostTag. The app removes them from requests, including ones that your InstantSearch or Autocomplete hooks add. Without distinct, stores that show products instead of variants show each variant as a separate result. If you rely on distinct, don’t use compositions.
  • Facet value search. To search within facet values, configure the attribute as searchable in the index’s attributesForFaceting.
  • Quotas. Each Algolia app can have a limited number of compositions. For more information, see Smart Groups and Composition API limits.

​
See also

Last modified on November 5, 2026