Introduction to Klaviyo's Data Model

Last updated at:

Primitive Data Objects

When syncing data into Klaviyo, it helps to have an understanding of the underlying data model. The primitive objects in Klaviyo are: Profiles, Metrics, and Catalogs/Feeds. The table below provides more detail on the structure and supported data types.

Data Object Description

Profiles represent people, typically with email or a specified customer ID as a primary identifier. Profiles can have an unlimited quantity of associated properties and properties can accept a variety of data types, such as dates, integers, floats, booleans, strings, or arrays.

For more, see:
People & Profiles (Help Center articles)
Identify API (API docs for creating or updating Profiles)
Profiles API (API docs for extracting Profile data)


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 "Viewed Course") or server-side (such as "Shipped Product" or "Course Completed") 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.

For more, see:
Klaviyo Web Tracking (Help Center article)
Sample Event Tagging for eCommerce (Help Center article)
Track API (API docs for tracking events)
Metrics API (API docs for exporting event data)

Catalogs / 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

Klaviyo allows you to organize Profiles into groups called Lists. Profiles may optionally be assigned membership of multiple Lists (or no Lists). Profiles may be added to Lists automatically by filling out a form, programmatically via API, or manually by CSV upload.

For more, see:
Klaviyo Lists API (API docs for programmatically interacting with Lists)


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.

For more, see:
Klaviyo Campaigns API (API docs for programmatically interacting with Campaigns)


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.

For more, see:
Klaviyo Templates API (API docs for programmatically interacting with Templates)
Django tags & templating (Docs on how to use Django in email templates)

Additional resources

For more on how to import this type of data into Klaviyo see our article on Getting Data into Klaviyo. To learn how this data can be used in Klaviyo see Using Data in Klaviyo.

Was this article helpful?
19 out of 30 found this helpful