> For the complete documentation index, see [llms.txt](https://staylime.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://staylime.com/docs/avante-themes/features-and-advanced-setup/complementary-products.md).

# Complementary products

Add a hand-picked "Pairs well with" block to Avante product pages using Shopify Search & Discovery — cross-sell related items and lift your average order value.

Show a hand-picked block of related products on your product pages to cross-sell and lift average order value. Unlike automatic recommendations, you choose exactly which products appear — perfect for "complete the look" or "add the matching case".

<figure><img src="https://795663372-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6DraMvJNYYlFJqlho1aV%2Fuploads%2FKKfG5fjahlEYFgR1N7zA%2FGroup%202%20(23).jpg?alt=media&amp;token=02db72fa-46da-4bab-a935-828f50e32845" alt=""><figcaption></figcaption></figure>

***

### How it works

You pick the pairs in Shopify's free **Search & Discovery** app, and Shopify stores them on the product. When a customer opens the product page, Avante asks Shopify's Product Recommendations API for that product's complementary list and renders the block with product image, price, and optional vendor and rating.

This is different from automatic **Product Recommendations** ("You might also like"), which Shopify generates algorithmically. Complementary products are fully controlled by you.

{% hint style="info" %}
**The list is filtered by Shopify, not by Avante.** Because it comes through the Recommendations API, Shopify drops anything a customer can't buy right now — out of stock, draft, unpublished, zero-priced — and returns up to 10 products. So a product you linked can be missing from the block even though the link is still there.
{% endhint %}

{% hint style="warning" icon="lightbulb" %}
**Note:** if you haven't linked any complementary products to a product, Avante hides the block on that product's page — so you never get an empty section.
{% endhint %}

{% hint style="info" %}
The block loads a moment after the rest of the page. In the Theme Editor it can look empty for a second, or stay empty on a preview of a product with no pairs set.
{% endhint %}

***

{% stepper %}
{% step %}

#### Step 1: Install Shopify Search & Discovery

1. Open the [Shopify Search & Discovery app](https://apps.shopify.com/search-and-discovery) in the App Store and install it
2. Confirm it's active in **Shopify Admin → Apps**
   {% endstep %}

{% step %}

#### Step 2: Link complementary products

1. Go to **Shopify Admin → Apps → Search & Discovery → Recommendations**
2. Click **Add recommendations** (top right) and choose the product you're cross-selling from. Products with nothing set yet show "No products" in the Complementary products column

<figure><img src="https://795663372-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6DraMvJNYYlFJqlho1aV%2Fuploads%2F8Su1NDc83jbjL5eCuH7q%2FGroup%202%20(24).jpg?alt=media&amp;token=ab0a624f-3f5b-41e6-83c5-1fb7709d3352" alt=""><figcaption></figcaption></figure>

3. Under **Complementary products**, select the items to pair with it (up to 10)
4. **Save**

<figure><img src="https://795663372-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6DraMvJNYYlFJqlho1aV%2Fuploads%2Fwq17ZEcCnapaKzNrFb7u%2FGroup%202%20(25).jpg?alt=media&amp;token=8a739e07-834c-4b6c-aeaa-2a9431601776" alt=""><figcaption></figcaption></figure>

{% hint style="success" icon="lightbulb" %}
**Tip:** this is the only place to choose complementary products — they're set in the Search & Discovery app, not on the product page in Shopify Admin and not in the theme. The theme block just displays whatever you link here, so keep the app installed.
{% endhint %}
{% endstep %}

{% step %}

#### Step 3: Add the block in the Theme Editor

1. Go to **Online Store → Themes → Edit theme**
2. In the top page selector, open **Products → Default product**
3. Select the **Product overview** section, click **Add block**, and choose **Complementary products**
4. Drag the block where you want it — e.g. right below the buy buttons
5. **Save**

<figure><img src="https://795663372-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6DraMvJNYYlFJqlho1aV%2Fuploads%2FwvuvzaM361o9wnBnxyQm%2FGroup%202%20(26).jpg?alt=media&amp;token=7d76965c-cd12-4a6a-a7ec-28be4d86f679" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Step 4: Style the block

Click the block to open its settings. Most are self-explanatory — heading, heading size, image ratio and focal point, price position, vendor, hover image, color pills, pickup availability. Two have dependencies worth knowing:

* **Heading** — set your text (e.g. "Pairs well with" or "Best fits with"). Wrap a word in {curly brackets} to apply the Secondary heading font from [Theme settings → Typography](/docs/avante-themes/theme-settings/typography.md)
* **Show product rating** — only shows if you have a product-rating app installed
* **Show short description** — pulls from the product's **Subtitle** metafield. [Learn more](/docs/avante-themes/features-and-advanced-setup/product-subtitle.md)
  {% endstep %}
  {% endstepper %}

### Result

The product page shows your hand-picked "Pairs well with" block. If no complementary products are linked, the block stays hidden.

<figure><img src="https://795663372-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6DraMvJNYYlFJqlho1aV%2Fuploads%2F8lFaOWFOJ6EvzQyezjsL%2FGroup%202%20(27).jpg?alt=media&amp;token=6994329d-da9c-4d45-b133-3a5480ef10a7" alt=""><figcaption></figcaption></figure>

***

### Troubleshooting

<details>

<summary><strong>The block doesn't show on the product page</strong></summary>

First, check that complementary products are linked to *that specific product* in Search & Discovery — an empty list makes Avante hide the block. A linked product also won't appear unless it's in stock (quantity above 0), set to **Active**, published to the Online Store, priced above $0, not a gift card, and not already in the customer's cart.

</details>

<details>

<summary><strong>Some of the products I linked are missing</strong></summary>

Shopify returns at most 10 complementary products and filters out anything unavailable at that moment. Restocking or republishing the product brings it back into the block — you don't need to relink it.

</details>

<details>

<summary><strong>What's the difference between Complementary and Recommended products?</strong></summary>

Complementary ("Pairs well with") is manual cross-sell you control. Recommended ("You might also like") is Shopify's automatic, algorithm-driven block.

</details>

***

### Related

* [Filters & search](/docs/avante-themes/features-and-advanced-setup/filters-and-search.md) — also powered by Search & Discovery


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://staylime.com/docs/avante-themes/features-and-advanced-setup/complementary-products.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.