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:
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.
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.
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.
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:
- 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.
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.
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.
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.
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.