# Use your theme's product card for Releva recommendations

> Let Releva pick the products and your Shopify theme render them, by pointing a Releva Product Block at a Liquid section of your own.

By default the **Releva Product Block** app block renders recommendations with Releva’s template. If you want the cards to look exactly like the rest of your theme, you can hand the rendering to a Shopify section you write. Releva picks **which** products to show; your Liquid decides **how** they look, with tags, prices, metafields and third-party snippets available because Shopify renders the HTML server-side.

## Before you start

* The Releva app is installed and the **Releva.ai** app embed is on: [Connect your Shopify store](https://releva.ai/documentation/integrations/shopify/connect-your-shopify-store/).
* You can edit the theme code of your store (**Online Store › Themes › … › Edit code**).
* You have a product block in Releva for the page you are working on, and its **Product Block Token**. Shopify shops show the token under each block on **Personalization › Product Blocks**, with a **Copy token** icon. See [Create a product block](https://releva.ai/documentation/guides/product-blocks/create-a-product-block/).

## How it works

1. The **Releva Product Block** app block renders an empty placeholder with your token and, when custom rendering is on, the id of your section.
2. On each page view the Releva app embed asks Releva for recommendations, extracts the product handles from the response and writes them, comma-separated, into a cart attribute named `_rlv_h_<section id>` through `/cart/update.js`. The attribute is written even when the list is empty, so a stale list never leaks from a previous page.
3. It then requests your section through Shopify’s Section Rendering API (`/?sections=<section id>`, with the visitor’s locale prefix) and injects the returned HTML into the placeholder. Scripts inside your section are executed again after injection.
4. Links in your section that point at `/products/` get Releva’s click-tracking parameters (`rlv_rid`, `rlv_rpid`, `rlv_rpos`) added, and a `releva:recommendations` event is dispatched on `window` with the recommender in `detail.recommenders`.

## Steps

### 1. Create a section file

1. In your Shopify admin, go to **Online Store › Themes**, select **…** › **Edit code** on the theme.
2. In the **Sections** folder, select **Add a new file** and name it, for example, `releva-recs.liquid`.
3. Paste the minimal section below or one of the [examples](https://releva.ai/documentation/integrations/shopify/use-your-themes-product-card/#section-examples), replace `YOUR-SECTION-ID-HERE` with the file name without `.liquid` (here `releva-recs`), and select **Save**.

```plaintext
{% assign rlv_handles = cart.attributes['_rlv_h_YOUR-SECTION-ID-HERE'] | default: '' | split: ',' %}


{% for handle in rlv_handles %}
  {% assign product = all_products[handle] %}
  {% if product.title != blank %}
    <!-- Your product card markup goes here -->
    <a href="{{ product.url }}">{{ product.title }} — {{ product.price | money }}</a>
  {% endif %}
{% endfor %}


{% schema %}
{ "name": "Releva Recommendations", "settings": [] }
{% endschema %}
```

Every section needs three things:

* The first line reads the cart attribute. Its key must be `_rlv_h_` followed by your section file name.
* `{% if product.title != blank %}` skips products that are unpublished or not available in the visitor’s market.
* A `{% schema %}` tag, which Shopify requires on every section file.

Inside the loop, `product` is the full Shopify product object: `product.title`, `product.price | money`, `product.compare_at_price`, `product.featured_image`, `product.url`, `product.tags`, `product.vendor`, `product.type`, `product.variants`, `product.metafields`, `product.available`, `product.description`, and anything else Liquid offers.

### 2. Point the Releva block at your section

1. Go to **Online Store › Themes › Customize** and open the page.
2. Add the **Releva Product Block** app block to a section, or select the one you already have.
3. Paste the **Product Block Token** from Releva.
4. Tick **Use my theme’s product card**.
5. In **Product Card Section ID**, enter the section file name without `.liquid`, for example `releva-recs`. Leaving it blank falls back to Releva’s default template.
6. Select **Save**.

## Check it worked

* Open the page on the live storefront, not in the theme editor preview. Your cards appear inside the Releva block.
* Each product link carries `rlv_rid`, `rlv_rpid` and `rlv_rpos` parameters when you hover or inspect it.
* In the Releva admin, the block’s analytics under **Personalization › Product Blocks** start counting views and clicks: [Turn on a product block and check its results](https://releva.ai/documentation/guides/product-blocks/turn-on-a-product-block-and-check-its-results/).

## Good to know

* **Shopify’s `all_products` limit.** Shopify resolves only about 20 `all_products[handle]` lookups per page render; later handles return nothing. Releva passes the full list and logs a hint in the browser console when a block returns more than 20 products. Limit the block’s product count in Releva, or look products up another way in your section.
* **At most 5 sections per page.** The Section Rendering API returns about 5 sections per request. Releva fetches all custom sections of a page in one request and renders only the first 5; a warning is logged in the console beyond that.
* **One section file per block.** Two blocks that point at the same section id share one cart attribute and collide. If two blocks should look the same, create two section files that both `{% render %}` a shared snippet.
* **Click tracking is automatic** for any `<a href="{{ product.url }}">` link in the section. No extra markup is needed.
* **Markets and languages.** The section is fetched with the visitor’s locale prefix (`window.Shopify.routes.root`), so `all_products` resolves in the market and language the visitor is browsing in.

## Troubleshooting

| Symptom                                                       | Fix                                                                                                                                                                                                              |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The block is empty on the storefront                          | The cart attribute key in your section does not match the file name. For `releva-recs.liquid` use `_rlv_h_releva-recs`. Also check that the block is **On** for this page in Releva and that the token is right. |
| The wrapper renders but has no cards                          | The `{% assign %}` line is missing or the key is wrong, or the recommender returned no products.                                                                                                                 |
| Some cards are missing                                        | Those products are unpublished or not available in the current market, and the `product.title != blank` guard skips them. Expected.                                                                              |
| More than 20 products requested, fewer shown                  | Shopify’s `all_products` limit (above). Check the browser console for the `[Releva]` hint.                                                                                                                       |
| The block is empty in the theme editor preview                | The preview does not run the full flow. Test on the live storefront.                                                                                                                                             |
| Cards show but clicks are not tracked                         | Make sure the card links use `<a href="{{ product.url }}">`. Releva adds the tracking parameters to links whose `href` contains `/products/`.                                                                    |
| The settings have no **Use my theme’s product card** checkbox | The Releva app in your store is out of date. Update it from the Shopify admin **Apps** page.                                                                                                                     |

## Section examples

### Reuse your existing theme card

If your theme already has a product card snippet (for example `snippets/product-card.liquid`), wrap it in the loop:

```plaintext
{% assign rlv_handles = cart.attributes['_rlv_h_YOUR-SECTION-ID-HERE'] | default: '' | split: ',' %}


<div class="my-grid">
  {% for handle in rlv_handles %}
    {% assign product = all_products[handle] %}
    {% if product.title != blank %}
      {% render 'product-card', product: product %}
    {% endif %}
  {% endfor %}
</div>


{% schema %}
{ "name": "Releva Recommendations", "settings": [] }
{% endschema %}
```

### Two blocks that look the same

Each block needs its own section file. Have both render a shared snippet:

```plaintext
{% assign rlv_handles = cart.attributes['_rlv_h_YOUR-SECTION-ID-HERE'] | default: '' | split: ',' %}
{% for handle in rlv_handles %}
  {% assign product = all_products[handle] %}
  {% if product.title != blank %}
    {% render 'my-shared-card', product: product %}
  {% endif %}
{% endfor %}
{% schema %}{ "name": "Releva Trending", "settings": [] }{% endschema %}
```

### Carousel with Swiper

A Swiper carousel with arrows, a sale badge and responsive breakpoints. It initializes on the `releva:recommendations` event, which fires after Releva injects the section.

```plaintext
{% assign rlv_handles = cart.attributes['_rlv_h_YOUR-SECTION-ID-HERE'] | default: '' | split: ',' %}


<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.css">


<style>
  .releva-slider-wrap { position: relative; max-width: 1240px; margin: 0 auto; padding: 20px 50px; }
  .releva-slider-wrap .swiper { overflow: hidden; }
  .releva-slider-wrap .swiper-slide { height: auto; display: flex; }
  .releva-slider-wrap .releva-card { width: 100%; text-align: center; }
  .releva-slider-wrap .releva-card a { display: block; text-decoration: none; color: inherit; }
  .releva-slider-wrap .releva-card .img-wrap { position: relative; overflow: hidden; }
  .releva-slider-wrap .releva-card img { width: 100%; height: auto; display: block; }
  .releva-slider-wrap .releva-card h3 { font-size: 14px; margin: 10px 0 4px; font-weight: 600; }
  .releva-slider-wrap .releva-card .price { font-weight: bold; }
  .releva-slider-wrap .releva-card .price s { color: #999; font-weight: normal; margin-right: 6px; }
  .releva-slider-wrap .sale-badge { position: absolute; top: 8px; left: 8px; background: #e53935; color: #fff;
    font-size: 12px; font-weight: 700; padding: 4px 8px; border-radius: 4px; z-index: 2; }
  .releva-slider-wrap .swiper-button-prev,
  .releva-slider-wrap .swiper-button-next { position: absolute; top: 50%; transform: translateY(-50%); width: 40px; height: 40px;
    background: rgba(255,255,255,0.9); border-radius: 50%; box-shadow: 0 2px 8px rgba(0,0,0,0.15); cursor: pointer; z-index: 10;
    display: flex; align-items: center; justify-content: center; margin: 0; }
  .releva-slider-wrap .swiper-button-prev { left: 5px; }
  .releva-slider-wrap .swiper-button-next { right: 5px; }
  .releva-slider-wrap .swiper-button-prev::after,
  .releva-slider-wrap .swiper-button-next::after { content: ''; display: block; width: 10px; height: 10px;
    border-top: 2px solid #222; border-right: 2px solid #222; }
  .releva-slider-wrap .swiper-button-prev::after { transform: rotate(-135deg); margin-left: 4px; }
  .releva-slider-wrap .swiper-button-next::after { transform: rotate(45deg); margin-right: 4px; }
  .releva-slider-wrap .swiper-button-disabled { opacity: 0.35; cursor: default; }
</style>


<div class="releva-slider-wrap">
  <div class="swiper releva-swiper">
    <div class="swiper-wrapper">
      {% for handle in rlv_handles %}
        {% assign product = all_products[handle] %}
        {% if product.title != blank %}
          <div class="swiper-slide">
            <div class="releva-card">
              <a href="{{ product.url }}">
                <div class="img-wrap">
                  {% if product.compare_at_price > product.price %}
                    {% assign discount = product.compare_at_price | minus: product.price | times: 100 | divided_by: product.compare_at_price %}
                    <span class="sale-badge">-{{ discount }}%</span>
                  {% endif %}
                  {% if product.featured_image %}
                    {% assign img = product.featured_image %}
                    <img src="{{ img | image_url: width: 400 }}" alt="{{ product.title | escape }}" loading="lazy"
                         width="400" height="{{ 400 | divided_by: img.aspect_ratio | round }}">
                  {% endif %}
                </div>
                <h3>{{ product.title }}</h3>
                <div class="price">
                  {% if product.compare_at_price > product.price %}
                    <s>{{ product.compare_at_price | money }}</s>
                  {% endif %}
                  {{ product.price | money }}
                </div>
              </a>
            </div>
          </div>
        {% endif %}
      {% endfor %}
    </div>
  </div>
  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>
</div>


<script src="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.js" defer></script>
<script>
  (function () {
    function initRelevaSwipers() {
      if (typeof Swiper === 'undefined') { setTimeout(initRelevaSwipers, 100); return; }
      document.querySelectorAll('.releva-slider-wrap').forEach(function (wrap) {
        var el = wrap.querySelector('.releva-swiper');
        if (!el || el.dataset.rlvSwiperInit) return;
        el.dataset.rlvSwiperInit = '1';
        new Swiper(el, {
          slidesPerView: 2,
          spaceBetween: 15,
          navigation: {
            prevEl: wrap.querySelector('.swiper-button-prev'),
            nextEl: wrap.querySelector('.swiper-button-next')
          },
          breakpoints: { 640: { slidesPerView: 3 }, 1024: { slidesPerView: 4 }, 1200: { slidesPerView: 5 } }
        });
      });
    }
    window.addEventListener('releva:recommendations', initRelevaSwipers);
    if (document.readyState !== 'loading') initRelevaSwipers();
    else document.addEventListener('DOMContentLoaded', initRelevaSwipers);
  })();
</script>


{% schema %}
{ "name": "Releva Recommendations", "settings": [] }
{% endschema %}
```

To avoid theme-check warnings about external assets, upload `swiper-bundle.min.css` and `swiper-bundle.min.js` to your theme’s **Assets** folder and reference them with `{{ 'swiper-bundle.min.css' | asset_url | stylesheet_tag }}` and `<script src="{{ 'swiper-bundle.min.js' | asset_url }}" defer></script>`.

## Next steps

* [Connect your Shopify store](https://releva.ai/documentation/integrations/shopify/connect-your-shopify-store/): Install the Releva app and switch the app embed on, if your store is not connected yet.
* [How product blocks work](https://releva.ai/documentation/learn/product-blocks/how-product-blocks-work/): Learn the three modes and the rules that decide whether a visitor sees a block.
* [Create a product block](https://releva.ai/documentation/guides/product-blocks/create-a-product-block/): Add a product block with its feed, audience and layout, and place it on your shop.
* [Turn on a product block and check its results](https://releva.ai/documentation/guides/product-blocks/turn-on-a-product-block-and-check-its-results/): Switch your block on and read its impressions, clicks, purchases and revenue.