Klaviyo destination

Send your event data from RudderStack to Klaviyo.

Klaviyo is a powerful ecommerce platform that lets you boost your business revenue. It offers unique features like category-based segmentation and various event triggers based on page views, purchases, email engagement, etc.

Find the open source transformer code for this destination in the GitHub repository.

Setup

  1. In your RudderStack dashboard, go to Directory > Destinations > Cloud Destinations and search for Klaviyo.
  2. Connect your source and click Continue.

Connection settings

Configure the following settings to set up Klaviyo as a destination in RudderStack:

  • Name: Assign a name to uniquely identify the destination.
  • Public API Key: Enter the unique public API key from your Klaviyo dashboard (present under Settings > Account).
  • Private API Key: Enter the private API key from your Klaviyo dashboard (present under Settings > Account). This key lets you add users to a list or subscribe them using personalised emails/SMS.

Connection mode

Specify how you want to route events from your source to Klaviyo.

RudderStack supports sending events to Klaviyo via the following connection modes:

Connection modeWebMobileServer
Device modeSupported--
Cloud modeSupportedSupportedSupported
info
In a web device mode integration, that is, using JavaScript SDK as a source, RudderStack loads the Klaviyo native SDK from https://static.klaviyo.com/ domain. Based on your website’s content security policy, you might need to allowlist this domain to load the Klaviyo SDK successfully.

Configuration settings

After completing the initial setup, configure the following settings to correctly receive your data in Klaviyo:

List and subscription settings

  • List Id: Enter the default list ID to which you want to add or subscribe the identified users.
  • Consent: Select the consent type from E-mail, SMS, or both. consent is a Klaviyo-specific property that you need to include in your events if you run a GDPR-compliant business.

Event-specific settings

  • Enable this option to make email as primary identifier: Turn on this setting to set a custom attribute _id and $email as the primary identifier when passed in traits.email/properties.email. RudderStack does not set $id field to the userId while sending the events.

    When disabled, RudderStack uses userId (anonymousId, if userId is absent) for mapping the user with a unique identifier. In case userId and anonymousId are absent, RudderStack sends email or phone as the user’s primary identifier.

    warning

    Note that:

    • This setting is applicable for identify and track calls.
    • Use this setting only if you are experiencing issues with duplicate profiles created in your Klaviyo account.
  • Enable to flatten user/event properties: Turn on this setting to flatten the user properties in identify and event properties in track calls before sending them to Klaviyo.

Web SDK settings

Use the following settings to configure Klaviyo’s native web SDK:

  • Send Page As Track: Turn on this setting to send page events as track events along with the event name and category.
  • Additional Page info: Turn on this setting to send page events as track events and send additional properties for the event.

Other settings

  • Client-side Events Filtering: This setting lets you specify which events should be blocked or allowed to flow through to Klaviyo. See Client-side Events Filtering guide for more information.
  • OneTrust Cookie Categories: This setting lets you associate the OneTrust cookie consent groups to Klaviyo.

Identify

The identify call lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them like their name, email address, etc.

success
You can send any number of key-value pairs as user traits and RudderStack updates them as custom profile properties in Klaviyo.

To create a new user in Klaviyo, you must pass either the userId, email, or phone properties in the identify call. If a user already exists, RudderStack updates the user profile with the latest values.

A sample identify call is shown below:

rudderanalytics.identify("userid", {
  firstName: "Name",
  lastName: "Surname",
  email: "name@website.com",
  phone: "+12 345 678 900",
  userId: "userId",
  title: "Owner",
  organization: "Company",
  city: "Tokyo",
  region: "ABC",
  country: "JP",
  zip: "100-0001",
  Flagged: false,
  Residence: "Shibuya",
  properties: {
    listId: "XUepkK",
    subscribe: true,
    consent: "email",
    smsConsent: true,
  },
})

Note that specifying consent and smsConsent in the event properties overrides the respective settings in the RudderStack dashboard.

Add and subscribe user to list

info
This feature is available only in the cloud mode integration.

You can add and subscribe a user to a Klaviyo list by specifying the List ID in the RudderStack dashboard and setting the subscribe option to true. Alternatively, you can add listId within the event properties - this will override the List ID specified in the dashboard for that particular event.

If you have enabled the Double opt-in setting for a list in Klaviyo, users will not be added to the list automatically without their consent. To add users to a list automatically without waiting for their consent, select the Single opt-in option in that list’s settings:

Destination Settings for Klaviyo

Track

The track call lets you record the user actions along with any properties associated with them.

A sample track call is shown below:

rudderanalytics.track("Checked Out", {
  Clicked_Rush_delivery_Button: true,
  total_value: 2000,
  Ordered: ["T-Shirt", "jacket"],
  revenue: 2000,
})

In the above snippet, RudderStack captures the information related to the Checked Out event, along with the details of the event.

To associate a user with an event, you need to pass either their userId, email, or phone in the track call. A sample server-side track call along with the user information is as shown:

client.track({
  userId: "user2",
  event: "Item Purchased",
  properties: {
    revenue: 97.5,
    products: [
      {
        productId: "pro1",
        price: 32.5,
        quantity: 3,
      },
    ],
  },
  context: {
    traits: {
      email: "user2@gmail.com",
    },
  },
})

In the above snippet, RudderStack captures the information related to the Item Purchased event, along with its additional information in properties. Moreover, since this event is captured using a server-side SDK, RudderStack passes the user information in context along with a unique userId.

info
  • To send track or screen type event using an SDK that does not persist user context information after identify, you need to pass the information in context.traits.
  • To set a specific value to the screen or track type event, you need to pass the event-related property in the properties field. Also, you can send revenue property in the track event and RudderStack will automatically map it to Klaviyo’s special property $value.

Ecommerce event mapping

RudderStack converts the following ecommerce events to the corresponding Klaviyo events:

RudderStack eventKlaviyo event
Product Viewed
Product Clicked
Viewed Product
Product AddedAdded to Cart
Checkout StartedStarted Checkout

In addition to the above, RudderStack sends the following:

  • Customer properties: Must contain either the email or phone_number. RudderStack extracts these customer properties from traits/context.traits in the track call.
info
As mentioned above, you can send any number of key-value pairs as user traits and RudderStack updates them as custom profile properties in Klaviyo.
  • Token: Public API key from the RudderStack dashboard.

Additionally, you can choose to send specific fields for each of the events covered in the following sections:

Product Viewed

RudderStack maps the Product Viewed event to Viewed Product and maps the following event properties:

RudderStack propertyKlaviyo property
nameProductName
product_idProductID
skuSKU
image_urlImageURL
urlURL
brandBrand
pricePrice
compare_at_priceCompareAtPrice
categoriesCategories

Product Added

RudderStack maps the Product Added event to Added to Cart and maps the following event properties:

RudderStack propertyKlaviyo property
value$value
nameAddedItemProductName
product_idAddedItemProductID
skuAddedItemSKU
image_urlAddedItemImageURL
urlAddedItemURL
priceAddedItemPrice
quantityAddedItemQuantity
categoriesAddedItemCategories
item_namesItemNames
checkout_urlCheckoutURL
items (deprecating soon)
products
Items
warning
properties.items will be deprecated soon.

Furthermore, products/items can contain the following parameters:

RudderStack parametersKlaviyo parameters
product_idProductID
skuSKU
nameProductName
quantityQuantity
pricePrice
totalRowTotal
urlURL
image_urlImageURL
categoriesProductCategories

Checkout Started

RudderStack maps the Checkout Started event name to Started Checkout and maps the following event properties:

RudderStack ParametersKlaviyo Parameters
order_id$event_id
value$value
categoriesCategories
item_namesItemNames
items (deprecating soon)
products
Items
checkout_urlCheckoutURL
warning
properties.items will be deprecated soon.

Furthermore, products / items can contain the following parameters:

RudderStack parametersKlaviyo parameters
product_idProductID
skuSKU
nameProductName
quantityQuantity
pricePrice
totalRowTotal
urlURL
image_urlImageURL
categoriesProductCategories

A sample track call containing the above ecommerce event parameters is shown below:

rudderanalytics.track("checkout started ", {
  order_id: "1234",
  value: 12.34,
  categories: ["category1", "category2"],
  checkout_url: "http://www.testcall.com",
  item_names: ["item1", "item2"],
  products: [{
      product_id: "pId1",
      sku: "sku1",
      name: "item1",
      url: "https://www.item1URL.com",
      price: 1.0,
      quantity: 1,
      image_url: "https://www.item1Image.com,
      categories: ["category1", "category2"],
      row_total: 1.0
    },
    {
      product_id: "pId2",
      sku: "sku2",
      name: "item2",
      url: "https://www.item2URL.com",
      price: 2.0,
      quantity: 1,
      image_url: "https://www.item2Image.com,
      categories: ["category1", "category2"],
      row_total: 2.0
    },
  ],
});
warning
When sending events via web device mode, specifying order_id is not mandatory, as Klaviyo automatically assigns the timestamp to the event. However, if explicitly specified, it must be unique. Klaviyo automatically discards the events containing a duplicate order_id.

Page

info
RudderStack supports sending page events to Klaviyo only via device mode.

The page call lets you record your website’s page views with any additional relevant information about the viewed page.

You can send the name and category information in the page event by enabling the Send Page As Track setting in the RudderStack dashboard. To associate the properties with the page view event, enable the Additional Page info setting as well.

A sample page call is shown below:

rudderanalytics.page("Cart", "Cart Viewed", {
  path: "/cart",
  referrer: "test.com",
  search: "term",
  title: "test_item",
  url: "http://test.in",
})

Screen

info
RudderStack supports sending screen events to Klaviyo only via cloud mode.

The screen method lets you record whenever a user sees their mobile screen along with any optional properties about the viewed screen.

A sample screen call is shown below:

[[RSClient sharedInstance] screen:@"Sample Screen Name" properties:@{@"prop_key" : @"prop_value"}];

In Klaviyo, the above screen call is shown as Sample Screen Name along with the associated properties.

Group

info
RudderStack supports adding and subscribing users to a specific list via the group call only in the cloud mode integration.

The group call lets you associate a particular identified user with a group, such as a company, organization, or an account.

To make a group call successfully, you must include either email or phone in it. A sample server-side group call is shown:

client.group({
  userId: "userId",
  groupId: "listId",
  traits: {
    subscribe: true,
  },
  context: {
    traits: {
      email: "user.test@gmail.com",
      city: "city",
      country: "country",
      zip: "213456",
      age: 23,
      plan: "free",
      consent: "email",
      phone: "1-617-555-1333"
    },
  },
})

Note that specifying consent in the event properties overrides the respective settings in the RudderStack dashboard.

In the above snippet, the user with the associated traits is added and subscribed to the list as it is set to true.

Troubleshooting

ErrorReasonSolution
"detail": "Duplicate email found: alex@example.com."The identifiers in the event are possibly from different user profiles in Klaviyo.Make sure that all the identifiers in the event payload belong to the same user profile.

To update a profile, you can provide the user's email, phone, or user ID.
"detail": "A profile already exists with one of these identifiers."

Questions? Contact us by email or on Slack