How to Sync a Custom Catalog Feed to Klaviyo

Last updated at:


Learn how to sync your custom catalog feed to Klaviyo, if your catalog feed is not synced by one of our pre-built ecommerce integrations, or you have catalog information stored in another system. Then, you can use items from that catalog feed to populate emails. 

This guide will walk you through the requirements for your custom catalog feed and how to sync your custom catalog feed to Klaviyo. Once your feed has been built and synced to your Klaviyo account, you will be able to use Klaviyo’s Product Recommendation, Product Block, and Catalog Lookup Tag features. Klaviyo resyncs the information from a given catalog feed source every six hours.

Using Custom Catalog Content

The custom catalog feature can be used to leverage product feeds and easily insert hand-picked catalog items in an email, as well as Klaviyo-generated personalized product recommendations. To learn how, check out How to Use Custom Catalog Data in Emails. Your custom catalog source can contain anything that you would consider to be “items” you want to share or recommend to your subscribers, whether these are products, store locations, ticketed events, or blog articles.  

Custom Catalog Requirements

Klaviyo can sync custom catalog feeds that meet the following requirements:

  • The catalog is a public, hosted feed of all the items in your catalog
  • The feed is in JSON or XML. Check out an example custom catalog feed in JSON and an example custom catalog feed in XML
  • The data in the feed is only one node deep, not nested JSON or XML (unless it is hosted on Google Merchant Feeds).
  • The size of any one feed file should not exceed 100 MB; for optimal performance, we recommend each feed file not exceed 50 MB. If your file exceeds this amount, please split the feed into multiple files. All files used as sources will feed into the same catalog in Klaviyo.
  • Required fields must not be left blank. For unavailable numeric fields, pass a zero (0), and for unavailable text fields, pass something indicating this such as “n/a” or “unavailable”.
  • If your feed is hosted with a caching layer, disable caching for the location where the feed is hosted or refresh this cache when the feed is updated. Otherwise, Klaviyo will only pull updated data for the feed items after the cache is refreshed.

If your feed will have more than 1 million items, please contact Klaviyo support before you reach the “Add feed to account” step of this setup. This will allow us to pre-allocate necessary resources on our end to better optimize for larger catalog sizes.

Mappable Catalog Properties

You can include any data you want in your custom catalog feed. In addition to the data you choose to include, Klaviyo also has some special mappable properties that unlock certain features of our platform. Below is a list of the required and optional fields available for our default catalog feed setup.

Required Fields

In order for the mapping step of the catalog setup to work, the following required fields must be included for each item in the feed. The name in parentheses is the field that they will map to in Klaviyo:

  • Unique ID ($id): Can be text, numeric, or alphanumeric, but must be unique
  • Title ($title): The name of the item
  • URL ($link): The URL at which a person can find this item
  • Image URL ($image_link): A URL at which the image for this item is hosted, which must use https
  • Description ($description): A text description of the item

The Unique ID ($id) of an item in the feed must match the item ID in the metric you want to base personalized recommendations on. For example, if you pass an Ordered Product metric to Klaviyo, the value passed as a “Product ID” property must match the Unique ID of that product in your catalog feed. 

To find the Product ID in an Ordered Product metric, navigate to the Analytics tab in your Klaviyo account and click Metrics. Find the Ordered Product metric in the list or via search, click on it, then click Activity Feed. Here you will find individual metrics. Click on Details for an individual metric to show the full metadata for that metric, including the Product ID.

Klaviyo Ordered Product Event details within Activity Feed tab, with numerous options

Optional Fields

In addition to the required fields above, we also recommend passing the following optional fields:

  • Price (price): The numeric item price, with no currency symbol
  • Categories (categories): A comma-separated list/array of categories, tags, or collections
    associated with an item

Additionally, there are fields that can be added to enable Back in Stock. Enabling Back in Stock relies on item inventory tracking. Include additional fields for:

  • Inventory ($inventory_quantity): a number representing the stock for a given item.

You can also include the following optional parameter:

  • Inventory Policy ($inventory_policy): a number that controls how Klaviyo treats product visibility in product feeds and blocks. This field has two available options:
    • 1: If the policy is set to 1, a product will not appear in dynamic product recommendation feeds and blocks if it is out of inventory quantity

    • 2: If the policy is set to 2, a product can appear in dynamic product recommendation feeds and blocks regardless of inventory quantity. This is also the behavior when this field is not set.

Catalog Property Considerations

As you set up your catalog feed, here are some functionality considerations to keep in mind:

  • The only way to filter your feed in Klaviyo is by category names. If there is something you want to filter your feed by, make sure to include it as a category.
  • Make sure the first item in your feed contains all available fields (in case some of your items do not). The mapping step of the catalog sync draws on the fields from the first item in the feed, so it is important that all fields are present in order to map successfully. For example, if some of the items in your feed contain eight fields, but some items only contain six of those fields, the first item in the feed should contain all eight fields. 

Sync Your Catalog

Add Your Feed

Once your feed is set up and hosted at a URL, add it to your account.

Navigate to the Catalog tab in Klaviyo. If this is your first custom catalog feed sync, you’ll see the following page. Click Add a Custom Catalog to be brought to the custom sources page (see below).

Catalog tab in Klaviyo with a blue Set up an Integration button and a grey Add a Custom Catalog button above three other options

If you’ve added a custom catalog feed before and navigate to the Catalog tab, you’ll see the following page. Click Manage Custom Catalog Sources in the upper right corner. This step will also bring you to the custom sources page.

Catalog tab in Klaviyo with populated items in various fields with a Manage Custom Catalog Sources button in blue

Click Add New Source. This will bring you to the define feed source page. 

Catalog Custom Sources page in Klaviyo, with list of sources  and a Add New Source button in blue at top right
Name your feed source and add the URL. You can optionally add a username and password if access to the feed URL requires them (your feed URL will determine this setting). Then, click Define Source

Create custom source page in Klaviyo with feed source setting fields and Define Source button in blue at the bottom

You’ll receive a green success callout showing your source has been added.

Catalog custom sources page in Klaviyo app with list of sources and Magento Comeback Kid Coffee source success button in green

Map Feed Fields

After your feed has been added as a catalog source, you can configure the feed fields mapping. From the Custom Sources page, click Configure field mapping under Status next to the source.

Klaviyo will try to automatically map the fields in your feed based on their name, but if they do not automatically map, you may need to set them yourself. Using all of the required and optional properties above, your mapping should look like this:

Configure field mapping page with field option forms and and Update Field Mapping button in blue in bottom left corner

Toggle a field “on” in the Required column to tell Klaviyo to only sync items that include that designated field. This is auto-populated for fields required by Klaviyo and can be optionally toggled on for additional fields.

If your catalog has extra fields you would like to include, such as inventory fields to enable Back in Stock, you can create a new field by typing the new field name into the Klaviyo Field column for that field and clicking Create “Option”.

Configure field mapping page showing Create “Option” in Klaviyo with an Update Field Mapping button in blue in the bottom left corner

Finalize Your Catalog

Once you’ve mapped the catalog feed in your account, the last step in the setup process is to reach out to our Support Team with the following information:

  1. The name of the metric on your account you would like to use for personalized recommendations. In most cases, Ordered Product or Viewed Product is the best metric to use.
  2. The name of the property in that metric’s metadata which corresponds to the Unique ID ($id) used in your catalog feed (e.g., Product ID).

Once this step is complete, you will be able to access and use the Product Feed and Product Block features.

Delete a Source

If you want to delete a custom catalog feed source, such as a test source you are no longer using, navigate to Catalog > Manage Custom Catalog Source and click the three dot dropdown next to the source to be deleted. Then, click Delete.

Pop up for custom catalog Delete Source option in Klaviyo with a cancel  button in grey and Delete in red

By deleting a source, you will lose all catalog categories and items that are displayed inside of Klaviyo. You may also lose the ability to utilize these items inside of your flows. 

Additional Resources

How to Use Custom Catalog Data in Emails 

How to Enable Back in Stock for Custom Catalog Feeds

Guide to the Catalog Tab 

Was this article helpful?
12 out of 17 found this helpful