Using Product Agents with Klaviyo¶

This guide explains how to integrate Product Agents with Klaviyo using a metric-triggered flow.

It covers:

• How Product Agents send events to Klaviyo
• How to configure the required Klaviyo flow
• The full event payload structure
• All supported merge variables
• How to render product data safely in templates

This guide is intended for developers, agencies, and technical marketers responsible for Klaviyo setup.

Integration model¶

When using Klaviyo as the delivery channel:

• Product Agents emit a custom metric event to Klaviyo
• Klaviyo triggers a flow when the event is received
• Klaviyo controls consent, suppression, smart sending, and delivery
• Product Agents do not send emails directly to customers

Each Product Agent message corresponds to one event sent to Klaviyo.

Prerequisites¶

Before setting up the integration, ensure that:

• You have access to the Klaviyo account
• You can create and edit flows
• You can create and edit email templates
• You have a Klaviyo API key with permission to send events

Event name and trigger¶

Product Agents send a custom Klaviyo metric named:

helloretail

Your Klaviyo flow must be a metric-triggered flow using this event.

There should be exactly one flow listening to this event.

Event payload structure¶

Product Agents send the following properties as part of the Klaviyo event.

{
  "subject": "string",
  "previewText": "string",
  "headline": "string",
  "body": "string",
  "callToAction": "string",
  "messageType": "string",

  "otherProductsTitle": "string",
  "otherProductsText": "string",
  "otherProductsCallToAction": "string",

  "primaryProducts": [
    {
      "title": "string",
      "description": "string",
      "image": {
        "scalableUrl": "string",
        "url": "string"
      },
      "url": "string",
      "price": "number|null",
      "oldPrice": "number|null",
      "currency": "string",
      "onSale": "boolean"
    }
  ],

  "otherProducts": [
    {
      "title": "string",
      "description": "string",
      "image": {
        "scalableUrl": "string",
        "url": "string"
      },
      "url": "string",
      "price": "number|null",
      "oldPrice": "number|null",
      "currency": "string",
      "onSale": "boolean"
    }
  ]
}

Notes¶

• primaryProducts is always an array and may contain one or more products
• otherProducts may be empty
• All fields should be treated as optional unless explicitly required by your template
• For information about how the image scaling mechanism works refer to Integration Overview

Creating the Klaviyo flow¶

1. Log in to Klaviyo
2. Go to Flows
3. Create a new flow
4. Choose Metric-triggered flow
5. Select the metric helloretail
6. Save the flow
7. Add an Email action to the flow

The email action must be set to Live for messages to be sent.

Do not add additional filters to the trigger unless explicitly required.
Filtering the trigger may block Product Agent messages.

Subject line and preview text¶

The subject line and preview text are provided dynamically by Product Agents.

Configure them in the email settings, not in the template body.

Subject¶

{{ event.subject }}

Preview Text¶

{{ event.previewText }}

Do not hard-code subject lines or preview text.

Template data access¶

{{ event.headline }}
{{ event.body }}
{{ event.primaryProducts.0.title }}

For fields containing HTML (headline, body, product descriptions), use |safe.

Core content fields¶

Product fields¶

First primary product¶

Looping through primary products¶

{% for product in event.primaryProducts %}
  {{ product.title }}
  {{ product.url }}
{% endfor %}

Looping through recommended products¶

{% for product in event.otherProducts %}
  {{ product.title }}
  {{ product.url }}
{% endfor %}

Conditional rendering of recommended products¶

{% if event.otherProducts | length > 0 %}
  {{ event.otherProductsTitle | safe }}
  {{ event.otherProductsText | safe }}

  {% for product in event.otherProducts %}
    {{ product.title }}
  {% endfor %}
{% endif %}

Recommended products section fields¶

messageType values¶

The messageType field identifies which Product Agent generated the message.

These values are stable technical identifiers and can be used in templates if conditional rendering is needed.

Smart sending and test mode¶

Klaviyo Smart Sending rules apply after the Product Agent event is received.

This means:

• Events may be received even if emails are blocked
• Emails blocked by Smart Sending do not reach the inbox
• Product Agents do not retry messages blocked by the channel

During testing, Smart Sending may need to be temporarily disabled to avoid confusion when sending repeated test messages.

These topics are covered in separate documentation:

• Using Product Agents with Webhooks