Klaviyo is an an e-commerce focused multi-channel marketing platform. With Klaviyo, businesses of all sizes can deliver personalized experiences across owned marketing channels such as email and SMS.

When integrated with Klaviyo, Freshpaint will create and update user profiles in Klaviyo and associate events with those user profiles.

Destination Info





Getting Started

Follow these steps in order to enable the Klaviyo destination:

  1. Go to the Klaviyo configuration page in Freshpaint and click "configure".

  2. Find your public Klaviyo API Key under Account > Settings > API Keys and enter it into the Integration Settings in Freshpaint.

  3. By default, email is set as the preferred user identifier in Klaviyo. If for some reason, you would like to prioritize a different identifier, uncheck this box.

  4. Choose a connection mode. You can take a look at the differences between the connection modes in the reference section below.

Set up User Identification

In order to create profiles and attribute events to those profiles in Klaviyo, you need to have User Identification set up. See this section below for more on user identification specifically for Klaviyo.

Enable Klaviyo Destination for Event(s)

In order to send events to Klaviyo, you'll need to enable the Klaviyo destination for the desired event in the event definition.

Confirm events are sending successfully to Klaviyo

You can see events associated with user profile by clicking into a user profile


When you call freshpaint.identify, Freshpaint will create or update a profile in Klavyio.

You must include one of the following: email, phone, or a unique identifier such as a user ID. If you have the "Use Email as Identifier" box checked under your configuration, Freshpaint will still create a profile in Klaviyo with another identifier. However, if you send an identify call later with an email, Freshpaint will prioritize that email identifier and the profiles will merge under the email address.

We highly recommend you consistently identify all individuals using only their email address ($email) or phone number ($phone_number), and do not pass $id values. Inconsistent identifiers sent to Klaviyo will result in inflated user profiles being created in Klaviyo. For more information, see Klaviyo's documentation.

If a profile record with the given identifier already exists, Freshpaint will update the existing profile record. If no record with the identifier exists, Freshpaint will create a new user profile.

The following Freshpaint parameters map to Klaviyo's user traits when calling identify:

Freshpaint ParameterKlaviyo User Trait







phone or phoneNumber






Client-side Identify

If you are using client-side connection mode, Freshpaint calls Klaviyo's identify method which calls their Identify API.

Server-side Identify

If you are in server-side connection mode, or if you otherwise have server-side identify calls set up, Freshpaint will create or update a user profile in Klaviyo by calling their Identify API at:


You can see the newly created/updated user profiles under "profiles" in Klaviyo.


When you send events to Klaviyo from Freshpaint in client-side connection mode, Freshpaint creates an event in Klaviyo by calling their front-end Track method, which uses_learnq object to track customers. You can learn more about that here.

When you send events to Klaviyo in server-side connection mode, or send server events to Klaviyo, Freshpaint creates an event in Klaviyo by calling their back-end Track API at:


There are some properties that are required for events to be accepted by Klaviyo. You can view them in the table below.

If you are sending a precision tracking event via Freshpaint's track method, or sending Autotrack events either server-side or client-side, Freshpaint will make sure any required properties are attached to the event.


token (required)


Your public key (six characters long)

event (required)


Name of the event you want to track

customer_properties (required)


Properties of the profile that triggered this event. You must identify the person by their email using a $email key (or if you have SMS-only contacts, by their phone number using a $phone_number key). Other than that, you can include any data you want and it can then be used to create segments of people.

properties (optional)


Properties of this event. Any properties included here can be used for creating segments later. There are also specific properties you can use here, denoted by a $, which map directly to some of Klaviyoโ€™s features. For example, if you track an event called Ordered Product, you can include a property for item type (e.g. image, article, etc.), size, etc.

time (optional)

integer (10 digit unix timestamp)

When this event occurred. By default, Klaviyo assumes events happen when a request is made. If you'd like to track an event that happened in the past, use this property.

You can view events in Klaviyo under the user's profile.

Configuration Options

Connection Mode

Both server-side connection mode and client-side mode are available for this destination. You can read more about the different connection modes here.

Client-side Connection Mode

Events originating from the user's web browser will be sent directly to Klaviyo.

Server-side Connection Mode

All events will be sent to Klaviyo using Freshpaint's servers. Your website will not send data directly to Klaviyo.

Event Transformations

Set up transformations to modify your data before it's sent to your destination. Read more about transformations here.

Event Tester

If you are in server-side connection mode you can use the event tester to test certain payloads to see if they are being sent correctly to Klaviyo. Here is an example of an identify event you might test sending to this destination along with the response code from Klaviyo:

You can read more about the Event Tester here.

Last updated