Klaviyo Cloud Mode (New API)

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

4 minute read

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 property	Klaviyo property	Note
`externalId.klaviyo-profileId`	`data.id` (generated via Klaviyo)	Alphanumeric string
-	data.type	Constant value: `profile`
Refer `attributes` Required	`data.attributes`	Data type: Object

Attributes

RudderStack property	Klaviyo property	Note
`context.traits.email` `traits.email`	`email`	Email format
`context.traits.phone` `traits.phone`	`phone_number`	Phone format
`userId` `context.traits.userId` `traits.userId`	`external_id`	Data type: String
`anonymousId`	`anonymous_id`	Data type: String
`traits.firstName` `traits.firstname` `traits.first_name` `context.traits.firstName` `context.traits.firstname` `context.traits.first_name`	`first_name`	Data type: String
`traits.lastName` `traits.lastname` `traits.last_name` `context.traits.lastName` `context.traits.lastname` `context.traits.last_name`	`last_name`	Data type: String
`context.traits.title` `traits.title`	`title`	Individual’s job title Data type: String
`context.traits.Organisation` `traits.Organisation`	`Organisation`	Data type: String
`context.traits.image` `traits.image`	`image`	URL format
`context.traits._kx` `traits._kx`	`_kx`	Also known as the `exchange_id`, this is an encrypted identifier used for identifying a profile by Klaviyo’s web tracking.
`location`	`location`	Data type: Object

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 property	Klaviyo property	Note
`traits.street` `traits.address.street` `context.traits.street` `context.traits.address.street` `properties.street`	`address1`	Data type: String
`context.traits.address.city` `traits.address.city`	`city`	Data type: String
`context.traits.address.country` `traits.address.country`	`country`	Data type: String
`context.traits.address.region` `traits.address.region`	`region`	Data 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`	`zip`	Data type: String
`context.traits.address.timezone` `traits.address.timezone`	`timezone`	Data type: String RudderStack recommends using time zones from the IANA time zone database.
`context.ip`	`ip`	Data type: String
`context.address.longitude` `context.location.longitude`	`longitude`	Data type: String
`context.address.latitude` `context.location.latitude`	`latitude`	Data type: String

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

Property mappings

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

RudderStack property	Klaviyo property	Note
-	`data.type`	Constant value: `event`
`attributes` Required	`data.attributes`	-

Attributes

RudderStack property	Klaviyo property	Note
`identify` property mappings Required	`profile`	The `profile` object is common between the `identify` and `track` calls.
-	`metric.data.type`	Constant value: `metric`
`event` Required	`metric.data.attributes.name`	Data type: String
`properties`	`properties`	Excluding these fields: `email`, `phone`, `revenue`, `total`, `value`, `value_currency`, and `currency`
`timestamp` `originalTimestamp`	`time`	-
`properties.revenue` `properties.total` `properties.value`	`value`	Data type: String / Integer
`properties.currency`	`value_currency`	Data type: String

Note that:

A user profile and metric objects should include at least one profile identifier (for example, id, email, 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 property	Klaviyo property	Note
-	`data.type`	Constant value: `profile-subscription-bulk-create-job`
`attributes` Required	`data.attributes`	Data type: Object
`relationships` Required	`data.relationships`	Data type: Object

Attributes

RudderStack property	Klaviyo property	Note
`traits.custom_source`	`custom_source`	Data type: String
`profile data` Required	`profiles.data[0]`	-

Profile data

RudderStack property	Klaviyo property	Note
-	`type`	Constant value: `profile`
`externalId.klaviyo_id`	`id`	-
`email`	`attributes.email`	Email format
`phone number`	`attributes.phone_number`	Phone format
`context.traits.consent` array including `email` or `sms` values	`subscriptions.email.marketing.consent`	`email` or `sms` values required for the marketing consent.

Relationships

RudderStack property	Klaviyo property	Note
-	`list.data.type`	Constant value: `list`
`groupId` Required	`list.data.id`	-

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Questions? Contact us by email or on Slack