> ## Documentation Index > Fetch the complete documentation index at: https://www.algolia.com/llms.txt > Use this file to discover all available pages before exploring further. # Use compositions with the Shopify app > Connect a composition to your Shopify store to add smart groups to search results and manage sorting in Merchandising Studio. This is a **beta feature** according to [Algolia's Terms of Service ("Beta Services")](https://www.algolia.com/policies/terms/). > [!NOTE] > > 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](https://www.algolia.com/doc/integration/shopify/getting-started/configuration.md#search-client-version) to **Version 5**. > If you use custom storefront JavaScript, follow the [version 5 upgrade guide](https://www.algolia.com/doc/libraries/sdk/upgrade/javascript.md). > Support for version 4 ends on August 14, 2026. A [composition](https://www.algolia.com/doc/guides/compositions) 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](https://www.algolia.com/pricing) and runs on [dynamic scaling infrastructure](https://www.algolia.com/doc/guides/scaling/infrastructure/dynamic/dynamic.md). * The **Search client version** setting is **Version 5**. For more information, see [Search client version](https://www.algolia.com/doc/integration/shopify/getting-started/configuration.md#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: > [tab] No existing compositions > > The app creates a composition from your current store settings and connects it. > [tab] Existing compositions > > The app lists the compositions that use that products index. Choose one option: > > * **Create a new composition**, then select **Create and connect**. > * Pick an existing composition, then select **Connect and sync**. > Syncing overwrites the sorting strategies of the composition with your store settings. > Rules and smart groups stay. 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](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/replicas.md), to the composition's [sorting strategies](https://www.algolia.com/doc/guides/compositions/sorting-strategy.md). 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](https://www.algolia.com/doc/integration/shopify/building-search-ui/recommend.md) 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](https://www.algolia.com/doc/integration/shopify/going-further/merchandising-tool.md) 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](https://www.algolia.com/doc/guides/compositions/smart-groups/search-based-groups.md#facets-including-disjunctive-faceting). 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](https://www.algolia.com/doc/integration/shopify/building-search-ui/instantsearch-hooks.md) or [Autocomplete](https://www.algolia.com/doc/integration/shopify/building-search-ui/autocomplete-hooks.md) hooks add. Without `distinct`, stores that [show products instead of variants](https://www.algolia.com/doc/integration/shopify/sending-and-managing-data/schemas.md#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`](https://www.algolia.com/doc/api-reference/api-parameters/attributesForFaceting). * **Quotas.** Each Algolia app can have a limited number of compositions. For more information, see [Smart Groups and Composition API limits](https://www.algolia.com/doc/guides/scaling/algolia-service-limits.md#smart-groups-and-composition-api). ## See also * [Smart groups](https://www.algolia.com/doc/guides/compositions/smart-groups/smart-groups)