Catalogs & recommendations - Liquid use cases

This page shows how to use Liquid with Blueshift catalog data and recommendation blocks. You'll find examples for fetching catalog items, looping through products, displaying attributes, sorting, limiting, performing inventory checks, and handling fallbacks.

All examples are verified for Blueshift's Liquid syntax and supported filters.

On this page

Fetch specific catalog items

Use the catalog_items function to populate a product list.

Liquid:

{% catalog_items product_list 'SKU-123' 'SKU-456' %}

Example data:

{
  "catalog_items": {
    "SKU-123": { "title": "Running Shoes", "price": 80 },
    "SKU-456": { "title": "Sports Jacket", "price": 120 }
  }
}
Rendered output: Two items loaded into product_list.

Back to TOC ↑

Event-based catalog lookup

When an event contains product_ids, Blueshift automatically fetches the related catalog items into bsft_event_context.products.

Liquid:

{% if bsft_event_context.products %}
{% for p in bsft_event_context.products %}
  {{ p.title }} – ${{ p.price }}
{% endfor %}
{% endif %}

Example data:

{
  "bsft_event_context": {
    "product_ids": ["SKU-123", "SKU-456"],
    "products": [
      { "title": "Running Shoes", "price": 80 },
      { "title": "Sports Jacket", "price": 120 }
    ]
  }
}
Rendered output: Running Shoes – $80
Sports Jacket – $120

Back to TOC ↑

Loop through catalog items

Iterate through the list returned by catalog_items.

Liquid:

{% for item in product_list %}
  {{ item.title }} – ${{ item.price }}
{% endfor %}

Example data:

{
  "product_list": [
    { "title": "Running Shoes", "price": 80 },
    { "title": "Sports Jacket", "price": 120 }
  ]
}
Rendered output: Running Shoes – $80
Sports Jacket – $120

Back to TOC ↑

Recommendations block

Access AI-powered recommendations from a configured block.

Liquid:

{% for product in recommendations.homepage_recos.products %}
  {{ product.title }} – {{ product.price | money }}
{% endfor %}

Example data:

{
  "recommendations": {
    "homepage_recos": {
      "products": [
        { "title": "Sneakers", "price": 90 },
        { "title": "Gym Bag", "price": 35 }
      ]
    }
  }
}
Rendered output: Sneakers – $90.00
Gym Bag – $35.00

Back to TOC ↑

Show product title, price, image, URL

Display common catalog attributes in messages.

Liquid:

{{ item.title }}
${{ item.price }}

<a href="{{ item.url }}">View product</a>

Example data:

{
  "item": {
    "title": "Leather Backpack",
    "price": 150,
    "image_url": "https://example.com/bag.jpg",
    "url": "https://example.com/bag"
  }
}
Rendered output: Leather Backpack
$150
[Image]
View product

Back to TOC ↑

Check for catalog availability

Use safe checks to avoid rendering issues when catalog items are missing.

Liquid:

{% if item and item.title %}
  {{ item.title }}
{% else %}
  Product unavailable
{% endif %}

Example data:

{
  "item": null
}
Rendered output: Product unavailable

Back to TOC ↑

Limit and sort recommendations

Control the number and order of recommended products.

Liquid:

{% for product in recommendations.homepage_recos.products limit: 3 %}
  {{ product.title }}
{% endfor %}

{% assign sorted = recommendations.homepage_recos.products | sort: "price" %}
{% for product in sorted %}
  {{ product.title }} – ${{ product.price }}
{% endfor %}

Example data:

{
  "recommendations": {
    "homepage_recos": {
      "products": [
        { "title": "Jacket", "price": 120 },
        { "title": "Cap", "price": 20 },
        { "title": "Shoes", "price": 90 }
      ]
    }
  }
}
Rendered output: Jacket
Cap
Shoes
Cap – $20
Shoes – $90
Jacket – $120

Back to TOC ↑

Sort or shuffle catalog items

Apply built-in Liquid filters to change item order.

Liquid:

{% assign shuffled = product_list | shuffle %}
{% for item in shuffled %}
  {{ item.title }}
{% endfor %}

Example data:

{
  "product_list": [
    { "title": "Hoodie" },
    { "title": "Shorts" },
    { "title": "T-Shirt" }
  ]
}
Rendered output: (Randomized order each time)

Back to TOC ↑

Price formatting

Format product prices using Blueshift’s money filter.

Liquid:

{{ item.price | money }}

Example data:

{
  "item": { "price": 120 }
}
Rendered output: $120.00

Back to TOC ↑

Inventory check

Show availability messaging based on catalog inventory fields.

Liquid:

{% if item.in_stock %}
  Available now
{% else %}
  Out of stock
{% endif %}

Example data:

{
  "item": { "title": "Backpack", "in_stock": false }
}
Rendered output: Out of stock

Back to TOC ↑

Fallback when the catalog or recommendations are empty

Provide safe default messaging when no products are available.

Liquid:

{% if product_list and product_list.size > 0 %}
  {% for item in product_list %}
    {{ item.title }}
  {% endfor %}
{% else %}
  No products to show.
{% endif %}

Example data:

{ "product_list": [] }
Rendered output: No products to show.

Back to TOC ↑

  More resources

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.