Track API reference

📘

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:

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:

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:

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:

Additional resources

• About cookies in Klaviyo
• Getting started with Track and Identify APIs
• Identify API reference