Track API reference

Learn how to use Klaviyo’s Track API to track customers as they interact with your site, and then send those events into Klaviyo, building the backbone for segmentation and automation within the platform.

📘

Info

This article assumes you’ve set up your site according to our Getting started with Track and Identify APIs article.

We have two versions of the Track API: a front-end and a back-end version. The structures are similar, but not exactly the same, so you may opt for one over the other depending on whether you want to send an event or an event’s data source.

The most important difference in functionality is that the front-end Track API call will only track a person’s actions if they are already cookied; it won’t work if they’re using an anonymous browser. The back-end version of this request uses the customer_properties dictionary to designate the profile to which this event should be tracked, using one of the following:

  • Highly recommended: an email address ($email), or if you have SMS-only contacts, a phone number ($phone_number)
  • A unique identifier, such as their user ID ($id)

📘

Info

We highly recommend you consistently identify all individuals using only their email address ($email) or phone number ($phone_number), and do not pass $id values. For more information, see Getting started with Track and Identify APIs.

Front-end tracking events (JavaScript)

The front-end version of the Track API uses the _learnq object to track customers. This object is a part of Klaviyo's main onsite tracking snippet, known as "klaviyo.js", which is automatically added during many of our integration setups. To check if the snippet is already a part of your integration, see our integration documentation.

📘

Info

When you add Klaviyo's onsite 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. For more information, see our Guide to Klaviyo onsite tracking.

The Track method allows you to record events and actions people take on your website. This method accepts the following inputs:

  • An event name as a string (required)
  • A dictionary or hash of properties associated with the event (optional)

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. This method understands different data types, so you can use numbers, booleans, dates, and lists in the request, and Klaviyo will create intelligent charts and graphs based on the data you send.

For example, you can use this front-end API to track when someone completes an order, and include information on the purchase price and items in the order. If your site supports customer profiles, you could also include information about when someone fills out their profile.

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

Back-end 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. This API is most useful when it comes to the following ecommerce store integration events:

  • Placed Order
  • Fulfilled Order
  • Cancelled Order
  • Refunded Order

There are two ways to make requests of the back-end Track API: POST and GET.

POST

POST requests are sent via the data JSON object, serialized as a URL-encoded form, and are used to track a profile’s activity. This endpoint can accept payloads up to approximately 1MB and can handle up to 200 unique metrics (event types). The JSON object requires two arguments and allows for three optional arguments, as described in the table below:

ArgumentTypeDescription
token
(required)
stringYour public key (six characters long)
event
(required)
stringName of the event you want to track
customer_properties
(required)
hash/dictionaryProperties of the profile that triggered this event. You must identify the person by their email using a $email key (or if you have SMS-only contacts, by their phone number using a $phone_number key). Other than that, you can include any data you want and it can then be used to create segments of people.

There are also specific properties you can use here, denoted by a $, which map directly to some of Klaviyo’s features.

For example, if you wanted to create a list of people on trial plans, include a person's plan type in this JSON object so you can use that information later.

Klaviyo’s database of customer properties is akin to a schemaless relational database, so you can add, delete, update, and read from this section at any time.
properties
(optional)
hash/dictionaryProperties of this event. Any properties included here can be used for creating segments later. There are also specific properties you can use here, denoted by a $, which map directly to some of Klaviyo’s features.

For example, if you track an event called Ordered Product, you can include a property for item type (e.g. image, article, etc.), size, etc.
time
(optional)
integer (10 digit unix timestamp)When this event occurred. By default, Klaviyo assumes events happen when a request is made. If you'd like to track an event that happened in the past, use this property.

POST example JSON object

{
  "token": "PUBLIC_KEY",
  "event": "Ordered Product",
  "customer_properties": {
    "$email": "[email protected]"
  },
  "properties": {
    "item_name": "Boots",
    "$value": 100
  }
}

GET

❗️Warning
This is offered for backwards compatibility; we recommend all new implementations use the POST approach above.

GET requests are made with the data parameter, which is a base64-encoded JSON string that is then URL-encoded and passed as a query parameter. The JSON object requires three arguments and allows for two optional arguments, as described in the table below:

ArgumentTypeDescription
tokenstringYour public key (six characters long)
event
(required)
stringName of the event you want to track
customer_properties
(required)
hash/dictionaryInformation about the customer. You must identify the person by their email, using a $email key, or a unique identifier, using an $id key.

There are also specific properties, denoted by a $, which map directly to some of Klaviyo’s features. These specific properties are overwritable if they need to be changed or updated later on.

Data included here can be used to create segments of people; e.g. if you wanted to create a segment of people on trial plans, you can include a person's plan type as a key-value pair here for later use.
properties
(optional)
hash/dictionaryInformation about this event, containing things such as items in order (array of objects), item names, categories, billing/shipping information, etc. There are also specific properties you can use here, denoted by a $, which map directly to some of Klaviyo’s features.
time
(optional)
integer (unix timestamp)When this event occurred. By default, Klaviyo assumes events happen when a request is made. If you'd like to track an event that happened in the past, use this property.

GET example JSON object

{
  "token" : "PUBLIC_KEY",
  "event" : "Elected President",
  "customer_properties" : {
    "$email" : "[email protected]"
  },
  "properties" : {
    "PreviouslyVicePresident" : true,
    "YearElected" : 1801,
    "VicePresidents" : ["Aaron Burr", "George Clinton"]
  },
  "time" : 1500922636
}

Example request

The string after data=is the base64-encoded, and then URL-encoded string of the JSON object above.

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

Specific properties

customer_properties

There are optional special fields you can include as a part of the customer_properties hash/dictionary which Klaviyo will know how to specifically handle, as shown in the table below:

ArgumentTypeDescription
$emailstringEmail address
$first_namestringFirst name
$last_namestringLast name
$phone_numberstringPhone number; e.g., "+13239169023"
$citystringCity the customer lives in
$regionstringRegion or state the customer lives in
$countrystringCountry the customer lives in
$zipstringPostal code the customer lives in
$imagestringURL to a photo of a person
$consentlist of stringsType(s) of marking a customer has consented to receive. This is only necessary for GDPR compliant businesses.
E.g., “['sms', 'email', 'web', 'directmail', 'mobile']”

These customer properties are overwritable in the Klaviyo platform. For example, if a customer provides an incorrect birthday and then adds the correct one, the new date will populate into Klaviyo and overwrite the old, incorrect one.

Properties

You can use the following special fields in properties:

ArgumentTypeDescription
$event_idstringA unique identifier for an event. You should send an $event_id if you have a unique identifier for each event (e.g. an order ID) in the following format: event name+timestamp+customer email/id.

If you don't specify an $event_id, it will default to the timestamp of the event.

You should also set the $event_id if you expect certain events to occur at the same point in time, which you will then want to split into multiple events. For example, if someone orders multiple items in one order, you may want to record one event for each item purchased.
$valueintegerA numeric value to associate with this event (e.g. the dollar value of a purchase)

Additional resources