How to Import Historical Orders Into Klaviyo Without Triggering Your Flows

Klaviyo is only as useful as the history behind it. A brand with ten years of orders sitting in an old system, and only six months of data in Klaviyo, is making segmentation decisions with most of the picture missing.

I worked on a project like this, where a client’s customer data lived in tab delimited files produced by an old classic ASP system on a Windows server. I wrote about the whole project in Syncing Legacy ASP Data into Klaviyo. Here I want to focus on the practical rules, because the mistakes people make are surprisingly consistent.

Rule one: import profiles first, then events

A profile is the person: their email, name, and any custom properties you want to keep, such as loyalty tier, last category viewed or average basket size. Events are things that person did.

Create or update the profile first, then attach events to it. Doing it in this order keeps your data clean and makes it easier to see what happened if a row fails.

Rule two: use the standard event names

Klaviyo has familiar names for ecommerce activity, such as Viewed Product, Added to Cart, and Placed Order. If you invent your own names, reports, segments and flows built for the standard ones will not see your history.

Match the shape of your events to what a live Shopify integration sends. Pay attention to the properties, such as order value, item names and SKUs, because flows and segments depend on them.

Rule three: set the original time

Every historical event should carry the time it really happened, not the time you imported it. Otherwise a customer who ordered in 2019 appears to have ordered today, and every report is wrong.

Also give each event a unique identifier, so that running the import twice does not create duplicates. Use something stable, like the order number plus the line number. This is what lets you fix a bug and rerun the whole file without fear.

Rule four: protect your flows

This is the one that causes the horror stories. Flows listen for events. If a flow is triggered by Placed Order, an imported order can start that flow for the customer, depending on how the event is timestamped and how the flow is configured. A thank you email for an order from six years ago is embarrassing at best.

Before you import anything:

List every flow triggered by the events you plan to send.
Put those flows in a draft or manual state for the duration of the import, or add a filter so they only act on recent activity.
Test with a handful of your own addresses first, and confirm nothing gets sent.
Turn the flows back on only after you have checked the results.

Read how your own account behaves with old timestamps. I would rather spend ten minutes checking than assume.

Having someone’s email in an old database does not mean they agreed to marketing emails from you through Klaviyo. Importing a profile and subscribing it to marketing are separate things, and they should stay separate. Bring in the history so it can power segments and personalization, and subscribe only the people who actually gave consent, according to the rules where you do business. When in doubt, check with whoever handles your compliance.

Rule six: expect messy files

Real exports are not tidy. In the legacy project, some of the files had an inconsistent number of columns depending on who generated them, and some product identifiers did not exist in the catalog anymore. Plan for it:

Validate each row before sending it.
Write bad rows to a separate report and keep going.
Log every run, with counts for rows read, profiles created, events sent and rows skipped.
Send an alert on errors, so a human looks at the log within a day.

Respect Klaviyo’s rate limits too. Send in batches, watch for 429 responses, and wait as instructed. A big historical import might take hours, and that is fine.

What you get for the effort

Once the history is in, segments like “bought twice in the last year but not since March” or “big spenders who never opened a campaign” become possible. Triggered campaigns based on real purchase behavior become possible too. That is the point of the exercise.

If you have a pile of customer data waiting to get into Klaviyo, email kevin@kevinhq.com and describe where it lives and roughly how many records there are. I can tell you whether it is an afternoon of work or a proper project.

← Back to Homepage