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",

  "inputProduct": {
    "title": "string",
    "description": "string",
    "imgUrl": "string",
    "image": {
      "scalableUrl": "string",
      "url": "string"
    },
    "url": "string",
    "originalUrl": "string",
    "trackingCode": "string",
    "productNumber": "string",
    "price": "number|null",
    "oldPrice": "number|null",
    "discountPercentage": "number",
    "currency": "string",
    "onSale": "boolean",
    "brand": "string|null",
    "inStock": "boolean",
    "priceExVat": "number|null",
    "oldPriceExVat": "number|null",
    "keywords": "string",
    "ean": "string|null"
  },

  "primaryProducts": [
    {
      "title": "string",
      "description": "string",
      "imgUrl": "string",
      "image": {
        "scalableUrl": "string",
        "url": "string"
      },
      "url": "string",
      "originalUrl": "string",
      "trackingCode": "string",
      "productNumber": "string",
      "price": "number|null",
      "oldPrice": "number|null",
      "discountPercentage": "number",
      "currency": "string",
      "onSale": "boolean",
      "brand": "string|null",
      "inStock": "boolean",
      "priceExVat": "number|null",
      "oldPriceExVat": "number|null",
      "keywords": "string",
      "ean": "string|null"
    }
  ],

  "otherProducts": [
    {
      "title": "string",
      "description": "string",
      "imgUrl": "string",
      "image": {
        "scalableUrl": "string",
        "url": "string"
      },
      "url": "string",
      "originalUrl": "string",
      "trackingCode": "string",
      "productNumber": "string",
      "price": "number|null",
      "oldPrice": "number|null",
      "discountPercentage": "number",
      "currency": "string",
      "onSale": "boolean",
      "brand": "string|null",
      "inStock": "boolean",
      "priceExVat": "number|null",
      "oldPriceExVat": "number|null",
      "keywords": "string",
      "ean": "string|null"
    }
  ]
}

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.

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.

{{ event.subject }}

{{ event.previewText }}

Template data access¶

{{ event.headline | safe }} {# (1)! #}
{{ event.body | safe }} {# (2)! #}
{{ event.primaryProducts.0.title }} {# (3)! #}

1. Use | safe on all fields that may contain HTML to allow it to render correctly instead of being escaped.
2. body may contain <b>, <em>, <ul>, and <li> tags — always use | safe.
3. Access the first primary product using .0. dot notation. Use a loop if you need to render multiple products.

Core content fields¶

Product fields¶

Input product¶

inputProduct is the product that triggered this message — the item the customer previously bought or viewed. You can reference it in templates to give the email context, for example to remind the customer what they purchased before recommending a replenishment or alternative.

First primary product¶

Looping through primary products¶

{% for product in event.primaryProducts %} {# (1)! #}
  {{ product.title }} {# (2)! #}
  {{ product.url }}
{% endfor %}

1. Loops over all primary products. Typically one, but the template should handle more.
2. Inside a loop, access fields directly on product — no need for event.primaryProducts.0.X.

Looping through recommended products¶

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

Conditional rendering of recommended products¶

{% if event.otherProducts | length > 0 %} {# (1)! #}
  {{ event.otherProductsTitle | safe }} {# (2)! #}
  {{ event.otherProductsText | safe }}

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

1. Always guard the recommended products section — otherProducts may be an empty array.
2. Used here as a precaution — only body, headline, and product description fields are documented as containing HTML.

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