Klaviyo

This connector uses the Klaviyo REST API revision 2024-10-15 (current stable).

Setup:

1. Sign in to Klaviyo → bottom-left avatar → Settings → API Keys → Create Private API Key.
2. Set scopes — at minimum: Profiles (Full), Lists (Full), Segments (Read), Events (Full), Catalogs (Read), Campaigns (Read), Flows (Read).
3. Copy the key. It's prefixed with pk_. Set KLAVIYO_PRIVATE_API_KEY.

Authentication: Authorization: Klaviyo-API-Key ${KLAVIYO_PRIVATE_API_KEY} (the literal prefix is Klaviyo-API-Key, NOT Bearer). The adapter sets this via API_KEY + custom apiKey value.

Revision header: every request MUST include revision: 2024-10-15. The adapter pins this in connector.headers. If you upgrade revision, expect breaking changes — read https://developers.klaviyo.com/en/docs/api_versioning_and_deprecation_policy.

JSON:API spec: Klaviyo follows JSON:API for resource shape. Every response: {data: {id, type, attributes, relationships}, links, meta}. Use ?include= (comma-separated) to side-load related resources in one call.

Filtering syntax: Klaviyo uses a custom filter DSL on most list endpoints. Example: ?filter=equals(properties,{'$source':'newsletter'}) or ?filter=greater-than(created,2025-01-01T00:00:00Z). The adapter exposes common filters as explicit query params.

Profile model: Klaviyo's central object. Each profile has email, phone_number, external_id, plus arbitrary properties (custom fields). Profiles are upserted by email/phone/external_id — you cannot have duplicates on the same identifier.

Events: the heart of Klaviyo's behavioral targeting. Send events via klaviyo_create_event with a profile identifier + a metric name (e.g. 'Placed Order') + properties. Klaviyo automatically creates the metric if it doesn't exist. Events drive flows (triggered automations) — sending the right events at the right time is 80% of Klaviyo work.

Pagination: cursor-based via page[cursor] (response includes links.next with the cursor). page[size] is typically 20 default, 100 max.

Lists vs Segments: lists are static (manually-managed subscribers). Segments are dynamic queries (recompute every few minutes). Use lists for opt-in newsletters, segments for behavioral cohorts ('opened a campaign in last 30 days').

Rate limits: vary per endpoint. Profile reads: 75/sec burst, 700/min steady. Profile writes: 150/min. Klaviyo returns 429 with Retry-After — honor it.

Webhooks out of scope (use Klaviyo's UI to configure event webhooks to your hosted endpoint).

Out of scope here: sending individual emails via the legacy track/identify endpoints (use the Events API + flows instead), template editing, image library, reviews, the older v1/v2 REST API.