Registry / communication / klaviyo-api

klaviyo-api

JSON →
library23.0.0pypypi✓ verified 84d ago

The Klaviyo Python SDK provides a convenient way to interact with the Klaviyo API for marketing automation, customer data management, and more. It offers full coverage of the Klaviyo API, including profiles, events, campaigns, flows, and more. The library is actively maintained with monthly releases, often aligned with new Klaviyo API revisions.

pip install klaviyo-api
INSTALL
IMPORT
SIG · KLAVIYO-API
K
klaviyo-api
communicationpythonv23.0.0
Install
5.2s avg
Import
68ms
Disk
55MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v23.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.071s · 51MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 5.2s · import 0.064s · 51MB
55MB installed
● package 55MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

KlaviyoAPI
from klaviyo_api import KlaviyoAPI

This quickstart demonstrates how to initialize the Klaviyo API client using a private API key from an environment variable and make a simple request to retrieve account information. Ensure your API key has the necessary scopes (e.g., 'Accounts' read scope) for the endpoints you wish to use.

import os from klaviyo_api import KlaviyoAPI from klaviyo_api.exceptions import KlaviyoApiException # Retrieve your Klaviyo Private API Key from environment variables. # You can find your API keys in Klaviyo Settings -> API Keys. # It should start with 'pk_'. KLAVIYO_PRIVATE_API_KEY = os.environ.get('KLAVIYO_PRIVATE_API_KEY', '') if not KLAVIYO_PRIVATE_API_KEY: print("Error: KLAVIYO_PRIVATE_API_KEY environment variable not set. Please set it to your Klaviyo Private API Key.") exit(1) try: # Initialize the Klaviyo API client klaviyo = KlaviyoAPI(api_key=KLAVIYO_PRIVATE_API_KEY) # Example: Get account information (requires 'Accounts' scope) # Make sure your API key has the necessary permissions. response = klaviyo.Accounts.get_accounts() if response.status_code == 200: print("Successfully connected to Klaviyo API.") print(f"Account ID: {response.body['data'][0]['id']}") print("First Account Name: ", response.body['data'][0]['attributes']['name']) else: print(f"Error connecting to Klaviyo API: {response.status_code} - {response.body}") except KlaviyoApiException as e: print(f"Klaviyo API Error: {e.status_code} - {e.body}") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingThe `anonymous_id` field was removed from profile payloads in version `22.0.0`. If you were previously including `anonymous_id` when creating or updating profiles, your requests will now fail or behave unexpectedly.
fix
Remove `anonymous_id` from any profile creation or update payloads. Use other identifiers like `email`, `phone_number`, or `external_id`.
affects: >=22.0.0
gotchaKlaviyo API keys have different types (Public, Private, Client-side) and specific scopes (permissions). Using the wrong type of key or a key without sufficient permissions for an endpoint will result in `401 Unauthorized` or `403 Forbidden` errors.
fix
Always use a Private API Key for server-side SDK interactions. Verify that the generated Private API Key has all the necessary scopes (e.g., 'Profiles' write, 'Events' write, etc.) for the API calls you intend to make.
affects: All
gotchaKlaviyo APIs are subject to rate limits. Exceeding these limits will result in `429 Too Many Requests` errors. Specific endpoints might have different tiers (e.g., Conversations API uses the 'SMALL' tier: 3 requests/second burst, 60 requests/minute steady).
fix
Implement exponential backoff and retry logic for API calls. Consult the Klaviyo API documentation for specific rate limits per endpoint. Distribute requests over time or use bulk endpoints where available.
affects: All
Errors
Common errors & fixes
klaviyo_api.exceptions.KlaviyoApiException: (401) Unauthorized
The API key provided is either incorrect, invalid, or does not have the necessary permissions (scopes) for the requested operation.
fix
Double-check your `KLAVIYO_PRIVATE_API_KEY` value. Ensure it's a Private API Key, not a Public API Key. Go to Klaviyo Settings -> API Keys to generate a new key with appropriate scopes for your needs.
TypeError: Object of type 'UUID' is not JSON serializable
Some data types, like `UUID` objects, are not directly JSON serializable, but the SDK expects JSON-compatible values for request bodies. This commonly occurs when passing Python objects directly without conversion.
fix
Before sending data to Klaviyo API, ensure all values in your payload are JSON serializable. Convert `UUID` objects to strings (`str(my_uuid_object)`) and `datetime` objects to ISO 8601 strings.
Upgrade
Version history
23.0.0latest on PyPI · released Apr 15, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
38 hits · last 30 days
node
34
OpenAI (training)
1
Resources
klaviyo-api — pip install klaviyo-api · libregistry