> For the complete documentation index, see [llms.txt](https://docs.roadmap.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roadmap.so/cart-and-checkout/configure-recommended-products-block.md).

# Configure Recommended Products Block

Show product recommendations in the cart or cart drawer, using product metafields and field-by-field styling controls.

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2FQ1BOsdkT3ZDyUMhlIpWt%2FScreenshot%202026-07-03%20at%209.23.52%E2%80%AFAM.png?alt=media&amp;token=8b378cf7-b450-4b0c-8c56-409f0e978b1a" alt=""><figcaption></figcaption></figure>

Use **Recommended Products** when you want to upsell extra items while the shopper reviews their cart.

It shows a product carousel inside the cart surface your store uses.

That can be the cart page or the cart drawer.

### What this feature does

**Recommended Products** shows suggested products based on a product metafield.

You choose how many products can appear, where the recommendations are sourced from, and how the block looks.

Use it when you want to:

* suggest complementary products before checkout
* keep upsells inside the cart flow
* hide the block once a shopper reaches a target cart value

### Where to find it

Go to **Cart & Checkout**.

On the **Cart Features** tab, find **Recommended Products** and select **Configure**.

### Before you configure it

Decide these four things first:

* which product metafield will hold the recommended products
* whether recommendations should use the last added product or all products in the cart
* how many products should show at once
* whether the block should hide once the cart reaches a spend threshold

### Set the recommendation logic

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2FZS7MmkDOLr6iuMXyBiqF%2FScreenshot%202026-07-03%20at%209.19.31%E2%80%AFAM.png?alt=media&amp;token=091af29f-4cff-4bf4-8022-fd6a30693a1c" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

#### Add the product metafield key

Enter the metafield used to pull the recommendations.

Roadmap ships the metafield `roadmap.recommended_products.` but you can link your own.

This metafield must be a **Product Reference** metafield.
{% endstep %}

{% step %}

#### Set the maximum number of products

Use **Max Recommended Products** to cap how many products can appear.

The default is **3**.
{% endstep %}

{% step %}

#### Choose the recommendation source

Use **Recommendation Source** to choose where the block should look for recommendations.

Use the last added product when the newest cart item should drive the upsell.

Use all products in cart when any cart line can contribute recommendations.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
If recommended products do not appear, check the metafield key first.

Then confirm the source products actually have values saved in that metafield.
{% endhint %}

### Hide the block at a threshold

Use **Hide on Threshold** when the upsell should stop once the shopper reaches a target.

This works well when the next goal is already handled elsewhere, such as free shipping or a Gift with Purchase threshold.

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2Fu7bn2MNTaunHNA4EswBo%2FScreenshot%202026-07-03%20at%209.20.09%E2%80%AFAM.png?alt=media&amp;token=d1d20845-84fa-4e59-905e-ef3e80f4145e" alt="" width="375"><figcaption></figcaption></figure>

{% stepper %}
{% step %}

#### Turn on threshold hiding

Enable **Hide block once cart reaches a threshold**.

Leave it off if the recommendation block should always show.
{% endstep %}

{% step %}

#### Choose one threshold mode

Use **For all countries** when one amount should apply everywhere.

Use **Per country** when different markets need different thresholds.
{% endstep %}

{% step %}

#### Enter the threshold values

Add the amount for each country you want to control.

If you use **Per country**, **Rest of World** covers countries without their own entry.

If no threshold is set for a country, the block keeps showing for that country.
{% endstep %}
{% endstepper %}

### Set the content & outer container

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2F2xrA1smor6fHVgnLtvS4%2FScreenshot%202026-07-03%20at%209.20.37%E2%80%AFAM.png?alt=media&amp;token=78145430-c1ed-4ab9-8b4e-25f218db5a99" alt="" width="375"><figcaption></figcaption></figure>

Use the panel to control the heading shown above the carousel.

You can configure:

* title text
* title size
* title colour
* title font weight
* background colour
* border colour
* border style
* border thickness

This is the outer frame around the whole recommendation area.

### Style each product card

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2FGYcrht32MCYG0T1V1SyW%2FScreenshot%202026-07-03%20at%209.21.13%E2%80%AFAM.png?alt=media&amp;token=a480349f-e2c0-49d7-b31b-fa86540bac5f" alt="" width="346"><figcaption></figcaption></figure>

#### Product image

Use **Product Image** to control how the image appears.

You can configure:

* image size
* border radius
* image shape

Larger images push the product info section to the right.

#### Inner section

Use **Inner Section** to style the product card itself.

You can configure:

* background colour
* background radius
* inner border on or off
* border colour
* border thickness
* product title colour, size, and weight
* product price colour, size, and weight

This controls the card that wraps the image, title, price, variant selector, and button.

### Configure the variant selector

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2FMBwRoeuiDd62daoKtp5h%2FScreenshot%202026-07-03%20at%209.53.54%E2%80%AFAM.png?alt=media&amp;token=719df808-31ba-45f7-88eb-8131ff2829b4" alt="" width="346"><figcaption></figcaption></figure>

Use **Variant Selector** when recommended products have selectable variants.

You can configure:

* minimum width
* background colour
* text colour
* border colour
* border radius

Increase the minimum width only when variant names need more room.

### Configure the button & Pagination

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2FOoPwO2FzFaE5WQUXFLA6%2FScreenshot%202026-07-03%20at%209.21.49%E2%80%AFAM.png?alt=media&amp;token=f83a98f1-bdc1-4886-a8e2-144fa2659ff1" alt="" width="353"><figcaption></figcaption></figure>

Use **Button** to style the add-to-cart action inside the product card.

You can configure:

* button text
* button colour
* button text colour
* button border colour
* error button colour
* error button text colour
* text size
* border radius
* font weight
* button location

Use a short label.

`Add to Cart` is the usual choice.

Use **Pagination** when more than one recommendation can appear in the carousel.

You can configure:

* show arrows
* show indicators
* arrow colour
* indicator primary colour
* indicator secondary colour

Turn off arrows or indicators only if the card count is low and the layout stays obvious.

### Adjust spacing

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2FK8Bt1KYVa7L1LlQzgNJg%2FScreenshot%202026-07-03%20at%209.55.21%E2%80%AFAM.png?alt=media&amp;token=a5061b22-1c0f-47e0-90e8-0a6066784d6e" alt=""><figcaption></figcaption></figure>

Use **Spacing** to tune how tightly the block fits inside your cart layout.

You can configure:

* container outer vertical and horizontal spacing
* product card inner vertical and horizontal spacing
* outer margins for top, bottom, left, and right

You can also turn on preview-only spacing indicators while you fine-tune the layout.

These indicators do not show on the live storefront.

### Use the preview simulator

The preview updates as you edit the settings.

Use **Simulate Cart** to test the block at different cart values.

If threshold hiding is enabled, test both below and above the threshold.

If you use country-specific thresholds, switch the country in the simulator and test each market.

Actual appearance may vary based on your store's cart drawer or cart page layout.

### Optional custom CSS

<figure><img src="https://393112916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJ8asLD4FVCFagK40xEr4%2Fuploads%2FwgLrTtZcrOsSDw5DANPa%2FScreenshot%202026-07-03%20at%209.22.02%E2%80%AFAM.png?alt=media&amp;token=e0abf92d-8d9e-4a32-aeb1-df16d73f5e20" alt=""><figcaption></figcaption></figure>

Use **Custom CSS** only when the built-in controls do not cover the design change you need.

This editor targets the widget with `::part(...)` selectors.

Example areas include:

* `heading`
* `product-offer`
* `product-image`

Use custom CSS carefully.

Aggressive overrides can make future styling changes harder to manage.

### Save and test

Select **Save** when you are done.

If the block is not already placed, select **Add to Cart Page** to add it to your theme via the editor.

Then test on the live storefront.

Check these cases before launch:

1. a cart with no qualifying recommendations
2. a cart below the threshold
3. a cart above the threshold

Also test desktop and mobile.

### Troubleshooting

Use these checks in order.

#### The block is empty

Check the metafield key first.

Then confirm the source products have recommended products saved in that metafield.

If you use **All products in cart**, check each eligible cart item.

#### The block shows for some countries but not others

Review the **Per country** threshold setup.

If a country has no specific entry, **Rest of World** applies.

If no threshold applies to that market, the block keeps showing.

#### The block hides sooner than expected

Check whether the cart subtotal is already above the configured threshold.

Then confirm the simulator country matches the threshold entry you want to test.

Retest with a lower simulated cart value.

#### The live layout looks different from the preview

The preview uses sample data.

Your live theme, cart width, product titles, variant names, and custom CSS can all change the final layout.

Retest on both desktop and mobile after saving.

### Best practices

* keep the title short
* start with three products or fewer
* use the last added product when the cart usually centers on one hero item
* use per-country thresholds if your free-shipping goals differ by market
* test long product names and long variant names before going live

### Related guides

* [Configure features](/cart-and-checkout/configure-features.md)
* [Cart Announcement Bar](/cart-and-checkout/cart-announcement-bar.md)
* [Create a Gift with Purchase discount](/discounts-and-gwp/using-gwp-and-discounts/create-a-gwp.md)


---

# 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://docs.roadmap.so/cart-and-checkout/configure-recommended-products-block.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.