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 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 | - |
Questions? Contact us by email or on
Slack