The Catalog Lookup Feature

read

Overview

The catalog tag allows you to reference specific product information from your catalog within your emails. 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 email 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 item ID of the product you are referencing. You can find your item ids by viewing your catalog.

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

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

  • If any one item referenced in your email is "unpublished" in your catalog at the time of lookup, the entire email will be skipped.
  • For a given flow email, 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 email was out-of-stock or otherwise unavailable.

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.
{% 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 inside of an image block, or an <img> tag.
{% catalog_item.id %}  Id The id of the item.

There may be additional data fields available inside of the {% catalog_item.metadata %} field. To access a preview of all your available fields. add the following snippet to a text block in a test template, and update itemID with the Item ID of one of the products from your catalog.

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

Then, preview the email.

2018-06-13_09-24-20.gif

This preview provides a raw version of 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 email. For example, a Browse Abandonment email where unique recommendations are generated based on viewed items. Instead of populating the single item a customer viewed in the email, 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 email. For example, with an Abandoned Cart email, only send the Product IDs of all abandoned items and Klaviyo can lookup 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 with sample event data below, we can build out a {% catalog %} block that references product information.

{
  "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": "https://klaviyogear.myshopify.com/collections/klaviyo-classics/products/short-sleeve-t-shirt-1",
  "title": "Classic Klaviyo T-Shirt",
  "featured_image": {
    "full": {
      "src": "https://www.klaviyo.com/media/images/examples/products/klaviyo-tshirt-full.png"
    },
    "thumbnail": {
      "src": "https://www.klaviyo.com/media/images/examples/products/klaviyo-tshirt-thumbnail.png"
    }
  },
  "id": "KLAVIYO-TSHIRT",
  "metadata": {
    "Color": "Grey",
    "Design": "Standard"
  }
}

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 email 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 custom properties. For example, the following profile shows three recommended products attached to a profile.

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

Here is an example of the syntax:

{% catalog person|lookup:'RecommendedProduct1' %}
 <img src="{{ catalog_item.featured_image.thumbnail.src }}" style="display: inline-block; border: none" width="150px" />
{{ catalog_item.Title }}
 {% endcatalog %}

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

Was this article helpful?
1 out of 2 found this helpful