> For the complete documentation index, see [llms.txt](https://rudderlabs.gitbook.io/rudderlabs-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rudderlabs.gitbook.io/rudderlabs-1/docs/destinations/marketing/klaviyo.md).

# Klaviyo

Step-by-step guide to send your event data from RudderStack to Klaviyo.

[**Klaviyo**](https://www.klaviyo.com/) is a powerful eCommerce platform that lets you boost your business revenue. It supports unique features such as category-based segmentation and various event triggers based on page views, purchases, email engagement, etc. You can easily track and measure all your user activity and the resulting revenue and get a breakdown of this revenue based on different custom attributes.

Klaviyo also offers features such as trend reports, cohort analysis, and various options for boosting customer engagement, such as personalized newsletters, product recommendations, in-app push notifications, and more.

RudderStack supports Klaviyo as a destination to which you can seamlessly send your event data.

**Find the open-source transformer code for this destination in our** [**GitHub repo**](https://github.com/rudderlabs/rudder-transformer/tree/master/v0/destinations/klaviyo).

## Getting started

Before configuring Klaviyo as a destination in RudderStack, verify if the source platform is supported by Klaviyo by referring to the table below:

| **Connection Mode** | **Web**       | **Mobile**    | **Server**    |
| ------------------- | ------------- | ------------- | ------------- |
| **Device mode**     | **Supported** | -             | -             |
| **Cloud mode**      | **Supported** | **Supported** | **Supported** |

To know more about the difference between cloud mode and device mode in RudderStack, refer to the [RudderStack Connection Modes](https://rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/) guide.

Once you have confirmed that the source platform supports sending events to Klaviyo, follow these steps:

* From your [**RudderStack dashboard**](https://app.rudderstack.com/), add the source. Then, from the list of destinations, select **Klaviyo**.

![Klaviyo connection settings](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-6e3d393dd1df31c126f9b8b901d938d43adfe185%2Fklaviyo-connection-settings.png?alt=media)

## Connection settings

To successfully configure Klaviyo as a destination, you will need to configure the following settings:

* **Public API Key**: Your Public API Key is the unique key generated against your Klaviyo account. It can be found in your Klaviyo dashboard in the **Account** section under **Settings**.
* **Private API Key**: Your Private API key can be generated for your account in the **Account** section under **Settings**. This key allows you to add users to a list or subscribe them using personalised emails/SMS.
* **Enforce Email as Primary Identifier**: If this option is enabled, RudderStack will never set `$id` field to your `userId` when you send the events. Instead, RudderStack will only set a custom attribute `_id` and `$email` as the primary identifier with your `traits.email` or `properties.email`.

This setting should be enabled only if you are experiencing any issues with duplicate profiles created in your Klaviyo account.

* **List Id**: Enter your default list ID to which you want to add or subscribe your identified users.
* **Consent**: If you are a GDPR-compliant business, you will need to include `consent` in your API call.

`consent` is a Klaviyo-specific property and only accepts these values: `email`, `web`, `sms`, `directmail`, and `mobile`.

* **SMS Consent**: If you are updating the consent for a phone number, or would like to send an opt-in SMS to the profile (for double opt-in lists), then enable this option. Alternatively, you can also include an `smsConsent` key in the properties with a value of `true` or `false`.
* **Send Page As Track**: Enable this option if you wish send `page` events as `track` events along with the event `name` and `category`.
* **Additional Page info**: If you are sending `page` events as `track` events, you can also choose to send in additional properties for the event by enabling this field.
* **Use Native SDK to send Events**: Enable this option if you want to send events using the web device mode.

In case `userId` is absent, RudderStack uses `anonymousId` for mapping the user with an unique identifier. In case both `userId` and `anonymousId` are absent, then `email` or `phone` will be considered as the user's primary identifier.

## Page

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** while setting up the Klaviyo destination in RudderStack. To associate the properties with the page view event, enable the `Additional Page info` setting.

A sample `page` call is shown below:

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

The `page` calls are only supported in the RudderStack device mode. For more information on the RudderStack device mode, refer to the [RudderStack Connection Modes](https://rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/) guide.

## Screen

The `screen` method lets you record whenever the user views their mobile screen, with any additional relevant information about the screen.

The `screen`call is the mobile equivalent of the `page` call.

A sample `screen` call is shown below:

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

In the above snippet, RudderStack captures all the information related to the viewed screen along with any additional information associated with the event. In the destination, the above `screen` call will be shown as `Sample Screen Name:` along with the properties.

The `screen` calls are only supported in the RudderStack cloud mode. To know more about the RudderStack cloud mode, refer to the [RudderStack Connection Modes](https://rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/) guide.

## Track

The `track` call allows you to capture user actions along with the properties associated with these actions.

Each user action is called as an **event**.

The user has to be associated with an event either via their `userId`, `email`, or `phone`.

A sample `track` call is shown below:

```javascript
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.

A sample server-side `track` call along with the user information is as shown:

```javascript
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 any additional info about that event in `properties` - in this case the `revenue`, along with product information. Moreover since this event is captured using a server-side SDK, RudderStack passes the user information in `context`, along with a unique `userId`.

* 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`.

### E-Commerce event name mapping

E-Commerce event name mapping is supported for both RudderStack cloud mode and web device mode.

RudderStack converts the following E-Commerce event names to the corresponding Klaviyo event names, before sending the events to Klaviyo:

| **RudderStack Event Name**         | **Klaviyo Event Name** |
| ---------------------------------- | ---------------------- |
| `product viewed`/`product clicked` | `Viewed Product`       |
| `product added`                    | `Added to Cart`        |
| `checkout started`                 | `Started Checkout`     |

In addition, RudderStack also sends the associated customer properties and the token.

The token refers to the Public API key used to configure Klaviyo as a destination in RudderStack. **This is a mandatory field**.

RudderStack extracts the customer properties from `traits`/`context.traits`. Refer to the sample `track` call in the [Track](https://rudderstack.com/docs/destinations/marketing/klaviyo/#track) section above for more information on passing the properties within `traits`/`context.traits`.

The customer properties must contain atleast one of `email` or `phone_number`.

In addition to the above-mentioned properties, you can also **optionally** send specific fields for each of the events covered in the following sections.

#### Product Viewed

As mentioned in the table above, RudderStack converts the `Product Viewed` event name to `Viewed Product`. The event properties are also mapped to the Klaviyo properties, as shown:

| **RudderStack Property** | **Klaviyo Property** |
| ------------------------ | -------------------- |
| `name`                   | `ProductName`        |
| `product_id`             | `ProductID`          |
| `sku`                    | `SKU`                |
| `image_url`              | `ImageURL`           |
| `url`                    | `URL`                |
| `brand`                  | `Brand`              |
| `price`                  | `Price`              |
| `compare_at_price`       | `CompareAtPrice`     |
| `categories`             | `Categories`         |

#### Product Added

As mentioned previously, RudderStack converts the `Product Added` event name to `Added to Cart`. The event properties are also mapped to the Klaviyo properties, as shown:

| **RudderStack Property** | **Klaviyo Property**   |
| ------------------------ | ---------------------- |
| `value`                  | `$value`               |
| `name`                   | `AddedItemProductName` |
| `product_id`             | `AddedItemProductID`   |
| `sku`                    | `AddedItemSKU`         |
| `image_url`              | `AddedItemImageURL`    |
| `url`                    | `AddedItemURL`         |
| `price`                  | `AddedItemPrice`       |
| `quantity`               | `AddedItemQuantity`    |
| `categories`             | `AddedItemCategories`  |
| `item_names`             | `ItemNames`            |
| `checkout_url`           | `CheckoutURL`          |
| `items`                  | `Items`                |

Furthermore, `items` can contain the following parameters:

| **RudderStack Parameters** | **Klaviyo Parameters** |
| -------------------------- | ---------------------- |
| `product_id`               | `ProductID`            |
| `sku`                      | `SKU`                  |
| `name`                     | `ProductName`          |
| `quantity`                 | `Quantity`             |
| `price`                    | `Price`                |
| `total`                    | `RowTotal`             |
| `url`                      | `URL`                  |
| `image_url`                | `ImageURL`             |
| `categories`               | `ProductCategories`    |

#### Checkout Started

As mentioned previously, RudderStack converts the `Checkout Started` event name to `Started Checkout`. The event properties are also mapped to the Klaviyo properties, as shown:

| **RudderStack Parameters** | **Klaviyo Parameters** |
| -------------------------- | ---------------------- |
| `order_id`                 | `$event_id`            |
| `value`                    | `$value`               |
| `categories`               | `Categories`           |
| `item_names`               | `ItemNames`            |
| `items`                    | `Items`                |
| `checkout_url`             | `CheckoutURL`          |

Furthermore, `items` can contain the following parameters:

| **RudderStack Parameters** | **Klaviyo Parameters** |
| -------------------------- | ---------------------- |
| `product_id`               | `ProductID`            |
| `sku`                      | `SKU`                  |
| `name`                     | `ProductName`          |
| `quantity`                 | `Quantity`             |
| `price`                    | `Price`                |
| `total`                    | `RowTotal`             |
| `url`                      | `URL`                  |
| `image_url`                | `ImageURL`             |
| `categories`               | `ProductCategories`    |

A sample `track` call containing the above e-Commerce event parameters is shown below:

```javascript
rudderanalytics.track("checkout started ", {
  order_id: "1234",
  value: 12.34,
  categories: ["category1", "category2"],
  checkout_url: "http://www.testcall.com",
  item_names: ["item1", "item2"],
  items: [{
      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
    },
  ],
});
```

When sending events via the 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 with a duplicate `order_id`.

## 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.

A sample `identify` call is shown below:

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

In the above snippet, RudderStack captures the user-related information like the `email`, `phone`, as well as the associated traits of the user.

To map a user in Klaviyo, you need either the `userId`, `email`, or `phone`. If a user already exists, the new values will be updated for that user.

### Adding a user to a list

Adding or subscribing users to a specific list is only available in cloud mode integration. To know more about the RudderStack cloud mode, read the [RudderStack connection modes](https://rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/) guide.

You can add a user to a Klaviyo list if the **List ID** is specified in the RudderStack dashboard. Alternatively, you can add `listId` within the event `properties`.

Doing so will override the **List ID** specified in the dashboard for that particular event. Similarly, specifying `consent` and `smsConsent` in the event properties will override the respective settings specified in the RudderStack dashboard for the specific event.

You can also subscribe the user to a list by setting `subscribe` option to `true`.

## Group

Adding or subscribing users to a specific list via the `group` event is only available in cloud mode integration. To know more about the RudderStack cloud mode, read the [RudderStack connection modes](https://rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/) guide.

The `group` call lets you link an identified user with a group, such as a company, organization, or an account. It also lets you record any custom traits associated with that group, such as the name of the company, the number of employees, etc.

A sample server-side `group` call looks like the following:

```javascript
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",
      smsConsent: true,
    },
  },
})
```

In the above snippet, the user with the associated traits is added to list, and also subscribed using the `subscribe` flag.

Apart from `userId`, `email`, or `phone`, the other fields are not mandatory.

Adding `consent` and `smsConsent` property in the user traits will override the settings specified in the RudderStack dashboard for the specific event.

## Contact us

For queries on any of the sections covered in this guide, you can [**contact us**](mailto:%20docs@rudderstack.com) or start a conversation in our [**Slack**](https://rudderstack.com/join-rudderstack-slack-community) community.