Klaviyo's data model
Learn about Klaviyo's data model, including Metrics, Profiles, and Catalogs/Feeds objects.
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).
Primary data objects
Info
Klaviyo considers the following objects to be primary data types, since Klaviyo natively handles these forms of data and that these are the required data to integrate with a customer.
When syncing data into Klaviyo, it helps to have an understanding of the underlying data model. The primitive objects in Klaviyo are:
- Metrics
- Profiles
- Catalogs/Feeds
Klaviyo’s track and identify APIs feed directly into the Metrics and Profiles objects, respectively. Any JSON or XML feed you currently have can be fed directly into the Catalogs/Feeds object.
The table below provides more detail on the structure and supported data types.
| Data Object | Description | Resources |
|---|---|---|
| Profiles | Profiles represent people, using either an email ($email) or a specified customer ID ($id) as a primary identifier. There are no practical limitations on the quantity of profile properties, and they can accept a variety of data types, such as dates, integers, floats, booleans, strings, or arrays. |
|
| Metrics | Metrics are the actions or events undertaken by people with Profiles. Metrics are represented as timestamped records with JSON-formatted payloads. This means a Metric may contain an unlimited quantity of attribute-value pairs and arrays, optionally including a nesting structure. The Metric object is extremely versatile, since it can be used to record any type of timestamped action whether originating client-side (such as "Viewed Product" or "Added to Cart") or server-side (such as "Shipped Product") and can include any associated information. In other words, we do not require that you treat any actions specially (such as a purchase). If it is a timestamped action, it is represented as a Metric in Klaviyo. |
|
| Catalogs and Feeds | Catalogs are used to represent products (or product-like records, such as courses or physical stores) that will then be referenced in email templates. Catalog items may be synced automatically via a native integration or may be synced to Klaviyo via a web feed. That is, the catalog should be formatted into an XML or JSON feed and posted to a URL that can be configured in Klaviyo. Klaviyo will ingest the catalog periodically and will process any changes periodically. |
|
Other data objects
As you’ll see in our API documentation, Klaviyo does have other supported data objects such as Lists and Campaigns but for the most part, these data objects are created organically via normal use of the Klaviyo app. It is also possible to interact with these objects programmatically via API.
| Data Object | Description | Resources |
|---|---|---|
| Lists & Segments | Klaviyo allows you to organize Profiles into groups called Lists and Segments. Profiles may optionally be assigned membership of multiple Lists (or no Lists) and may be added to Lists automatically by filling out a form, programmatically via API, or manually by CSV upload. Profiles will also be programmatically added or removed from Segments as they meet or fail to meet the Segment criteria. |
|
| Campaigns | Klaviyo allows you to create and execute messaging Campaigns that are sent to a target audience defined as a List. Campaigns are usually created in the UI but it is also possible to programmatically interact with Campaigns via API. |
|
| Templates | The content and design of a messaging Campaign are stored in a Template. Templates can contain HTML, CSS, and dynamic tags or logic that use Django syntax. |
|
Updated almost 2 years ago