Use your theme's product card for Releva recommendations
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
Section titled “Before you start”- The Releva app is installed and the Releva.ai app embed is on: 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.
How it works
Section titled “How it works”- The Releva Product Block app block renders an empty placeholder with your token and, when custom rendering is on, the id of your section.
- 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. - 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. - Links in your section that point at
/products/get Releva’s click-tracking parameters (rlv_rid,rlv_rpid,rlv_rpos) added, and areleva:recommendationsevent is dispatched onwindowwith the recommender indetail.recommenders.
1. Create a section file
Section titled “1. Create a section file”- In your Shopify admin, go to Online Store › Themes, select … › Edit code on the theme.
- In the Sections folder, select Add a new file and name it, for example,
releva-recs.liquid. - Paste the minimal section below or one of the examples, replace
YOUR-SECTION-ID-HEREwith the file name without.liquid(herereleva-recs), and select Save.
{% 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
Section titled “2. Point the Releva block at your section”- Go to Online Store › Themes › Customize and open the page.
- Add the Releva Product Block app block to a section, or select the one you already have.
- Paste the Product Block Token from Releva.
- Tick Use my theme’s product card.
- In Product Card Section ID, enter the section file name without
.liquid, for examplereleva-recs. Leaving it blank falls back to Releva’s default template. - Select Save.
Check it worked
Section titled “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_rpidandrlv_rposparameters 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.
Good to know
Section titled “Good to know”- Shopify’s
all_productslimit. Shopify resolves only about 20all_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), soall_productsresolves in the market and language the visitor is browsing in.
Troubleshooting
Section titled “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
Section titled “Section examples”Reuse your existing theme card
Section titled “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:
{% 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
Section titled “Two blocks that look the same”Each block needs its own section file. Have both render a shared snippet:
{% 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
Section titled “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.
{% 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>.