Skip to main content

Fundamentals of building with Klaviyo

Course overview
Lesson
10 min read

Klaviyo's data model overview

Understand why Klaviyo's data model is structurally different from flat or relational platforms, and learn to identify which of the four Klaviyo object types (profiles, events, catalogs, or custom objects) holds a given piece of data.

Meet Maya

Meet Maya. She's a true sneakerhead, and she just found the perfect pair of Eastie's high tops.

She adds them to her cart, gets pulled into a work call, and closes the tab without checking out. And if you're familiar with Klaviyo, you know this is when we send an email or text that says, 'Hey, you forgot something!'

But as a developer for Eastie, you're not thinking about just one cart. You're thinking about thousands of customers like Maya, each with different products, sizes, colors, preferences, and behaviors. Multiply that out, and you're suddenly managing millions of combinations of people, products, and actions.

What makes Klaviyo's data model unique

Klaviyo's data model is designed to give you flexibility without giving up structure.

Here are two common patterns developers may already know:

Click on each card to flip it and reveal the answer.
0 of 2 cards flipped
Type of system
Relational/object-first systems
Pain points

These systems usually require a deeply defined schema up front. They are powerful, but every time you learn something new about Maya, her birthday, loyalty tier, or favorite product category, you may need to rethink where that data lives and how it connects.

Type of system
Flat or tag-based system
Pain points

These systems are fast to start with, but keeping a full picture of Maya gets harder over time. She likes an Eastie post on social media, then browses the site and favorites a few items. A flat system captures each of those separately, and stitching them into one story means flipping between tools instead of looking in one place.

Klaviyo centers the data model around a unified profile, then layers in events, catalog data, and custom objects to capture different kinds of information.

That means you can keep the person at the center, preserve a history of what they did over time, and support more advanced use cases without forcing every implementation into a rigid schema on day one.

What objects make up Klaviyo

Being able to understand when to use each object and what each one is good at will help you build integrations, applications, and personalized experiences beyond what Klaviyo offers out of the box.

Profile (who this person is)

Let’s think about Maya.

Her email address, first name, phone number, preferred language, loyalty tier, or shoe size preference are all examples of data that describe who she is right now.

Profile properties are best for attributes that describe the person and can change over time. If Maya moves from 'Silver' to 'Gold' in a loyalty program, the profile should reflect her current status. The old value is replaced by the new one.

Common profile fields include:

  • Email
  • Phone Number
  • First Name
  • Last Name
  • City
  • Country
  • Timezone

In the API, these default properties use names like first_name and phone_number.

Custom profile properties are yours to define, such as:

  • Preferred Language
  • Account Status
  • Shoe Size

Developer takeaway: use profiles for durable person-level attributes. If the value should always represent the latest known truth about the person, it probably belongs here.

Full reference: Profiles API overview.

User profile dashboard displaying channel consent statuses, custom properties, and an event timeline showing recent marketing subscriptions.

Events (what they did)

The moment Maya adds the shoe to her cart, that's an Event logged on Maya's profile. An event records that something happened at a specific point in time.

Profiles tell you who Maya is. Events tell you what Maya did.

For example:

  • Added to Cart
  • Started Checkout
  • Placed Order
  • Viewed Product

An event usually includes:

  • a metric name that describes the action
  • a timestamp
  • properties that describe the context of that action

So an Added to Cart event might include:

  • product_id
  • variant_id
  • price
  • quantity
  • added_at

Event structure affects much more than ingestion. It affects segmentation, flow logic, reporting, and debugging.

As we go through the certificate, you'll notice that we use 'events' and 'metrics' interchangeably. Here is the distinction: a metric is the event type, like Added to Cart. An event is the individual occurrence, like Maya adding the Eastie high tops to her cart at 2:14 PM.

Developer takeaway: use events for behavior, actions, and anything time-based. If you need history, sequence, or triggers, you are probably in event territory.

Full reference: Events API overview.

User activity timeline for Jemma showing events like Viewed Product, Added to Cart, and Received Email with timestamps from March 2023.

Catalogs (what the store offers)

Now let's look at the sneaker itself.

The sneaker has a title, product image, description, URL, price, and inventory attributes. That data exists whether or not Maya likes (or even sees) the product (sorry Maya, you can't like every shoe).

Catalogs store information about the items or services a business offers. In ecommerce, that may be products, variants, and collections. In other businesses, it may be classes, appointments, locations, menu items, or service offerings.

This is one of the distinctions that matters most in Klaviyo's data model:

  • Profiles and events are tied to a person and their behavior.
  • Catalogs hold reusable data that is not inherently person-specific.

That's why catalog data works well for personalization at scale. The same item can be referenced across many people, messages, and flows without duplicating that information on every profile or event.

Catalog items can be synced through a native integration, a custom catalog feed, or the Catalogs API.

A custom catalog feed syncs price changes, new color variations, and inventory updates into the catalog on a schedule, the same destination as a native integration or the Catalogs API. A few nuances include:

  • Custom catalog feed data has to be one node deep, no nested JSON or XML, unless it's coming through Google Merchant feeds
  • Klaviyo resyncs custom catalog feeds every 6 hours. The Catalogs API updates right away.
  • Custom catalog feed files are capped at 100 MB, with 50 MB or under recommended.

Learn more in Sync a custom catalog feed to Klaviyo.

Developer takeaway: if the data describes something the business offers, not who the person is and not what they did, it likely belongs in a catalog or related reusable data source.

Full reference: Catalog API overview.

Products catalog dashboard showing a tabular list of inventory items with details including item name, status, ID, date added, and last update date.

Custom Objects

Sometimes profile properties, events, and catalogs still are not enough.

Let's say Maya has multiple active reservations at a restaurant, multiple pets on file with a groomer, or multiple subscriptions tied to her account. Each of those records has its own fields, and each one is related to Maya.

That is where custom objects come in.

Custom objects are useful when a person has a one-to-many relationship with something, and each related record needs its own structure.

Examples:

  • reservations
  • appointments
  • pets
  • children
  • subscription plans
  • B2B accounts or locations

What differentiates custom objects from properties? If Maya has 3 children that also love Eastie. Each child has their own name, style, shoe size, and history with the brand. Being able to capture this data as a custom record allows Klaviyo to act upon and store this information.

Developer takeaway: if one profile can be associated with multiple structured records, and each record has its own attributes, a custom object may be the right fit.

Full reference: Custom Objects API overview.

Screenshot of a user profile displaying the Objects tab with details for a Burger Box Subscription, including renewal date, box type, and price.

Web feeds

Some reusable content isn't a product, like Eastie's blog posts, an Instagram feed, or a customer's favorite review. Web feeds let Klaviyo fetch that content and insert it directly into Eastie's messages.

A web feed is a JSON or XML file, hosted at a URL, that Klaviyo checks on a schedule but does not sync into the catalog. Examples can be: a blog post, an Instagram feed, or a podcast. Essentially, anything that is reusable that is not a product can get referenced directly in a template using web feeds, with the syntax feeds.FEED_NAME.

A few nuances:

  • Must be publicly hosted and accessible over HTTPS
  • Web feeds refresh every 15 minutes.
  • Web feeds have a 4 MB limit.

Full reference: How to add a custom web feed in an email.

Products catalog page in Klaviyo dashboard showing an item list and a cursor hovering over the Manage Product Feeds button.
Klaviyo's data model overview