Klaviyo Python SDK

Common errors

• klaviyo_api.exceptions.KlaviyoApiException: (401) Unauthorized

  cause 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

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

Warnings

• breaking The `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`.
• gotcha Klaviyo 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.
• gotcha Klaviyo 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.

Install

• pip install klaviyo-api Install stable version

Imports

• KlaviyoAPI

  from klaviyo_api import KlaviyoAPI

Quickstart

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}")