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.
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.
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.
"properties": {
"cart": {
"items": [
{"product_id": "7677341401226"},
{"product_id": "7677341401227"}
]
}
}"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
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.
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.
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.
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 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.
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.
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.
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.