Python wrapper for the Klaviyo API
Switch branches/tags
Clone or download
remstone7 Merge pull request #9 from remstone7/201809_v2
201809 v2
* metrics api
* lists api
Latest commit f63da5c Oct 16, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
klaviyo address pr feedback Sep 27, 2018
.gitignore Fixing gitignore Aug 2, 2012 mailinator > Sep 27, 2018 update readme, versioning, formatting Aug 24, 2018

What is Klaviyo?

Klaviyo is a real-time service for understanding your customers by aggregating all your customer data, identifying important groups of customers and then taking action.

What does this package do?

  • Track customers and events directly from your backend.
  • Track customers and events via JavaScript using a Django middleware.

How to install?

easy_install klaviyo


pip install klaviyo

API Examples

After installing the klaviyo package you can initiate it using your public token which is for track events or identifying profiles and/or your private api key to utilize the metrics and list apis.

import klaviyo

client = klaviyo.Klaviyo(public_token=PUBLIC_TOKEN, private_token=PRIVATE_TOKEN)

You can then easily use Klaviyo to track events or identify people. Note, track and identify requests take your public token.

# Track an event...
client.track('Filled out profile', email='', properties={
    'Added social accounts' : False,

# you can also add profile properties
  'Filled out profile', 
    'Added social accounts' : False,
    '$first_name': 'Thomas',
    '$last_name': 'Jefferson'

# ...or just add a property to someone
client.identify(email='', properties={
    '$first_name': 'Thomas',
    '$last_name': 'Jefferson',
    'Plan' : 'Premium',

You can get metrics, a timeline of events and export analytics for a metric. See here for more

# return all metrics

# you can paginate through using the page offset

# return a timeline of all metrics

# add a since param to get data 
# you can paginate through using a Unix timestamp or a UUID obtained from the next attribute

# you can query a specific metric id by

# you can export metric data

You can create, update, read, and delete lists. See here for more information

# to get all lists

# to add a new list
  list_name = 'YOUR_LIST_NAME'  ,
  method = 'POST'

# get list details

# update list name
  list_name = 'NEW_LIST_NAME',
  method = 'POST'

# delete a list
    method = 'DELETE'

Note in the list_subscription call, subscription_type is either subscribe or members. Please refer to the docs to see which method is correct and

# subscribe members to a list and check if they're in a list
client.list_subscription('list_id', subscription_type, data=data, method="GET")

# you can unsubscribe customers from a list
client.unsubscribe_from_list('list_id', subscription_type, emails)

# get exclusion emails from a list - marker is used for paginating
client.list_exclusions('list_id', marker=None)

# get all members in a group or list

How to use it with a Django application?

To automatically insert the Klaviyo script in your Django app, you need to make a few changes to your file. First, add the following setting:


then add the Klaviyo middleware at the top of the MIDDLEWARE_CLASSES:

    # Other classes

This will automatically insert the Klaviyo script at the bottom on your HTML page, right before the closing body tag.