Using Data in Klaviyo

read
Last updated at:

Data Objects

Generally, when thinking about using data in Klaviyo, it helps to first understand Klaviyo’s data model, i.e., what data Klaviyo collects and how it is organized. For more on this topic you can review our Data Model. For present purposes, recall that Klaviyo’s three primitive data objects are:  Profiles, Metrics, and Catalogs/Data Feeds. Below we will explain how these are used in Klaviyo.

How Data is Used

The data that is pushed into Klaviyo - i.e. data from Profiles, Metrics, and Catalogs / Data Feeds - is primarily used for two reasons:  targeting (defining who receives a message and when they receive it) and personalization (what content is rendered into the message). There are three main mechanisms in Klaviyo to enable this:

  1. Flow triggers
  2. Segmentation and conditional filters
  3. Dynamic content in messages

Part of the power of Klaviyo is how these three mechanisms can work together and interact. For example, consider a “Cart Abandonment” flow. Suppose that we want to target and personalize by applying the following logic:

  • Targeting:  Send an email one hour after someone adds an item into their cart, but only if that user has not completed a purchase since adding that item. Send people from the United States one email and people outside the United States another email.
  • Personalization:  Dynamically insert the person’s name, details about the item added to cart, and details for other recommended products based on individualized purchase histories. 

This table illustrates how different data objects would be used to enable this.

Illustrative examples of data usage

  Profiles Metrics Catalogs / Data Feeds
Flow Triggers "Birthday Flow" triggered on "Birthday" property Define trigger as Added to Cart event  
Segmentation & conditional filters Configure flow split Where 'Country' equals 'United States' Define flow filter to include anyone who Has not 'Placed Order' since starting this flow  
Dynamic content in messages Configure template to reference
{{ person.first_name }}
Configure template to reference data from the Added to Cart event, such as
{{ event.line_items.product_name }}
Configure template to include a Klaviyo product block which renders recommended products from catalog

Getting Data into Klaviyo

Generally, when thinking about pushing data into Klaviyo, it helps to first understand Klaviyo’s data model, i.e. what data Klaviyo collects and how it is organized. For more on this topic see our Data Model

Native & Third-Party Integrations

Klaviyo has more than 50 pre-built native integrations. In many cases, you’ll be able to synchronize your data into Klaviyo simply by enabling one of these integrations in Klaviyo. To see integrations we natively support, navigate to the Integrations page in the Klaviyo app. 

Additionally, because Klaviyo has open APIs, some third-parties have productized integrations into Klaviyo which they support. These can be enabled by creating an API key in Klaviyo and following the configuration instructions from the third party. An illustrative example is Segment.com.

APIs

If you want to programmatically push data into Klaviyo, we have APIs that can be used to create, read, update or delete records for most of the objects in our data model. The specific endpoints, supported request formats, and example responses are detailed in our API documentation. Additionally, we have an API Reference Guide that provides a general overview, illustrative use cases, and details on Klaviyo properties. 

We’ve architected Klaviyo to make it easy to push data to us and use that data with ease and without limitation. For example, here are some of the key usability principles we design for:

  • No pre-configuration:  We store data in a highly-denormalized manner, which means there’s no need to pre-configure your data schema in the UI or otherwise. Just send data to our APIs and you’ll see and use it in the app in real-time.
  • Flexibility:  We don’t limit the total quantity of unique events, aggregate events, or event properties. We allow you to pass complex data structures, such as JSON payloads including nested arrays of any data type. We don’t have any practical limitations on payload size.
  • Simplicity:  Pushing data typically requires interacting with just two endpoints, Track and Identify; we don’t require you to treat different any user actions or most properties in special ways. Additionally, Klaviyo will automatically understand data types such as numbers, dates, booleans, or text without you having to specify it.
  • No surprise limitations: You have complete control over, and access to, all your data. We don’t have any data retention limits nor any downstream filters on how you can query data in the UI. You will have the ability to access every event and all associated metadata for every user over all time.

As noted above, the APIs you are most likely to interact with for the purposes of pushing data into Klaviyo are our Identify and Track APIs. These are used for passing profile properties and timestamped events, respectively. As noted in our API documentation, these particular endpoints are optimized for low latency and high numbers of requests, so they don’t adhere to the same REST principles our other APIs. Klaviyo's Track and Identify APIs have a recommended limit of 350 requests per second - since our rate-limits are elastic, we do not publish a hard-limit. For our REST APIs (all APIs that are not Track or Identify) we provide a timestamp for when the next request will be accepted in rate-limit API responses to make it easy to efficiently retry if you do hit a limit.

Other Ways to Upload Data

Klaviyo also supports uploading Profiles into a List as well as uploading historical Metric data through our UI via CSVs. Additionally, any individual Profile property or List membership may be edited manually in the app.

Getting Data Out of Klaviyo

Generally, when thinking about exporting data from Klaviyo data and syncing into another system, it helps to first understand Klaviyo’s data model, i.e., what data Klaviyo collects and how it is organized. For more on this topic see our Data Model.

The most commonly requested data object to export from Klaviyo are Metrics. Metrics are actions that are represented as timestamped records that include JSON-formatted payloads. They may contain an unlimited quantity of attribute-value pairs, optionally including arrays. Klaviyo automatically records Metrics for email, push, or SMS-related events such as “Received Email," “Opened Email," “Clicked Email," and more. Additional illustrative objects that may be exported include Profiles, Lists, and Unsubscribes.

How to Export Data

Klaviyo exposes data for export through several REST APIs associated with these data objects. Developers can use these to extract information, optionally using parameters to refine the information returned. As an example, a simple curl request to retrieve a list of each unique metric observed in the account via the Klaviyo Metrics API would look like this:

curl https://a.klaviyo.com/api/v1/metrics -G \
  -d api_key=api_key

The GET call returns a JSON object with all the fields of the specified dataset as a reply. In this illustrative example, the account has two unique metrics. The resulting JSON might look like:

{
  "end": 2,
  "object": "$list",
  "page_size": 50,
  "start": 0,
  "total": 3,
  "data": [
    {
      "updated": "2019-02-05 17:31:37",
      "name": "Active on Site",
      "created": "2019-02-05 17:31:37",
      "object": "metric",
      "id": "H7wi5R",
      "integration": {
        "category": "API",
        "object": "integration",
        "id": "7FtS4J",
        "name": "API"
      }
    },
    {
      "updated": "2019-02-05 17:31:37",
      "name": "Viewed Product",
      "created": "2019-02-05 17:31:37",
      "object": "metric",
      "id": "JgV8XH",
      "integration": {
        "category": "API",
        "object": "integration",
        "id": "7FtS4J",
        "name": "API"
      }
    },
    {
      "updated": "2019-10-01 02:57:11",
      "name": "Received Email",
      "created": "2019-10-01 02:57:11",
      "object": "metric",
      "id": "QhG7U2",
      "integration": {
        "category": "Internal",
        "object": "integration",
        "id": "0rG4eQ",
        "name": "Klaviyo"
      }
    }
  ]
}

Integrating Klaviyo with a Data Warehouse

Given this background, the general process of integrating Klaviyo with a data warehouse or internal system is as follows:

Step Description
Specify data to extract

Document the data objects and any filtering criteria that you want to apply when extracting data from Klaviyo. For example, if you are interested in syncing Klaviyo-originated metrics into another system, you could reflect this as follows:

Data objects: Metrics
Filtering criteria: All Metrics where “integration.name” equals “Klaviyo”

Test and validate API requests

After documenting the data that should be extracted, we recommend identifying the Klaviyo API endpoints that return the desired data and using Klaviyo’s sample API requests to fetch and validate the data, then define the logical steps to automate this. Using the example above, it might look like this:

Step 1: GET request to https://a.klaviyo.com/api/v1/metrics in order to get a list of all unique metrics.
Step 2: GET request to https://a.klaviyo.com/api/v1/metric/{metric_id}/export for each metric_id of interest

Map source data to destination Once you know the data that you want to extract and how to extract it, you must map Klaviyo’s data structure into your data warehouse or other business system. Klaviyo’s APIs return JSON formatted data, so if your warehouse or other business system requires another format, you may need to manipulate the output to conform to the expectations of the destination.
Build ETL (or use a pre-built connector)

Once you have specs for extracting data and mapping it to your target destination, the next step is to author the code that will automate the extract, transfer, and load (ETL) logic. You may benefit from using an open-source tool such as a Singer tap to achieve this.

If you prefer to avoid this step, you may opt for a tool with which Klaviyo has a pre-built integration such as Segment.com, Stitch Data, or Fivetran.

Perform QA Finally, having automated the ETL, you will want to validate that the data flows through as expected. 
x
Was this article helpful?
14 out of 32 found this helpful