> 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
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".
***
### How it works
Complementary products live in Shopify's native `complementary-products` metafield. You use the free **Search & Discovery** app to choose which products to pair — but the block itself reads straight from the metafield, so once links are set, Avante keeps showing them even if the app is later removed. Avante renders the block on the product page 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="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 %}
***
{% 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
3. Under **Complementary products**, select the items to pair with it (up to 10)
4. **Save**
{% 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.
{% 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**
{% 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.
***
### Troubleshooting
The block doesn't show on the product page
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.
What's the difference between Complementary and Recommended products?
Complementary ("Pairs well with") is manual cross-sell you control. Recommended ("You might also like") is Shopify's automatic, algorithm-driven block.
***
### 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://staylime.com/docs/avante-themes/features-and-advanced-setup/complementary-products.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.