Use data in Klaviyo

❗️

This guide refers to Klaviyo's v1/v2 legacy APIs.

We are in the process of updating these guides, please check back later! For more information about the differences between legacy and new APIs, check out the comparison chart and [new API overview] (ref:api_overview).

Data objects

When understanding how to use data in Klaviyo, it is helpful to first understand Klaviyo’s data model (i.e., what data Klaviyo collects and how it’s organized). Klaviyo’s three primitive data objects are: Profiles, Metrics, and Catalogs/Data Feeds. Below, you’ll find an explanation of how each one is used in Klaviyo.

How data Is used

Data pushed into Klaviyo (from Profiles, Metrics, and Catalogs / Data Feeds) is primarily used for two reasons:

• Targeting
  Defining who receives a message and when they receive it
• Personalization
  What content is rendered into the message

There are three main ways in Klaviyo to target and personalize:

• Flow triggers
• Segmentation and conditional filters
• Dynamic content in messages

Part of the power of Klaviyo is how these three mechanisms work together and interact. For example, consider an abandoned cart 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. People from the United States receive one email, while people outside the United States receive another email.
• Personalization
  Dynamically insert the person’s name, details about the item added to cart, and details for other recommended products based on purchase history into a message. 

This table illustrates how different data objects are used in flows, segmentation, and messaging:

Getting data into Klaviyo

Once you understand Klaviyo’s data model and how data is used in Klaviyo, you can then learn about how to get data into Klaviyo. There are a variety of ways this can be done, which are outlined below.

Native and 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. To see integrations we natively support, navigate to the Integrations tab. 

Additionally, because our APIs are open, 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. For a full list of third-party integrations, check out our Klaviyo integrations directory. 

APIs

If you want to programmatically push data into Klaviyo, you can utilize our APIs 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 articles on our Track and Identify API that provide a general overview, illustrative use cases, and details on Klaviyo properties. 

We’ve built Klaviyo to make it easy to push data to us and use it. 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 be able to see it 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.
• Simplicity
  Pushing data typically requires interacting with just two endpoints, Track and Identify. We don’t require you to treat any user actions or most profile 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 of your data. We don’t have any data retention limits nor any downstream filters on how you can query data in the UI. You have the ability to access every event, and all associated metadata for every user over all time.

The APIs you are most likely to interact with for the purposes of pushing data into Klaviyo are our Track and Identify APIs, which are used for passing timestamped events and profile properties, 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 as 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.This makes 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 via a CSV file upload. Additionally, any individual profile property or list membership may be edited manually in the app.

Additional resources

• Export data from Klaviyo
• Acceptable date and timestamp formats for profile and event properties
• Sync a custom catalog feed to Klaviyo