Take Klaviyo to the next level
Klaviyo is a powerful tool, and it becomes even more powerful when you integrate Klaviyo with other services. Klaviyo has several native integrations, like Shopify, which allow you to connect the two services with just a few clicks.
When no native integration exists, Klaviyo's APIs can be used to pass information back and forth between Klaviyo and any other service. Klaviyo's APIs can also be used to build on top of Klaviyo and customize data, reporting, and anything else in your Klaviyo account.
Understanding Klaviyo's data model and how to map your data properly to achieve your goals can be helpful in order to properly set up any custom integrations or logic.
The 3 main objects in Klaviyo's data model
Klaviyo's data model is based on 3 main objects: profiles, events, and catalog items. Flip through the tabs below to learn more about these 3 objects.
Profiles
Profiles represent people. Each customer in your Klaviyo account has a unique profile.
Within a profile, you can see a snapshot of the individual in the form of profile properties, actions that individual has taken, and other key details on how this profile was added into Klaviyo.
Profile properties are stored on the profile level and represent information about each person. Some properties, like location, are automatically set when Klaviyo identifies the individual via JavaScript. You also have the option to add custom profile properties, which can be anything, like a customer's favorite coffee or birthday. Custom profile properties can be added manually, via CSV upload, or via API.
Events
Events represent things that happen. These can be instigated by the customer, like Opened Email or Placed Order, or they can occur on the back end (e.g., Order Shipped).
Each event is associated with a specific profile. Events can represent actions that an individual has taken (such as Placed Order or Opened Email), or they can represent updates that affect an individual (such as Order Shipped or Bounced Email). When naming custom events, use a past tense verb followed by a noun. For instance, if you are creating an event that fires whenever a customer uses a coupon, use the format Used Coupon.
You can include event data, as long as it's valid JSON, to track more details about the event action.
In Klaviyo, events are individual occurrences of an action taken by an individual whereas metrics are the groupings of that action. For example, there are individual Placed Order events that, as a whole, make up the Placed Order metric. Read more about metrics and events.
Catalog items
Within the Klaviyo catalog, you can include all of the items your brand manages. Catalog items can be physical items (like a T-shirt), digital items (like an eBook download) or even virtual offerings (like a guided tour). Each catalog item is required to have an ID, title, description, image, and corresponding product URL.
Optionally, you may want to have associated variants (like different sizes or colors of the same T-shirt). While not required, you can also include fields like categories for feed creation and filtering, as well as any other custom fields that might be relevant to your brand.
To customize product recommendations or cross-reference product information, use the catalog lookup tag in email and SMS messages to display information about a specific catalog item. For instance, you can use the catalog lookup tag to display product images beyond the default image for each product.
To enable additional inventory and price-based functionality like Back in Stock and Price Drop, you'll want to include inventory & price details for each variant.
Learn more about the data model
Read through the dropdowns to dive deeper into some nuances of the objects involved in Klaviyo's data model that are good to keep in mind.
Profile identifiers
Profiles all have a unique ID generated by Klaviyo. They are also identified by an optional external_id, email, and phone number. There is a hierarchy of profile identifiers, where Klaviyo's profile ID is taken as the strongest, then external_id, then email, then phone number.
Profiles are automatically merged based on their identifiers. This means that in general, only one profile can exist with one email address.
The only exception is if you use external_id to identify profiles, in which case you could have 2 profiles with different external_ids but the same email. It is generally best practice to use email rather than external_id to identify profiles. Check out our guide to identity resolution for more information.
Consent
Consent is stored on the profile level. Profiles have separate consent statuses for email, SMS, and mobile push notifications:
There are three possible consent statuses:
- Subscribed: this profile has explicitly opted in to this marketing channel.
- Never subscribed: this profile has neither opted into nor out of email marketing.
- Unsubscribed: this profile explicitly opted out of this marketing channel.
SMS and push notifications can only be sent to profiles with a Subscribed status for that respective channel.
Email can technically be sent to both Subscribed and Never subscribed profiles. Never subscribed profiles are often created through general site engagement, like starting a checkout, but you should not email Never subscribed profiles to protect your deliverability and sender reputation.
Profiles can also be suppressed for email, meaning they cannot receive email marketing messages. Profiles can be suppressed in one of 4 ways:
- An email hard bounced
- An email soft bounced more than 7 times in a row
- The profile was manually suppressed
- The person was suppressed in a previous email service provider
You can read more about suppressions here.
Lists and segments
Lists and segments are both ways to group profiles in Klaviyo.
Lists are static groupings of profiles. You can manually add or remove customers from a list at any time, and you can set a sign-up form to add customers to a specific list.
Segments are defined by a set of conditions and are dynamically updated as customers meet and do not meet criteria. You can connect segment conditions with and and or.
For example, Beantown Coffee has a Newsletter list that contains all profiles who have opted in to receive their regular email newsletter. They also have a segment of profiles who have opted in to email marketing and have ordered an item within the last 30 days, which they use to send more tailored communications based on the customer lifecycle.
You can read more about the difference between lists and segments here.
Campaigns and flows
You can message your customers in Klaviyo using either a campaign or a flow.
Campaigns are messages set to send to a specific audience at a specific time. Campaigns are great for weekly newsletters and announcements.
Flows, also known as automations, are a series of actions that automatically occur in response to a trigger. Flows can be triggered or initiated in several ways:
- When a profile joins a list or segment (list/segment-triggered)
- When a profile takes a certain action (metric-triggered)
- When a date-based profile property, such as a birthdate, is reached (date-triggered)
You can use email, SMS, and push in either flows or campaigns. Read more about flows here.
Top-level vs. nested event data
Only top-level event data can be used when creating segments and filtering flows. This refers to the JSON nesting hierarchy, where data nested more than a single node deep is unavailable for use in segmentation and filtering.
Keep this in mind when determining how to structure custom events you are sending into Klaviyo.