Skip to content

Area: Developers

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.

  • 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.
  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.
  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, replace YOUR-SECTION-ID-HERE with the file name without .liquid (here releva-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.

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

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 %}

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 %}

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