Klaviyo Integration

Klaviyo's recommendation and automation engines only work if they have an up-to-date picture of your catalog. Once a catalog is synced, Klaviyo combines your product data with on-site and email behavior (viewed products, added-to-cart events, checkout-started events, and purchase history) to build personalized recommendation blocks, trigger back-in-stock notifications when inventory is replenished, and populate abandoned cart and browse abandonment emails with the exact products a shopper looked at. Klaviyo notes that products missing key data, such as an image, are automatically excluded from recommendations, and that already-purchased or out-of-stock items are filtered out of suggestion blocks, so feed completeness and accuracy directly determine how well these flows perform.

Once a custom catalog is synced, Klaviyo lets marketers drag a product block into a flow or campaign email and populate it dynamically, without writing HTML, since Klaviyo's own documentation notes that "product blocks do not support any custom HTML." These blocks can pull recently viewed products (based on the Viewed Product metric), items similar to what a customer viewed or ordered, products added to cart (from Added to Cart or Checkout Started events), or classic best-seller and static lists. For more advanced use cases, such as a proprietary recommendation engine, Klaviyo also supports catalog lookup tags that reference specific items by their unique item ID inside templates. All of this depends on the catalog feed carrying clean, complete item records with the right identifiers.

Klaviyo supports two paths for syncing an external catalog: a hosted custom catalog feed, or direct integration through the Catalogs API.

For a hosted feed, Klaviyo accepts JSON or XML - CSV is not supported. The feed must be publicly reachable over HTTPS, and Klaviyo pulls it on a fixed schedule rather than on demand. Klaviyo's guide is explicit that the data in the feed should be "only one node deep, not nested JSON or XML" (Google Merchant feeds are the one documented exception), that the first item in the feed must contain every field you intend to map so Klaviyo can detect the schema, and that no required field should be left blank - Klaviyo recommends using "0" for unavailable numbers and "n/a" for unavailable text rather than omitting the field. Feed files can be up to 100MB, though Klaviyo recommends staying under 50MB for reliable processing, and larger catalogs can be split across multiple files feeding into one catalog.

Alternatively, systems that need real-time or event-driven updates can push items directly through Klaviyo's Catalogs API, which uses a resource ID format of {integration_type}:::{catalog_type}:::{external_id} - for example $custom:::$default:::3829918373-TShirt-1. Klaviyo currently only supports the $custom integration type paired with the $default catalog type.

Feedance generates the hosted JSON or XML catalog feed Klaviyo expects, mapped field-for-field to Klaviyo's schema, so you don't have to hand-build a flat, single-node feed or maintain a custom API integration yourself.

1. In Feedance, create a new feed and select Klaviyo as the destination template.
2. Map your product data to Klaviyo's required fields ($id, $title, $description, $link, $image_link) and add the optional fields you want to use, such as $price, $inventory_quantity, $inventory_policy, and categories.
3. Publish the feed to get a public, HTTPS-hosted feed URL from Feedance.
4. In Klaviyo, go to Content > Products > Manage Custom Catalog Sources, click Add new source, and paste in the Feedance feed URL.
5. Configure field mapping on Klaviyo's Custom Sources page to confirm each attribute lines up correctly, then contact Klaviyo Support with your relevant metric names and Item ID property names so their team can finalize the catalog for production, as Klaviyo's own setup flow requires.
6. Once Klaviyo confirms the catalog is live, monitor the first sync in Feedance and in Klaviyo to catch any mapping issues before recommendation blocks or Back in Stock flows go live.

Klaviyo pulls custom catalog feeds on a fixed 6-hour cycle. If your feed sits behind a caching layer, Klaviyo's documentation warns that you must disable caching or manually refresh the cache when the underlying data changes, otherwise Klaviyo will keep pulling stale, cached data even after your source updates. Beyond the feed sync itself, Klaviyo's recommendation models need their own runway: the platform states it typically takes 2 days to a week for its systems to train on a new catalog, and that recommendation models are generally retrained every 2-7 days depending on usage. Feedance refreshing your feed reliably on Klaviyo's 6-hour cadence keeps price, inventory, and new-product changes flowing into that training loop as quickly as Klaviyo's own architecture allows.

Klaviyo's sync and troubleshooting documentation calls out several recurring causes of catalog sync failures:

• Feed not accessible: Klaviyo cannot reach the source URL, typically because it's password-protected or otherwise blocked behind a security layer.
• Stale cached data: a caching layer in front of the feed URL serves Klaviyo an old version of the file, so updates never appear until the cache is cleared or refreshed.
• Nested data structures: Klaviyo's parser expects data "only one node deep," so nested JSON or XML (outside the Google Merchant feed exception) will fail to map correctly.
• Incomplete first item: because Klaviyo uses the first item in the feed to detect the schema, an item missing fields that appear later in the file can cause those fields to be dropped for the whole catalog.
• Duplicate or missing identifiers: Klaviyo has a dedicated troubleshooting article for duplicate or missing identifier errors, and on the Catalogs API side, attempting to create an item with an external_id that already exists returns a 409 Conflict; bulk job failures list the specific field and reason in an errors array in the API response.
• Missing images: items without an image URL are excluded from Klaviyo's recommendation engine even if the rest of the record is valid.

Keep the Item ID stable across every sync - Klaviyo matches items on this value, so a changing ID makes Klaviyo treat an existing product as brand new and resets any accumulated recommendation and inventory history for it. Populate every optional field Klaviyo can use for automation, especially $price and $inventory_quantity, since inventory data is required to turn on Back in Stock flows and price data feeds price-drop campaigns. Make sure every item has a valid HTTPS image URL, since Klaviyo silently drops image-less products from recommendation blocks rather than erroring. If you're managing more than roughly 50MB of catalog data, split it across multiple feed files pointed at the same catalog rather than pushing one oversized file, and if your catalog approaches Klaviyo's documented caps of 250,000 items, 500,000 variants, or 2,500 categories, or your feed will exceed 1 million items, plan to contact Klaviyo Support ahead of setup, per their own guidance.

Does Klaviyo accept CSV feeds?
No. Klaviyo's custom catalog feed sync only accepts JSON or XML; CSV is not a supported format.

How is a custom catalog feed different from the Catalogs API?
A custom catalog feed is a hosted file Klaviyo pulls on its own 6-hour schedule. The Catalogs API lets you push item creates, updates, and deletes directly, which suits merchants who need faster or event-driven updates than a polled feed can provide.

Why isn't my catalog updating in Klaviyo?
The most common causes Klaviyo documents are a caching layer serving stale data, a feed URL that's become inaccessible or protected, or a malformed/nested feed structure that fails Klaviyo's one-node-deep requirement.

What do I need in my feed to enable Back in Stock alerts?
Klaviyo's Back in Stock guide requires the $inventory_quantity field on every item in your custom catalog feed; without it, Klaviyo has no stock signal to trigger a restock notification.

Can I use custom HTML in Klaviyo's product recommendation blocks?
No. Klaviyo's documentation states product blocks do not support custom HTML; advanced formatting requires using the Source option in a text block or catalog lookup tags instead.