Skip to main content

Fundamentals of building with Klaviyo

Course overview
Lesson
1 min read

Map your Klaviyo data to align with your use case

Now that we've broken down how Klaviyo organizes information, let's look at a real example you'll likely see when working on the platform.

Maya's abandoned cart

Marketing teams love an abandoned cart flow because it is a classic activated experience: someone shows intent, leaves before converting, and Klaviyo helps the business follow up at the right moment.

That is exactly what happened with Maya.

She found a pair of Eastie High Tops, added them to her cart, and left before checking out. That behavior can trigger an email, text, push, or WhatsApp message reminding her she still has something waiting for her.

On the front end, this feels simple.

Let's walk through it.

Step 1: Identify the person

Before you can trigger anything, Klaviyo needs to know who the event belongs to.

In this case, that person is Maya.

Klaviyo recommends identifying profiles by email. If your app or backend has its own internal user ID, external_id is available as an alternative.

Using an external ID as your unique identifier adds complexity, so we only recommend it if you have a well-managed identity system. If identity is mapped inconsistently, teams can end up with duplicate profiles that do not merge automatically later.

What to remember: start with the clearest, most stable identifier possible. For most implementations, that is email.

These examples assume the Klaviyo JavaScript snippet is already loaded on your site.

javascript
klaviyo.identify({
  "email": "maya@example.com",
  "phone_number": "+15555550111"
});

Step 2: Capture what happened

Now that we know who the person is, we need to record what they did.

In this case, Maya added something to her cart.

This is event data.

A few parts of this payload matter more than they may first appear to:

  • $value is a reserved field and should be numeric. That is what makes the event usable in revenue-related reporting later.
  • $event_id helps distinguish one event occurrence from another. This matters most for higher-frequency actions or retry-prone systems. If you send events from your backend with the Events API, the same field is called unique_id.

This is a good example of why event structure matters. Even when the event “works,” small payload decisions can affect reporting, timing, and how reliable the data is later.

javascript
klaviyo.track("Added to Cart", {
  "ProductName": "Eastie High Top",
  "ProductID": "7677341401226",
  "VariantID": "7677341401226-VARIANT",
  "VariantName": "Eastie High Top",
  "VariantSKU": "CLO-004",
  "Price": 128.00,
  "Categories": ["Shoes", "Fall26Drop"],
  "URL": "https://www.eastie.com/products/eastie-high-top",
  "ImageURL": "https://www.eastie.com/images/hightopshoe.jpg",
  "$currency": "USD",
  "$value": 128.00,
  "$event_id": "8812_1793635200"
});

Step 3: Only top-level data is available for flow filters

Now we can put the pieces together.

An abandoned cart flow typically triggers off the Added to Cart event, waits for a period of time, and checks whether a Placed Order event happened afterward.

That sounds straightforward, but this is where data structure often starts to matter in more visible ways.

Now say Maya adds a second pair before she leaves. For her reminder to show everything in her cart, the event needs the full cart. Imagine that payload looks like the first example:

This may look perfectly fine in the payload, and it may even render correctly in the email template.

But if the data you want to filter on lives only inside nested objects, marketers will not be able to segment or build flow logic off those fields in the way they expect.

A better pattern is to pull important filterable values up to the top level.

For example, in the second payload, ItemNames and Categories sit at the top level, so marketers can filter on them.

Then, if needed, you can still keep richer nested data available separately for template rendering. That nested array is also what lets a template loop through each item. Flat fields like product_1_name and product_2_name can't be looped.

What to remember: structure the payload for both machines and the people who will need to use the data later.

json
"properties": {
  "cart": {
    "items": [
      {"product_id": "7677341401226"},
      {"product_id": "7677341401227"}
    ]
  }
}
json
"properties": {
  "ItemNames": ["Eastie High Top", "Eastie Low Top"],
  "Categories": ["High Tops", "Low Tops"],
  "Items": [
    {"ProductID": "7677341401226", "ProductName": "Eastie High Top", "ItemPrice": 128.00},
    {"ProductID": "7677341401227", "ProductName": "Eastie Low Top", "ItemPrice": 110.00}
  ],
  ...
}

Same concept, different business

If you're worried that you won't be able to use any content from this course because you are not in an ecommerce business, fear not. This pattern shows up across verticals. Say a restaurant wants to remind guests who started a reservation but never confirmed it.

  • The profile is the guest.
  • The event is Started Reservation, with details like party size and requested time sent as top-level properties.
  • Each location's address and hours live in a web feed.

Klaviyo's data model can adapt across verticals because the concept is the same even when the business is different.

Common gotchas

Flip each card to see what's happening and an example.
0 of 4 cards flipped
Gotcha
Missing a unique ID ($event_id or unique_id) on high-frequency events. Symptom: event counts look lower than expected.
What is happening

What is happening: without a unique ID, Klaviyo uses the event's timestamp, down to the second, as the ID. Two events for the same profile and metric in the same second look like duplicates, so Klaviyo keeps one and drops the other.

Example: Maya adds two different pairs to her cart within the same second. Without a unique ID on each, Klaviyo records one Added to Cart and silently drops the other.

Gotcha
Event property naming issues. Symptom: a metric property shares a name with a profile property, and that metric disappears entirely from the segment builder and flow filter options.
What is happening

What is happening: when a metric property and a profile property share a name, the metric property doesn't appear in segment builder or flow filter options.

Example: Eastie stores shoe_size as a profile property (a general preference). The "Added to Cart" event also includes a shoe_size property, the size of the item in this specific cart. Because the names match, the event-level shoe_size gets hidden entirely.

Gotcha
Nested cart data that looks correct but can't be used downstream. Symptom: the payload arrives, but filters or segments do not behave the way the team expects.
What is happening

What is happening: the fields are nested too deeply for the intended use case.

Example: Let's say Eastie had a coupon as part of their abandoned cart flow, but they wanted to skip anyone who added a final sale item. Because the developer added final sale as a tag that lived inside of cart.items nested two levels down, Eastie's marketing team cannot filter on this property in the Flow trigger.

Gotcha
Values of 0, null, or empty string not behaving as expected in segmentation. Symptom: data appears to be present, but it does not work the way a marketer expects in the segment builder.
What is happening

What is happening: some values are excluded from segmentation behavior, which can be confusing if you don't know to look for it.

Example: a discount code property set to "" for full-price orders looks present in the payload but never shows up as a segmentable value.

What to do when you mapped your data incorrectly

Sometimes the issue is not the current payload. It is the fact that the wrong structure has already been synced.

Click into the dropdowns below to review common scenarios you may face in Klaviyo and how to recover.

If a metric was mapped incorrectly

Go to Analytics > Metrics, find the metric, and delete it. This removes the metric and all events tied to it.

Before you do that, fix the payload structure in your integration first. Then resync or reimport the data so the corrected version lands under a fresh metric.

One important callout: if any live flow is triggered off that metric, double check it afterward. Deleting and recreating a metric can create a new internal ID, even if the metric name stays the same. That means a flow can quietly stop working if the trigger is still pointing at the old version.

If data that should have been top-level was sent nested instead

There is no way to restructure data that is already stored in Klaviyo. If the payload was sent with nested properties, Klaviyo cannot go back and flatten those existing events for you.

First, fix the integration so it sends the corrected top-level structure going forward.

If the historical version of that data matters, for example if your abandoned cart logic depends on older event history, you will need to follow the same recovery process as above: delete the metric, then reimport the historical data using the corrected structure.

If identity was mapped inconsistently

For example, if inconsistent use of external_id created duplicate profiles, stop sending the problematic identifier before you make changes to existing profiles. Otherwise, you may continue creating new duplicates.

For a small number of profiles, you can use Klaviyo's Merge Profiles API to merge two profiles directly and choose which profile should remain as the destination.

For anything at scale, reach out to Klaviyo Support. Bulk profile cleanup can be risky, and incorrect merges can result in lost data. Support can review large-scale duplicate cleanup requests, but bulk-merge assistance isn't guaranteed.

Before merging, make sure you understand how conflicting property values will be handled, since the surviving profile will take precedence when fields conflict.

Why this matters

An abandoned cart reminder may look like a simple flow.

But under the hood, it depends on clean profile identification, well-structured event data, and a payload that supports both personalization and filtering.

When those pieces are mapped well, the marketing team can build and optimize confidently.

When they are not, the experience may still launch but it will be harder to troubleshoot, harder to personalize, and harder to trust.

Map your Klaviyo data to align with your use case