Klaviyo API Reference Guide

read

Overview

This is an overview of Klaviyo's track and identify API. These APIs are used for tracking people and the events or actions they do. For instance, tracking when someone is active on your website, when a purchase is made or when someone watches a video. The track and identify API can be implemented via javascript or server side. Which implementation to use will depend on the specific use case, and most users will use a mix of both.

They are optimized for low latency and high numbers of requests, so they do not adhere to the same REST principles our other APIs use. Klaviyo's REST API references can be found here.

If you are looking to integrate a custom ecommerce platform, Klaviyo's guide can be found here.

The Klaviyo Web Tracking Snippet (Javascript)

To track website activity, find your public API key by navigating to Account > Settings > API Keys. Your public key is six characters long. Add the following snippet of code to your main store template so it's included on all pages. You should place this snippet either with other analytics scripts you use or right before the closing </body> tag.

Make sure to replace API_KEY with your Klaviyo account's Public API key:

<script>
  var _learnq = _learnq || [];
  _learnq.push(['account', 'API_KEY']);
  (function () {
    var b = document.createElement('script'); b.type = 'text/javascript'; b.async = true;
    b.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'a.klaviyo.com/media/js/analytics/analytics.js';
    var a = document.getElementsByTagName('script')[0]; a.parentNode.insertBefore(b, a);
  })();
</script>

Note

You might be wondering, "How does using Klaviyo affect my site's performance?" The answer is Klaviyo doesn't affect your website's performance at all. Our code only loads once the rest of your website has finished loading. In addition, Klaviyo tells browsers to cache our JavaScript so your visitors often don't even need to download our JavaScript every time they switch pages.

Identifying Users (Javascript)

You'll be using the _learnq object that's automatically added by the Klaviyo Web Snippet.

To make an API call, Klaviyo uses a special syntax that allows your API calls to work even when our script hasn't loaded on the page yet. You'll create an array where the first value is the name of the method you want to call and any subsequent values are arguments to pass to that method.

The identify method allows you to identify and set properties on an individual. This method accepts a dictionary or hash of properties. When you identify someone, you must include either their email address, with the $email key, or a unique identifier such as their user ID, with the $id key.

Once you've included at least one of those identifiers, you're free to add any custom properties you want. Custom properties are useful for tracking facts about individuals. In Klaviyo, you can then create segments of people based on those properties. For instance, you might want to track an individual's plan type or sign up date. Klaviyo will also understand different data types you use, so feel free to use numbers, booleans and dates.

<script>
  var _learnq = _learnq || [];
  {% if user.is_logged_in %}
  _learnq.push(['identify', {
    $email: '{{ user.email }}',
    $first_name: '{{ user.first_name }}',
    $last_name: '{{ user.last_name }}', 
  }]);
  {% endif %}
</script>

Depending on the types of templates you use for your website, the lines with the following code may use different syntax:

{% if user.is_logged_in %}
{{ user.email }}

Using the template language available, you want to check if the person viewing the current page is logged in. If so, you should output their email and name, if available. If you don't have name information, remove those two lines and the trailing comma after the email "$email" line.

In addition to properties you track, Klaviyo will automatically determine what website each person was first referred from for attribution tracking and a person's location based on where they access your website.

Identifying Users (Server Side)

The server side Identify API endpoint is https://a.klaviyo.com/api/identify, which is used to track properties about an individual without tracking an associated event. Requests are made with a GET request to the specified endpoint with a single parameter, data, which is a base64 encoded JSON string. The JSON object requires two arguments:

Argument Type Description
token (required) string Your public key (six characters long).
properties (required) hash/dictionary Custom information about the person. You must identify the person by their email, using a $emailkey, or a unique identifier, using a $id. Other than that, you can include any data you want and it can then be used to create segments of people. For example, if you wanted to create a list of people on trial plans, include a person's plan type in this hash so you can use that information later.

 

An Example JSON object:

{
  "token" : "API_KEY",
  "properties" : {
    "$email" : "thomas.jefferson@example.com",
    "$first_name" : "Thomas",
    "$last_name" : "Jefferson",
    "Plan" : "Premium",
    "SignUpDate" : "2016-05-01 10:10:00"
  }
}

Example request. Note: the string after data= is the base64 encoded string of the JSON object above:

https://a.klaviyo.com/api/identify?data=ew0KICAidG9rZW4iIDogIkFQSV9LRVkiLA0KICAicHJvcGVydGllcyIgOiB7DQogICAgIiRlbWFpbCIgOiAidGhvbWFzLmplZmZlcnNvbkBleGFtcGxlLmNvbSIsDQogICAgIiRmaXJzdF9uYW1lIiA6ICJUaG9tYXMiLA0KICAgICIkbGFzdF9uYW1lIiA6ICJKZWZmZXJzb24iLA0KICAgICJQbGFuIiA6ICJQcmVtaXVtIiwNCiAgICAiU2lnblVwRGF0ZSIgOiAiMjAxNi0wNS0wMSAxMDoxMDowMCINCiAgfQ0KfQ==

Responses

Responses from requests made to the identify APIs return either 1, for success, or 0, for failure. Keep in mind API requests are processed asynchronously, typically in less than a second, so when a request returns there might be a slight delay before data appears inside Klaviyo. In certain cases, such as pixel tracking, it may be better to return a blank pixel rather than a success or failure message. In those cases, you can always return a blank pixel by adding a GET parameter i=1 to your request. 

Profile Special Properties

Klaviyo has a few special properties that are used to display information about people (designated with the $ character). These are:

  • $id - your unique identifier for a person
  • $email - email address
  • $first_name - first name
  • $last_name - last name
  • $phone_number - phone number
  • $title - title at their business or organization
  • $organization - business or organization they belong to
  • $city - city they live in
  • $region - region or state they live in
  • $country - country they live in
  • $zip - postal code where they live$
  • $image - url to a photo of the person

Tracking Events (Javascript)

You'll be using the _learnq object that's automatically added by the Klaviyo web tracking snippet.

To make an API call, Klaviyo uses a special syntax that allows your API calls to work even when our script hasn't loaded on the page yet. You'll create an array where the first value is the name of the method you want to call and any subsequent values are arguments to pass to that method.

The track method allows you to record events and actions people take on your website. This method accepts a string which is the name you give to that event. This method also accepts an optional dictionary or hash of properties associated with that event.

For example, you could track when someone purchases an item and include information on the purchase price and what items they bought. If you have an application where people have profiles you could track when someone fills out their profile.

When you add Klaviyo's web tracking snippet(s) to your site, we are only able to track the browsing activity of "known browsers" -- i.e. browsers that have visited and engaged at least once before. Klaviyo will not track anonymous browsers. More information can be found here

Klaviyo's event tracking and analytics are very flexible, so you can customize them to keep track of what's important to your business. Our track method also understands different data types, so you can use numbers, booleans and dates and we'll create intelligent charts and graphs based on the data you send. 

<script>
var _learnq = _learnq || [];
  _learnq.push(['track', 'Elected President', {
    'PreviouslyVicePresident' : true,
    'YearElected' : 1801,
    'VicePresidents' : ['Aaron Burr', 'George Clinton']
  }]);
</script>

Tracking Events (Server Side)

The Track API endpoint is https://a.klaviyo.com/api/track, which is used to track when someone takes an action or does something. Requests are made with a GET request to the specified endpoint with a single parameter, data which is a base64 encoded JSON string. The JSON object requires three arguments and allows for two optional arguments:

Argument Type Description
token (required) string Your public key (six characters long).
event (required) string Name of the event you want to track.
customer_properties (required) hash/dictionary Custom information about the person who did this event. You must identify the person by their email, using a $email key, or a unique identifier, using a $id. Other than that, you can include any data you want and it can then be used to create segments of people. For example, if you wanted to create a list of people on trial plans, include a person's plan type in this hash so you can use that information later.
properties (optional) hash/dictionary Custom information about this event. Any properties included here can be used for creating segments later. For example, if you track an event called "Posted Item," you could include a property for item type (e.g. image, article, etc.).
time (optional) integer When this event occurred. By default, Klaviyo assumes events happen when a request is made. If you'd like to track and event that happened in past, use this property.


An Example JSON object:

{
  "token" : "API_KEY",
  "event" : "Elected President",
  "customer_properties" : {
    "$email" : "thomas.jefferson@example.com"
  },
  "properties" : {
    "PreviouslyVicePresident" : true,
    "YearElected" : 1801,
    "VicePresidents" : ["Aaron Burr", "George Clinton"]
  },
  "time" : 1500922636
}

Example request. Note: the string after data=is the base64 encoded string of the JSON object above:

https://a.klaviyo.com/api/track?data=ew0KICAidG9rZW4iIDogIkFQSV9LRVkiLA0KICAiZXZlbnQiIDogIkVsZWN0ZWQgUHJlc2lkZW50IiwNCiAgImN1c3RvbWVyX3Byb3BlcnRpZXMiIDogew0KICAgICIkZW1haWwiIDogInRob21hcy5qZWZmZXJzb25AZXhhbXBsZS5jb20iDQogIH0sDQogICJwcm9wZXJ0aWVzIiA6IHsNCiAgICAiUHJldmlvdXNseVZpY2VQcmVzaWRlbnQiIDogdHJ1ZSwNCiAgICAiWWVhckVsZWN0ZWQiIDogMTgwMSwNCiAgICAiVmljZVByZXNpZGVudHMiIDogWyJBYXJvbiBCdXJyIiwgIkdlb3JnZSBDbGludG9uIl0NCiAgfSwNCiAgInRpbWUiIDogMTUwMDkyMjYzNg0KfQ==

Responses

Responses from requests made to the track APIs return either 1, for success, or 0, for failure. Keep in mind API requests are processed asynchronously, typically in less than a second, so when a request returns there might be a slight delay before data appears inside Klaviyo. In certain cases, such as pixel tracking, it may be better to return a blank pixel rather than a success or failure message. In those cases, you can always return a blank pixel by adding a GET parameter i=1 to your request.

If you only want to track the first occurrence of an event and ignore subsequent events, you can use /api/track-once. It uses the same request format as /api/track.

Event Special Properties

Klaviyo has a few special properties that are used to display information about an event (designated with the $ character). These are:

  • $event_id - an unique identifier for an event.  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.
  • $value - a numeric value to associate with this event (e.g. the dollar value of a purchase)
  • Profile special properties can be found above
Was this article helpful?
1 out of 1 found this helpful