Skip to content
This repository has been archived by the owner on Aug 18, 2023. It is now read-only.


Repository files navigation

python-klaviyo - DEPRECATED

Deprecation Notice

This SDK and its associated pip package are set to be deprecated on 2024-06-30 and will not receive further updates.

We recommend migrating over to our newest SDK.

You can read more about our SDK release history and support here

For a comparison between our old and new APIs, check out this guide.

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

Response Object

All of the methods will return a KlaviyoAPIResponse object containing two attributes status_code and data.
For example, if you wanted to create a list you would do the following:

response = client.Lists.create_list(list_name) # returns information about the created list
response.status_code # returns the http status code of the response

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.Public.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.Public.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

# return a timeline of all metrics
    since=None (unix or returned uuid from request)

# you can query for a specific metric id
    since=None (unix or returned uuid)

Export metric specific values

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

# to get all lists

# to add a new list

# get list details

# update list name

# delete a list

# Add subscribers to a list, this will follow the lists double opt in settings
client.Lists.add_subscribers_to_list(list_id, profiles)
    profiles: is list of objects formatted like {'email': EMAIL, 'custom_property': NAME}
# Check email address subscription status to a list
client.Lists.get_subscribers_from_list(list_id, emails)
    emails: is a list of email addresses

# Unsubscribe and remove profile from a list
client.Lists.delete_subscribers_from_list(list_id, emails)
    emails: is a list of email addresses 

# Add members to a list, this doesn't care about the list double opt in setting
client.Lists.add_members_to_list(list_id, profiles)
    profiles: is list of objects formatted like {'email': EMAIL, 'custom_property': NAME}
# Check email addresses if they're in a list
client.Lists.get_members_from_list(list_id_, emails)
    emails: is a list of email addresses
# Remove emails from a list
client.Lists.remove_members_from_list(list_id, emails)
    emails:  a list of email addresses

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

# get all members in a group or list
client.Lists.get_all_members(group_id, marker=None)

# check if email is in a segment, takes a list of emails.
client.Lists.get_members_from_segment(segment_id, [emails])

You can fetch profile information given the profile ID. See here for more information:

# get profile by profile_id

# update a profile
client.Profiles.update_profile(profile_id, properties) # properties is a dict

# unset properties on a profile
    properties=['snake_case_property', 'camelCaseProperty', 'This one has spaces']

# get all metrics for a profile with the default kwargs
# to paginate the responses you will get a UUID returned from the response, see here for more information
client.Profiles.get_profile_metrics_timeline(profile_id, since=None, count=100, sort='desc')

# get all events of a metric for a profile
# to paginate the responses you will get a UUID returned from the response
client.Profiles.get_profile_metrics_timeline_by_id(profile_id, metric_id, since=None, count=100, sort='desc')

You can fetch the profile ID for a given email:

# get the profile_id for ''

You can request profile deletion based on an email, phone number, or profile ID. See here for more information:

# request deletion of the profile tied to ''
client.DataPrivacy.request_profile_deletion(identifier=', id_type='email')

You can fetch information from campaigns:

# request all campaigns
client.Campaigns.get_campaigns(page=0, count=50)

# get campaign recipients (offset can be found from the next_offset in the previous response)
client.Campaigns.get_campaign_recipients(campaign_id, count=5000, offset='', sort='asc')

Rate Limiting

If a rate limit happens it will throw a klaviyo.exceptions.KlaviyoRateLimitException This will contain a detail key with a string value mentioning the time to back off in seconds

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.