Manually Import Historical Event Data



While we recommend using Klaviyo's integrations with tools like Shopify, Magento and Bigcommerce to integrate data going forward (or our API to add your custom data), it's also possible to manually add event data (i.e. what someone did at a certain point in time) to Klaviyo.

A common example of this is historical purchase data from a previous ecommerce platform.

Upload a CSV File of Data

To get started, navigate to your account's Integrations tab and click the link for the by uploading a CSV option.


On the next page, you'll be prompted to load a CSV file with three required columns : 

  • Timestamp: showing the day and time of the event (i.e. the order placed).
  • Person//Email: This is the email address of the person who made the purchase. 
  • Optional: 
    • $value: If you're uploading purchase data, make sure 
    • Any other properties about that event you want to upload. 

How to format your CSV file

  • Each CSV file should represent an action or activity someone can take. For instance, "Purchased product" or "Signed up for webinar." If you have multiple actions to track, you should upload them as separate CSV files.
  • If you don't specify $event_id, it will default to the timestamp of the event. In practice, you should send an $event_id if you have an unique identifier for each event, for example an order ID. You should also set the $event_id if you expect certain events to occur at the same point in time. This can happen when someone takes one action which you will split into multiple events. For example, if someone purchases multiple items and you want to record one event for each item purchased.

  • Each row in a CSV file represents one action taken by one person. If someone does something multiple times, you should have one row for each time they did that action.
  • The first row of your CSV file contains the headers to identify the data in each column.
  • You need one column labeled Timestamp which has the date and time that row's action occurred. You should format the date and time as YYYY-mm-dd HH:MM:SS. So 1:30pm on November 11th would be 2012-11-14 13:30:00.
  • You need a column labeled Person//Email or Person//ID to identify the person who did that action. If you use a Person//Email column, the data in that column should be the email address of that person. If you use a Person//ID column, the data in that column should be a unique identifier for that person, such as their customer ID. You can include both columns, if you want, but you need to include at least one of them.
  • If you have additional data about the person who did something, it should go in a column whose label starts with Person// and then the type of data that column has. For instance, if you had the company or organization each person belongs to, you'd want to label that column Person//Organization. The special prefix let's us know to associate the data in that column with each person rather than the activity. The following are special columns you can use to help you identify people:
    • Person//Email — email address
    • Person//First Name — first name
    • Person//Last Name — last name
    • Person//Phone — phone number
    • Person//Organization — organization
    • Person//Title — job title
  • If you have additional data about each action, you can include it in extra columns with any labels you want. For instance, if someone purchases something and you want to include what item they bought, you could include that data in a column labeled Item Purchased.
  • If you don't have data for a particular column, leave it blank and we'll ignore it. For instance, if you don't know someone's organization, you can leave the column for Person//Organization blank and we'll skip tracking that property

How to Name your Event

After you load and import your CSV file, you will have the opportunity to name the event. If you are attempting to map the imported data to an event metric that already exists in your account, make sure to type the event name exactly as it already appears.

647924Note for Ecommerce Stores Loading Purchase Data

If you're uploading purchase data, you'll want to upload two files - one for the overall order, and a second that includes item by item data.  Here's what the headers of those files should look like typically: 

Placed Order

Person//Email Person//First Name Person//Last Name Timestamp $event_id $value Quantity Categories Items John Smith 2014-03-10 08:55 12425 49.00 2 ["Books", "Games"] ["To Kill a Mockingbird", "Pictionary"] 

Ordered Product

Person//Email Person//First Name Person//Last Name Timestamp $event_id $value Quantity Category Item John Smith 2014-03-10 08:55 12425 24.00 1 Books To Kill a Mockinbird

The reason to include two metrics is that it makes it easier to later trigger emails off of both an overall order and off of specific categories / items. 

For Ordered Product, $event_id needs to be a unique identifier for each combination of the order and the product ordered.  The easiest way to do this is usually to use a combination of the Order ID and product ID or item number in the order. 

Import Troubleshooting

My Import is Taking a Long Time

Imports can take between 5 minutes and 24 hours depending upon the size of your list -- we highly recommending beginning the import of any list at least 24 hours in advance of needing it for a given campaign to ensure the import process does not hold up your send.

My Import Keeps Failing

If your import fails, it is likely due to one of the following reasons:

  • Is your file a .csv file? Your file must be in .csv format. If you attempt to upload an Excel file or a .txt file, the import will fail.
  • Did you format your Timestamp column correctly? You should format the date and time as YYYY-mm-dd HH:MM:SS. For example, 1:30pm on November 11th would be: 2012-11-14 13:30:00.
  • Do all required columns have data filled in for every row? You must have a column labeled Person//Email or Person//ID. If either of these columns have an empty row, this can cause your import to fail.
  • Does your Person//Email column have an invalid email addresses in it? If you have values within the Person//Email that don't have a valid email address format, this can cause your import to fail.
  • Are all of your columns labeled correctly? Are there any spaces? Make sure that all of your column headers match what is outlined in this guide. You will also want to make sure there are no spaces in your column names!
Was this article helpful?
0 out of 0 found this helpful