Setting up Klaviyo¶

Your Klaviyo API key must include permissions to:

• Read access to Lists, Segments, Profiles, Metrics & Campaigns
• Full access to Templates, Events & Flows

If the permissions are incomplete, the setup will stop and show an error message explaining what is missing.

Use a list when:

• You have a single, dedicated marketing consent list that all opted-in customers are added to (the most common setup)
• Your signup forms add subscribers directly to a Klaviyo list
• You want the simplest and most predictable setup — list membership is explicit and does not change unless a contact is manually added or removed

Use a segment when:

• You run multiple language domains and want to make sure each customer only receives emails in their language — for example, a segment scoped to your German-speaking subscribers
• You only want to contact customers who have been active recently — for example, customers who have opened an email or placed an order in the last 90 days
• You want to limit emails to customers who have actually opened emails before, rather than everyone who is subscribed
• You want to combine several conditions — for example, opted-in customers who have visited the site in the last 60 days and have not made a purchase
• You want to exclude specific customers from Product Agent emails without unsubscribing them from your other marketing — see the Excluding specific profiles section below

Segments in Klaviyo are evaluated dynamically. A customer may enter or leave a segment at any time as their profile data changes. With lists, membership is static until explicitly changed. If your permission logic is complex or frequently updated, segments offer more flexibility, but list-based permission is simpler to reason about and debug.

Because each agent gets its own dedicated Klaviyo flow during onboarding, agent-level analytics are available by default in Klaviyo's flow reporting.

If you have existing flows set up manually, or want to combine multiple agents into a single flow and use Trigger Filters to split them, you can configure that manually in Klaviyo.

To add a Trigger Filter:

1. Open the flow in Klaviyo
2. Click the Trigger
3. Under Trigger Filters, click Add and select messageType from the dropdown

messageType is sent with every Product Agent event and identifies which agent generated it. The available values are:

Replenishment Reminder

REPLENISHMENT_REMINDER

Alternative Picks

SIMILAR_PRODUCT_RECOMMENDATIONS

Recommended Add-ons

ACCESSORY_RELATED_PRODUCT_UPSELL

Price Drop – Viewed Product

PRICE_DROP_VIEWED_PRODUCT

Price Drop – Purchased Replenishment

PRICE_DROP_PURCHASED_REPLENISHMENT

Price Drop – Alternative Product

PRICE_DROP_ALTERNATIVE_PRODUCT

Price Drop – Complementary Product

PRICE_DROP_COMPLEMENTARY_PRODUCT

Trigger Filters can also be used with other event properties, such as language, which is useful if multiple websites or languages send data into the same Klaviyo account.

By default, Product Agents generate dynamic text for your emails using AI. If you prefer to write your own copy, or want to use product variables directly in your templates, see Customising Your Email Templates.

If a customer feels they are receiving too many emails, you may want to stop them from receiving Product Agent emails without unsubscribing them from your regular marketing. The cleanest way to do this in Klaviyo is to combine a custom profile property with a segment.

Step 1: Set a custom property on the profile¶

In Klaviyo, open the profile you want to exclude. Scroll down to the Custom properties section and click Add custom property.

Add the following:

• Property name: excludeProductAgents
• Value: yes (as a string)

Using a string value avoids Klaviyo treating the field as a boolean, which keeps the segment builder straightforward. You can set this manually on individual profiles, or update it programmatically via the Klaviyo API.

Step 2: Create or update your permission segment¶

If you are already using a segment as your permission source, add a condition to exclude anyone with this property set. If you are using a list today, you will need to switch to a segment first — see Step 2 above.

The segment condition should be:

• Base: your existing subscriber list or consent condition (for example, "is subscribed to email marketing")
• And: excludeProductAgents is not set (Type: Text)

Because the condition checks for existence rather than a specific value, you only need to set the property on profiles you want to exclude. Everyone else is included by default — no property needs to be set on the rest of your subscriber base.

This keeps the customer in your main marketing audience so they continue to receive newsletters and campaigns, but removes them from the segment that Product Agents use to check permission.

Step 3: Select the segment as your permission source¶

If you have not already done so, go to the Product Agents settings in Hello Retail and set this segment as your permission source.

Once the segment is active, Product Agents will no longer send emails to any profile where excludeProductAgents is set to true. Removing the property from a profile will automatically add them back to the segment on Klaviyo's next evaluation.

If an expected email was not received, there can be several possible reasons:

• The Klaviyo flow is not set live
  The flow may exist but is still in draft mode, so the event does not trigger any emails.

• Smart Sending is enabled in the flow
  If the recipient has already received another email within the Smart Sending window, it may suppress the message.

• Flow filters prevent the email from triggering
  The event may be sent correctly, but the filters in the flow do not match the event data.

• The flow is not triggered by the Product Agent event
  The Klaviyo flow must listen to the correct event from Hello Retail in order to send emails.

• The email address has unsubscribed from marketing emails
  If the recipient has previously unsubscribed, Klaviyo will not send the message.

Product Agents send events to Klaviyo. Whether an email is actually sent depends on the configuration of the Klaviyo flow.