Klaviyo Python SDK (Legacy)

Legacy Notice

This SDK is set to be deprecated + retired on 2024-06-30.

We have a NEW python SDK to go along with our new API.

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.

Klaviyo Python SDK

• SDK version: 1.0.7.20220329

Helpful Resources

• API Reference
• API Guides
• Postman Workspace

Design & Approach

This SDK is a thin wrapper around our API. See our API Reference for full documentation on API behavior.

This SDK exactly mirrors the organization and naming convention of the above language-agnostic resources, with a few namespace changes to make it Pythonic (details in Appendix).

Organization

This SDK is organized into the following resources:

• Campaigns
• DataPrivacy
• ListsSegments
• Metrics
• Profiles
• Templates
• TrackIdentify

Installation

pip

You can install this library using pip.

Depending on your system configuration, you will need to run one of the following shell commands:

pip install klaviyo-sdk

OR

pip3 install klaviyo-sdk

source code

Alternatively, you can also run this using this repo as source code, by running one of the following shell commands within the cloned repo:

pip install -r requirements.txt

OR

pip3 install -r requirements.txt

and then running python from the cloned repo.

Usage Example

To instantiate the client

from klaviyo_sdk import Client

client = Client( "YOUR API KEY HERE", max_delay=60, max_retries=3)

NOTE:

• The SDK retries on resolvable errors, namely: rate limits (common) and server errors on klaviyo (rare).
• The keyword arguments define retry behavior; the example is populated with the default values.
• max_delay denotes total delay (in seconds) across all attempts.

To call the metric-export operation:

metric_id = "METRIC_ID"
count = 100

client.Metrics.metric_export(metric_id, count=count) 

Error Handling

This SDK throws an ApiException error when the server returns a non-2XX response.

An ApiException consists of the following attributes:

• status : int
• reason : str
• body : bytes
  • this can be decoded into a native python dictionary as follows:

    # to decode to a dictionary
    import json
    BODY_DICT = json.loads(YOUR_EXCEPTION.body)
    
    # to decode to a string
    BODY_STRING = YOUR_EXCEPTION.body.decode('utf-8')

• headers : class 'urllib3._collections.HTTPHeaderDict'
  • This can be interacted with as a normal dictionary:
    • ex:

      date = YOUR_EXCEPTION.headers['Date']
      keys = YOUR_EXCEPTION.headers.keys()
      values = YOUR_EXCEPTION.headers.values()
      

Comprehensive list of Operations & Parameters

NOTE:

• Organization: Resource groups and operation_ids are listed in alphabetical order, first by Resource name, then by OpenAPI Summary. Operation summaries are those listed in the right side bar of the API Reference.
• For example values / data types, as well as whether parameters are required/optional, please reference the corresponding API Reference link.
• Some keyword args are required for the API call to succeed, the API docs above are the source of truth regarding which keyword params are required.
• JSON payloads should be passed in as native python dictionaries.

Campaigns

Cancel a Campaign

client.Campaigns.cancel_campaign(campaign_id)

Clone a Campaign

client.Campaigns.clone_campaign(campaign_id, name=name, list_id=list_id)

Create New Campaign

client.Campaigns.create_campaign(list_id=list_id, template_id=template_id, from_email=from_email, from_name=from_name, subject=subject, name=name, use_smart_sending=use_smart_sending, add_google_analytics=add_google_analytics)

Get Campaign Info

client.Campaigns.get_campaign_info(campaign_id)

Get Campaign Recipients

client.Campaigns.get_campaign_recipients(campaign_id, count=count, sort=sort, offset=offset)

Get Campaigns

client.Campaigns.get_campaigns(page=page, count=count)

Schedule a Campaign

client.Campaigns.schedule_campaign(campaign_id, send_time=send_time)

Send a Campaign Immediately

client.Campaigns.send_campaign(campaign_id)

Update Campaign

client.Campaigns.update_campaign(campaign_id, list_id=list_id, template_id=template_id, from_email=from_email, from_name=from_name, subject=subject, name=name, use_smart_sending=use_smart_sending, add_google_analytics=add_google_analytics)

DataPrivacy

Request a Deletion

client.DataPrivacy.request_deletion(body=body)

ListsSegments

Add Members to a List

client.ListsSegments.add_members(list_id, body=body)

Create List

client.ListsSegments.create_list(list_name=list_name)

Delete List

client.ListsSegments.delete_list(list_id)

Exclude Profile From All Email

client.ListsSegments.exclude_globally(email=email)

Get Global Exclusions & Unsubscribes

client.ListsSegments.get_global_exclusions(reason=reason, sort=sort, count=count, page=page)

Get All Exclusions for a List

client.ListsSegments.get_list_exclusions(list_id, marker=marker)

Get List Info

client.ListsSegments.get_list_info(list_id)

Check if Profiles Are in a List

client.ListsSegments.get_list_members(list_id, body=body)

Check if Profiles Are in a List and not Suppressed

client.ListsSegments.get_list_subscriptions(list_id, body=body)

Get Lists

client.ListsSegments.get_lists()

Get List and Segment Members

client.ListsSegments.get_members(list_or_segment_id, marker=marker)

Check if Profiles Are in a Segment

client.ListsSegments.get_segment_members(segment_id, body=body)

Remove Profiles From List

client.ListsSegments.remove_members(list_id, body=body)

Subscribe Profiles to List

client.ListsSegments.subscribe(list_id, body=body)

Unsubscribe Profiles From List

client.ListsSegments.unsubscribe(list_id, body=body)

Update List Name

client.ListsSegments.update_list_name(list_id, list_name=list_name)

Metrics

Get Metrics Info

client.Metrics.get_metrics(page=page, count=count)

Query Event Data

client.Metrics.metric_export(metric_id, start_date=start_date, end_date=end_date, unit=unit, measurement=measurement, where=where, by=by, count=count)

Get Events for a Specific Metric

client.Metrics.metric_timeline(metric_id, since=since, count=count, sort=sort)

Get Events for All Metrics

client.Metrics.metrics_timeline(since=since, count=count, sort=sort)

Profiles

Exchange ID for Profile ID

client.Profiles.exchange(body=body)

Get Profile

client.Profiles.get_profile(person_id)

Get Profile ID

client.Profiles.get_profile_id(email=email, phone_number=phone_number, external_id=external_id)

Get Profile's Events for a Specific Metric

client.Profiles.profile_metric_timeline(person_id, metric_id, since=since, count=count, sort=sort)

Get Profile's Events for all Metrics

client.Profiles.profile_metrics_timeline(person_id, since=since, count=count, sort=sort)

Update Profile

client.Profiles.update_profile(person_id, params=params)

Templates

Clone Template

client.Templates.clone_template(template_id, name=name)

Create New Template

client.Templates.create_template(name=name, html=html)

Delete Template

client.Templates.delete_template(template_id)

Get All Templates

client.Templates.get_templates(page=page, count=count)

Render Template

client.Templates.render_template(template_id, context=context)

Render and Send Template

client.Templates.send_template(template_id, from_email=from_email, from_name=from_name, subject=subject, to=to, context=context)

Update Template

client.Templates.update_template(template_id, name=name, html=html)

TrackIdentify

Identify Profile (Legacy)

client.TrackIdentify.identify_get(data)

Identify Profile

client.TrackIdentify.identify_post(data=data)

Track Profile Activity (Legacy)

client.TrackIdentify.track_get(data)

Track Profile Activity

client.TrackIdentify.track_post(data=data)

Appendix

Limitations

• The api_key is set at the global level: this means that if you manage multiple stores, you will need to run the code for each store in a different environment

Refresher on catching exceptions:

try:
    YOUR_CALL
except Exception as e:
    print(e.status)
    print(e.reason)
    print(e.body)
    print(e.headers)

Namespace

In the interest of making the SDK Pythonic, we made the following namespace changes relative to the language agnostic resources up top.

1. dashes - become underscores _
2. all other non-alphanumeric symbols, including spaces, are removed.

For example:

• get-campaigns becomes get_campaigns
• Track & Identify becomes TrackIdentify

Parameters & Arguments

The parameters follow the same naming conventions as the resource groups and operations.

We stick to the following convention for parameters/arguments

1. All parameters are passed as function args.
2. All optional params, as well as all Body and Form Data params (including required ones), are passed as keyword args.
3. All query and path params that are tagged as required in the docs are passed as positional args.
4. There is no need to pass in your private api_key for any operations, as it is defined upon client instantiation; public key is still required where.