Klaviyo

Estimated reading: 8 minutes

Overview

Klaviyo is a behaviour-driven email and SMS marketing platform. AFI subscribes contacts to a Klaviyo list and (on Pro) fires custom events that Klaviyo Flows can listen for. Connection is via a single Private API Key — no OAuth dance.

Supported actions

Subscribe To List (Free + Pro) — adds the contact to a chosen Klaviyo list, populating profile properties from the mapped fields.
Create Event (Pro) — fires a named Klaviyo event that you can use as a Flow trigger.

Pro additionally enables richer field mapping (more sender-plugin field types — phone, date, dropdown, hidden, custom — surface for mapping) and lets you populate custom profile properties beyond name + email.

Quick reference

Need to…	Do this
Capture form signups into a Klaviyo list	Pick Subscribe To List, choose the list, map email + first / last name.
Fire a Klaviyo Flow on submission	AFI Pro — pick Create Event; the event name is what you reference in the Flow’s Metric trigger.
Capture phone numbers	Phone must be in E.164 format (`+15551234567`). Use a form plugin with international phone validation. Pro is required to map phone.
Pass UTM source / GCLID into profile	Enable Send UTM Variables in AFI > Settings > General; map `{{utm_source}}` / `{{gclid}}` onto custom profile properties (Pro).

Most common Klaviyo question: “the integration looks fine but subscribers don’t appear.” Almost always the destination Klaviyo list has double opt-in enabled — subscribers are waiting on the confirmation click. Switch the list to single opt-in (or accept that contacts only appear after confirming).

How to Use

Obtaining the API Key & Authentication

Before start, you are required to save the API Key in the plugin settings page.

Go to the WordPress admin area, click [direction] AFI > Settings [/direction].
Enable and select the Klaviyo tab.
Click on the link and you’ll be taken to the API Kyes page. Click on Create API Key if not exists, then copy it.
Paste the Key in the API Key input box and click the Save Changes button.

Create New Integration

Once API Key is saved you can start creating new integration. Click on Add New under AFI menu, New Integration page will appear.

Title

A default title will be auto-generated with an auto incremental number. You can rename it to something related to the task. It will help you to quickly recognize the correct one when there is multiple integrations setup.

Trigger

Select Correct Sender Form in Form Provider dropdown. Desired Form plugin must be installed and activated otherwise you won’t see it listed. After selecting Correct Form, all forms built under that form will be fetched and auto-populated in the Form/Task Name dropdown. Select the form that you want to integrate.

Action

Select Klaviyo in Platform dropdown. In Pro version you’ll get the option Klaviyo [PRO]. Select that.

Map Fields

Available contact lists will be auto-populated. Select the desired one. Map Email, First Name, Last Name, etc., and other fields that you want. Skip the fields that not needed. Finally, click the Save Integration button.

Phone Number

If the form on your website collects user’s phone number, you might want to send it to Klaviyo along with other data. You have to be cautious in this case. Klaviyo only accepts a fully formatted phone number including the country code before it. You need to ensure that a fully formatted phone number is sent. So there are two ways you can achieve it.

Design your forms phone number field in a way that user also enters the country code number. It could be a dropdown where the country is selectable.

Or if you expect the visitors from the same country, you can use a simple phone number input box in the form. In this case, add the country prefix while setting up the integration. For example, if you expect all the users from Spain, add +34 before the phone number tag. The plugin will automatically add +34 before all the submitted phone numbers.

Double opt-in

Double opt-in option is activated by default for lists in Klaviyo. While it is activated, new contacts will get an email first. If they click on confirm on that email, they will be added to the list. If you want the submitted data to be added directly to the list (though it is not recommended), select single opt-in.

Create Event (Track)

Use this to:

Send a custom event like “Order Placed”, “Signed Up”, or “Booked Appointment” to Klaviyo
Track event time, value, currency, and properties
Include user profile info (email, name, phone, etc.)

These events appear under Metrics in Klaviyo and can be used to:

Analyze behavior
Trigger flows or emails
Segment users based on actions

You can use this feature to send a custom event called Product Purchased with extra details like:

Product name
Amount paid
Purchase time
Customer email

AFI Pro will send this data directly to your Klaviyo account under Metrics → Custom Events.

Log

After the integration is made, when users fill up the form and submit it, the plugin initiates the process of sending data to the configured platform. It also saves a log that includes what data it tried to send, and what it got in response from that platform. So if you find an integration is not working, your first task is to check the logs. Go to AFI > Log menu and check the recent logs.

Troubleshooting

Integration not working, contact not saving to Klaviyo account

If you have created an integration, but no contact is added to Klaviyo when testing it, check the following things:

Always test using real email addresses and phone numbers. Avoid using fake ones like test@test or a@b, as modern platforms can recognize and ignore them.
If you’re sending a phone number, make sure it’s fully formatted with the country code. Check the phone number section above for more details.
If the double opt-in option is enabled in the list settings, users will receive a confirmation email. The list will only be updated once they confirm through that email. For more information, refer to the Double Opt-in section above.
If you are still having issues, please send an email to su*****@************************om.local with screenshots and a copy of the error log. We’ll be happy to help.
You can also check the Log menu, where you might find some errors logged. Review the error message and try to fix the issue accordingly.

Common issues & fixes

Distilled from years of Klaviyo support tickets.

Subscribers don’t appear in the list

The list has double opt-in enabled. This is the single most common Klaviyo ticket — it comes up nearly weekly. Switch the list to single opt-in in Klaviyo Lists settings, or instruct subscribers to confirm via email.

400 Bad Request on phone-number submissions

Phone field validation. Klaviyo requires E.164 format with country code (+15551234567). Either ensure the form pre-formats phones, or temporarily remove the phone mapping to confirm the rest of the integration works.

“duplicate_profile” 409 error

Klaviyo treats both email AND phone as unique identifiers. If a submitted phone matches one profile while the submitted email matches a different one, the API returns 409. Either dedupe upstream or align identifiers.

Lists stopped appearing in the dropdown

Most likely an old AFI version — Klaviyo changed their API spec in June 2024. Update the plugin to fix.

Same email creates only one profile / form submits don’t seem to create new contacts

By design. Klaviyo merges by email — re-subscribing the same email updates the existing profile rather than creating a new one.

Tags on individual contacts aren’t appearing

Klaviyo’s tagging model applies tags to lists / segments, not directly to individual profiles. If you need per-profile metadata, use custom properties instead.

API key won’t connect

Go to AFI > Settings > Klaviyo, delete the old API key entry, regenerate a fresh Private API key in Klaviyo (Account > Settings > API Keys > Create Private API Key), paste it back, save.

Phone validation error when using Forminator

Forminator’s international phone validation produced inputs Klaviyo rejected. Update AFI to v1.114.9 or later — the phone-sanitisation fix landed there.

Notes & caveats

Profile dedup: Klaviyo merges by email or phone match — re-subscribing doesn’t create duplicates, it updates.
Suppression list: if a contact was suppressed (unsubscribed, bounced, marked spam), re-subscribing via API won’t bring them back. Customers must opt themselves in.
Metric vs Event: Klaviyo’s Events feature triggers Flows. Metric names are case-sensitive — use stable names like form_submitted.
Custom properties are schemaless — any property name is accepted on first send.