Klaviyo Cloud Mode Integration (New API)

Send events to Klaviyo via RudderStack cloud mode using the new API (v2024-06-15).

After you have successfully instrumented Klaviyo as a destination in RudderStack, follow this guide to correctly send your events to Klaviyo in cloud mode using the new API (v2024-06-15).

Identify

The identify call lets you create or update a profile in Klaviyo.

A sample identify call is shown below:

rudderanalytics.identify("1hKOmRA4el9Z", {
  firstName: "Alex",
  lastName: "Keener",
  email: "alex@example.com",
  title: "Owner",
  organization: "Company",
  zip: "100-0001",
  flagged: false,
  properties: {
    listId: "XUepkK",
    subscribe: true,
    consent: ["email"],
  },
})

Note that specifying consent in the event properties overrides the Consent setting specified in the RudderStack dashboard.

Subscribe/Unsubscribe users

To subscribe a user, you can set the traits.properties.subscribe flag to true. RudderStack uses the Subscribe Profiles API to subscribe users to the listId passed in the event (traits.properties.listId) or the RudderStack dashboard.

To unsubscribe a user, you can set the traits.properties.subscribe flag to false. RudderStack uses the Unsubscribe Profiles API for unsubscribing. Either of the user’s email or phone_number fields are required, depending on their subscription.

Note that Klaviyo doesn’t support specifying the Klaviyo profile ID to unsubscribe a user. Also, it removes all the relative consents.

Property mappings

The following table lists the mappings between RudderStack and Klaviyo properties:

RudderStack propertyKlaviyo propertyNote
externalId.klaviyo-profileIddata.id (generated via Klaviyo)Alphanumeric string
-data.typeConstant value: profile
Refer attributes
Required
data.attributesData type: Object

Attributes

RudderStack propertyKlaviyo propertyNote
context.traits.email
traits.email
emailEmail format
context.traits.phone
traits.phone
phone_numberPhone format
userId
context.traits.userId
traits.userId
external_idData type: String
anonymousIdanonymous_idData type: String
traits.firstName
traits.firstname
traits.first_name
context.traits.firstName
context.traits.firstname
context.traits.first_name
first_nameData type: String
traits.lastName
traits.lastname
traits.last_name
context.traits.lastName
context.traits.lastname
context.traits.last_name
last_nameData type: String
context.traits.title
traits.title
titleIndividual’s job title

Data type: String
context.traits.Organisation
traits.Organisation
OrganisationData type: String
context.traits.image
traits.image
imageURL format
context.traits._kx
traits._kx
_kxAlso known as the exchange_id, this is an encrypted identifier used for identifying a profile by Klaviyo’s web tracking.
locationlocationData type: Object
info
RudderStack maps the rest of the custom event traits of string data type to Klaviyo’s properties field in a key-value format (object data type).

Location

RudderStack propertyKlaviyo propertyNote
traits.street
traits.address.street
context.traits.street
context.traits.address.street
properties.street
address1Data type: String
context.traits.address.city
traits.address.city
cityData type: String
context.traits.address.country
traits.address.country
countryData type: String
context.traits.address.region
traits.address.region
regionData type: String
traits.zip
traits.postalcode
traits.postalCode
traits.address.zip
traits.address.postalcode
traits.address.postalCode
context.traits.zip
context.traits.postalcode
context.traits.postalCode
context.traits.address.zip
context.traits.address.postalcode
context.traits.address.postalCode
properties.zip
properties.postalcode
properties.postalCode
zipData type: String
context.traits.address.timezone
traits.address.timezone
timezoneData type: String

RudderStack recommends using time zones from the IANA time zone database.
context.ipipData type: String
context.address.longitude
context.location.longitude
longitudeData type: String
context.address.latitude
context.location.latitude
latitudeData type: String

Track

warning
This destination does not strictly adhere to the RudderStack Ecommerce Event Spec.

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,
})

Property mappings

The following table lists the mappings between RudderStack and Klaviyo properties:

RudderStack propertyKlaviyo propertyNote
-data.typeConstant value: event
attributes
Required
data.attributes-

Attributes

RudderStack propertyKlaviyo propertyNote
identify property mappings
Required
profileThe profile object is common between the identify and track calls.
-metric.data.typeConstant value: metric
event
Required
metric.data.attributes.nameData type: String
propertiespropertiesExcluding these fields:

email, phone, revenue, total, value, value_currency, and currency
timestamp
originalTimestamp
time-
properties.revenue
properties.total
properties.value
valueData type: String / Integer
properties.currencyvalue_currencyData type: String

Note that:

  • A user profile and metric objects should include at least one profile identifier (for example, idemail, or phone_number) and the metric name.
  • Klaviyo does not support any ecommerce event in particular. Hence, RudderStack no longer supports the ecommerce events as the payload schema is same for all the events.

Group

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, userId or phone in it. A sample group call is shown:

client.group({
  userId: "1hKOmRA4el9Z",
  groupId: "1112311",
  traits: {
    subscribe: true,
  },
  context: {
    traits: {
      email: "alex@example.com",
      city: "New Orleans",
      country: "Louisiana",
      zip: "213456",
      age: 23,
      plan: "free",
      consent: ["email"],
      phone: "1-617-555-1333"
    },
  },
})

In the above snippet, the user with the associated traits is added and subscribed to the list as it is set to true. Note that specifying consent in the event properties overrides the Consent setting specified in the RudderStack dashboard.

Property mappings

The following table lists the mappings between RudderStack and Klaviyo properties:

RudderStack propertyKlaviyo propertyNote
-data.typeConstant value: profile-subscription-bulk-create-job
attributes
Required
data.attributesData type: Object
relationships
Required
data.relationshipsData type: Object

Attributes

RudderStack propertyKlaviyo propertyNote
traits.custom_sourcecustom_sourceData type: String
profile data
Required
profiles.data[0]-

Profile data

RudderStack propertyKlaviyo propertyNote
-typeConstant value: profile
externalId.klaviyo_idid-
emailattributes.emailEmail format
phone numberattributes.phone_numberPhone format
context.traits.consent array including email or sms valuessubscriptions.email.marketing.consentemail or sms values required for the marketing consent.

Relationships

RudderStack propertyKlaviyo propertyNote
-list.data.typeConstant value: list
groupId
Required
list.data.id-

Questions? Contact us by email or on Slack