Catalog lookup tag reference

Last updated at:

You will learn

Learn how to use the catalog tag, which allows you to reference specific product information from your catalog within your emails and SMS messages. This is useful when you want to create custom product recommendations, or cross-reference product information. For example, if you're using your own recommendation engine, you can pass your own product recommendations as event or profile data to Klaviyo, and then utilize that data in templates.

Please note that this guide is designed for tech-savvy marketers or customers who have access to a developer.

The {% catalog %} tag

The {% catalog %} tag uses the following syntax:

{% catalog itemID unpublished="cancel" %}
{% endcatalog %}

Replace itemID with the Product ID of the product you are referencing. This is the Product ID as synced from your own product catalog. Note, this lookup is specifically for the Product ID and not the SKU.

Including unpublished="cancel" will ensure that you don't send your message in the event that the item referenced is unpublished. This argument is optional. 

  • If any item referenced in your message is unpublished in your catalog at the time of lookup, the entire message will be skipped.
  • For a given flow message, you can navigate to Analytics > Recipient Activity > Other and see a list labeled Skipped: Catalog Item Unavailable. This list includes all profiles that were skipped because an item featured in the message was out-of-stock or otherwise unavailable.

When using this feature, between the opening and closing catalog tags, you can reference specific data from the item associated with the itemID in your Klaviyo product catalog.

The following data is available to reference inside of a {% catalog %} block.

Template tag Name Description
{{ catalog_item.description }} Description The description of the item.
{{ catalog_item.tags }} Tags Any tags added to the item.
{{ catalog_item.url }} URL The url for accessing the item in your store.
{{ catalog_item.title }} Title The title of the item.
{% currency_format catalog_item.metadata|lookup:"$price" %} Price The price of an item. This tag formats the item price with the correct currency prefix.
{{ catalog_item.featured_image.full.src }} Full image The url for the full image of the item. Use this inside of an image block, or an <img> tag.
{{ catalog_item.featured_image.thumbnail.src }} Thumbnail The url for the full image of the item. Use this in an <img> tag in custom HTML, or use it as a dynamic image placeholder URL surrounded by the opening and closing {% catalog %} tags 
{{ }}  Id The Product ID of the item.

There may be additional data fields available that are considered metadata. To reference one of these additional item properties, you can use the variable syntax: {{ catalog_item.metadata.color }}. In this case, the variable will pull in the "color" value associated with the item stored in the item's metadata.

To access a preview of all available details stored on an item — including all metadata — add the following snippet to a text block in a test template, and update itemID with the Product ID of one of the current products in your catalog.

{% catalog itemID %}
{{ catalog_item }}
{% endcatalog %}

Then, preview the email. This preview provides a raw version of all the data available for your products.

Lookup an item ID passed with an event

Using a catalog lookup with an event is mostly used in the following scenarios:

  • If you're using a custom integration where product recommendations are passed along with an event to show in the message. For example, a browse abandonment message where unique recommendations are generated based on viewed items. Instead of populating the single item a customer viewed in the message, you can generate and populate a set of recommended items based on that item viewed. A set of Product IDs needs to be sent to Klaviyo along with the event.
  • If you're using a custom integration and you prefer not to send all product details that need to go in an message. For example, with an abandoned cart message, only send the Product IDs of all abandoned items and Klaviyo can look up each one to pull in all relevant details. There's no need for every event to contain product name, price, image, etc. since all of this can be populated by only passing the Product ID to Klaviyo, then looking up the information in your Klaviyo product catalog.

When using a {% catalog %} tag with an event, the lookup is based on the Item ID of the catalog item (this will either be Product ID or SKU depending on the integration).

For an event where the identifying value passed is Item ID, the lookup tags will appear like this:

{% catalog event.ItemID %}
{% endcatalog %}

Within this {% catalog %} block, add template variables for the data you would like to populate regarding each item (i.e. title, image, etc.)

For example, using the sample catalog item data below, we can build out a {% catalog %} block that references key product information:

Catalog item data:

  "description": "Standard issue for all Klaviyos. This t-shirt has the Klaviyo logo on the front and mark diagram on the back.",
  "tags": "apparel,t-shirt,new-arrival",
  "url": "",
  "title": "Classic Klaviyo T-Shirt",
  "featured_image": {
    "full": {
      "src": ""
    "thumbnail": {
      "src": ""
  "metadata": {
    "Color": "Grey",
    "Design": "Standard"

Template block syntax:

The syntax for the following {% catalog %} block would pull in the item image, item title, and item description from your catalog, for each item in the event:

{% for item in event.Items %}
	{% catalog item.SKU %}
 		<img src="{{ catalog_item.featured_image.full.src }}"/>
 		{{ catalog_item.title }}
 		{{ catalog_item.description }}
 	{% endcatalog %}
{% endfor %}

If the lookup can’t find the item it’s looking for, the message is skipped and does not send.

Lookup an item ID as a custom property

If you're using your own recommendation engine you can pass recommended item IDs to profiles in Klaviyo as a custom property. For example, the following profile shows three recommended product IDs attached to a profile as an array.

An array of recommended products stored as a profile property

Using a {% catalog %} tag, you can reference information from any of these products when messaging this customer.

Here is an example of the syntax:

{% for item in person|lookup:'Recommended Products' %}{% catalog item %} 
<img src="{{ catalog_item.featured_image.thumbnail.src }}" style="display: inline-block; border: none" width="150px" />
<p>{{ catalog_item.title }} {% endcatalog %}</p>
{% endfor %}

If the lookup can’t find the item it’s looking for, the message is skipped and does not send.

Additional resources

Was this article helpful?
80 out of 147 found this helpful