HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
Guides
ChangelogHelp CenterCommunityContact Us
These docs are for v1-2. Click to read the latest docs for v2024-10-15.

Klaviyo's data model

Learn about Klaviyo's data model, including Metrics, Profiles, and Catalogs/Feeds objects.

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.

Klaviyo Data Model for primary data objects, showing Metrics (Events), Profiles, and Catalogs/Feeds

The table below provides more detail on the structure and supported data types.

Data ObjectDescriptionResources
ProfilesProfiles 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.
MetricsMetrics 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 FeedsCatalogs 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 ObjectDescriptionResources
Lists & SegmentsKlaviyo 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.
CampaignsKlaviyo 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.
TemplatesThe 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 over 2 years ago