> For the complete documentation index, see [llms.txt](https://uxsmart.gitbook.io/velare/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://uxsmart.gitbook.io/velare/buy-and-install/create-required-metafields/metafields/complementary-products.md).

# Complementary products

**Complementary products** are the items you hand-pick to go with the product a shopper is looking at, for example a pouch that matches a bag or a strap that fits it. Vélare reads this metafield and shows those products on the product page as a **Pairs well with** row, so shoppers can add the matching piece without going back to the collection. Unlike related products, the list is chosen by you product by product, not generated from tags or collections.

{% embed url="<https://www.youtube.com/watch?v=zJnndKk6Fwk>" %}

{% hint style="info" %}
This metafield uses the reserved namespace `shopify--discovery--product_recommendation`, which belongs to the **Shopify Search & Discovery** app. It is created by the app, not typed in by hand like the other metafields in this section. Install the app first, then fill in the values on your products.
{% endhint %}

### Before you start <a href="#before-you-start" id="before-you-start"></a>

* You can install apps and edit products in your Shopify admin.
* You know which products belong together. Two to four matches per product is usually enough for the row.

### Step 1: Install the Shopify Search & Discovery app <a href="#step-1-install-the-app" id="step-1-install-the-app"></a>

{% hint style="success" %}
**Steps:**

1. Open the [Shopify Search & Discovery](https://apps.shopify.com/search-and-discovery) app page in the Shopify App Store.
2. Click **Install** and confirm the installation for your store.
3. Go to **Shopify admin > Settings > Custom data > Products** and check that the **Complementary products** definition is listed.
   {% endhint %}

*Result:* the definition below exists in your store, with the values shown in the screenshot.

* Name: **Complementary products**
* Namespace and key: `shopify--discovery--product_recommendation.complementary_products`
* Type: **List - Product**

<figure><img src="/files/tRRefRafkLsnf75OXXbQ" alt=""><figcaption></figcaption></figure>

### Step 2: Pick the complementary products on each product <a href="#step-2-pick-the-products" id="step-2-pick-the-products"></a>

{% hint style="success" %}
**Steps:**

1. Go to **Shopify admin > Products**.
2. Select the product you want to pair items with.
3. Scroll down to the product's **Metafields** area and find **Complementary products**.
4. Click **Select products**.
5. Tick the products that go with this one, then confirm.
6. Drag the rows to set the order shoppers will see.
7. Click **Save**.
8. Repeat for every other product that should show a pairing row.
   {% endhint %}

*Result:* the product stores its own list of matching products. Products you skip keep an empty list.

<figure><img src="/files/1Lrf9Z4vtrlEsZbBfsCx" alt=""><figcaption></figcaption></figure>

### What you should see <a href="#what-you-should-see" id="what-you-should-see"></a>

On the product page, a **Pairs well with** row shows the products you selected, in the order you set, each with its image, title, and price. The row is produced by the **Complementary products** block of the [Product information](/velare/customize-your-pages/product-page/page-template-sections/product-information.md) section, so the block must be present in your product template for the row to appear.

<figure><img src="/files/7zlYM6xNb9FdSoCBb46I" alt=""><figcaption></figcaption></figure>

### If something goes wrong <a href="#if-something-goes-wrong" id="if-something-goes-wrong"></a>

* **The Complementary products field is missing on the product.** The Search & Discovery app is not installed yet, or the installation did not finish. Redo Step 1.
* **The row does not show on the storefront.** The product has no selected products yet, or the **Complementary products** block is not in your product template. Check both.
* **The wrong products show up.** The list is manual, so it shows exactly what is selected on that product. Edit the selection in Step 2.
* **A selected product disappeared from the row.** Products that are unpublished or out of stock may not be shown. Check the status of that product.

### Related pages <a href="#related-pages" id="related-pages"></a>

* [Metafields](/velare/buy-and-install/create-required-metafields/metafields.md): the full list of metafields to create
* [Custom Product Badge](/velare/buy-and-install/create-required-metafields/metafields/custom-product-badge.md): the previous metafield in this section
* [Product information](/velare/customize-your-pages/product-page/page-template-sections/product-information.md): the product page section and its **Complementary products** block
* [Related products](/velare/customize-your-pages/product-page/page-template-sections/related-products.md): automatic recommendations, as opposed to this hand-picked list
* [Top apps](/velare/buy-and-install/apps/top-apps.md): apps recommended for Vélare stores


---

# 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://uxsmart.gitbook.io/velare/buy-and-install/create-required-metafields/metafields/complementary-products.md?ask=<question>&goal=<endgoal>
```

`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.