Linking Klaviyo as a source

Let AI connect your sources for you

Skip the manual setup — run this in your project and the wizard auto-detects your databases and APIs and connects them to PostHog.

Learn more

The Klaviyo connector syncs your marketing data – campaigns, profiles, events, flows, lists, and metrics – into PostHog, so you can analyze your email and marketing activity alongside your product data.

Prerequisites

You need a Klaviyo account and a private API key. Create one in your Klaviyo account settings by clicking Create Private API Key, giving it a name, and selecting a Read-Only Key. Grant read permissions for the data you want to sync: Accounts, Campaigns, Catalogs, Coupon codes, Coupons, Custom objects, Events, Flows, Forms, Images, Lists, Metrics, Profiles, Push tokens, Reviews, Segments, Tags, Templates, Web feeds, and Webhooks. Tables you haven't granted access to are skipped.

Adding a data source

In PostHog, go to the Sources tab of the data pipeline section.
Click + New source and click Link next to this source.
Enter your credentials (see Configuration below) and click Next.
Select the tables you want to sync, choose a sync method and frequency, then click Import.

Once the syncs are complete, you can start querying this data in PostHog.

When linking Klaviyo, you'll need:

API key – the private API key you created in your Klaviyo account settings (starts with pk_).

Sync modes

Each table can be synced in one of several modes, depending on what the source supports:

Webhook (when available) – the source pushes changes to PostHog in real time. Fastest freshness, lowest ongoing cost, and the only mode that reliably captures updates and deletes.
Incremental – only new or updated rows are synced on each run, using a cursor field (such as an updated_at timestamp). Cheaper than a full refresh, but deletes aren't captured.
Append only – new rows are appended using a cursor field; existing rows are never updated. Ideal for immutable, append-only tables like event logs.
Full refresh – the whole table is reloaded on every sync. Use it when a table has no reliable cursor or when you need deletions reflected.

See sync methods for a full explanation of how each mode works and how to choose between them.

The events table is append-only, since Klaviyo events are immutable. On the initial sync, only the last 365 days of events are imported.

List profiles

The opt-in list_profiles table maps which profiles belong to which list as {list_id, profile_id, joined_group_at} rows. This is disabled by default, but can be toggled on in the schema configuration when setting up or editing your Klaviyo source. It supports incremental sync on joined_group_at (the datetime when the profile most recently joined the list). Incremental syncs only pick up new joins and re-joins, and will not account for profiles removed from a list. A full refresh is required if profiles need to be removed. Once synced, you can join it with your profiles table:

SQL
Run in PostHog
SELECT p.*
FROM klaviyo_profiles p
JOIN klaviyo_list_profiles lp ON lp.profile_id = p.id
WHERE lp.list_id = 'your_list_id'

Note: List membership isn't the same as subscription. A profile can belong to a list without being subscribed to any of its communications. To check what a profile is actually subscribed to, look at the $consent array in the profile's properties column — it lists the channels (sms, email, and/or push) the profile currently consents to. Avoid relying on $consent_timestamp for this: it records when consent was given, but Klaviyo doesn't always clear it when a profile unsubscribes.

To find profiles that are on a list and actually subscribed to a given channel, filter on $consent too:

SQL
Run in PostHog
SELECT p.id, p.email
FROM klaviyo_profiles p
JOIN klaviyo_list_profiles lp ON lp.profile_id = p.id
WHERE lp.list_id = 'your_list_id'
  AND arrayExists(x -> x = 'email', JSONExtractArrayRaw(p.properties, '$consent'))

Webhooks

The webhooks table is only available to Klaviyo accounts with the Advanced KDP add-on. Without it, Klaviyo returns a 403 permission_denied error saying "You must have Advanced KDP enabled to use this endpoint," even when your API key has the Webhooks read scope. This table is disabled by default. Only enable it if your Klaviyo account includes Advanced KDP.

Configuration

Option	Type	Required
`API key`	password	Yes
`Conversion metric ID (optional)`	text	No

Supported tables

Table	Description	Sync method	Incremental field	Primary key
`email_campaigns`	An email marketing campaign in Klaviyo sent to a target audience.	Incremental, Full refresh	updated_at, created_at	—
`sms_campaigns`	An SMS marketing campaign in Klaviyo sent to a target audience.	Incremental, Full refresh	updated_at, created_at	—
`events`	Only syncs the last 365 days on initial sync	Append only, Full refresh	datetime	—
`flows`	An automated flow in Klaviyo that sends messages based on triggers and conditions.	Incremental, Full refresh	updated, created	—
`lists`	A list of profiles in Klaviyo used to target campaigns and flows.	Incremental, Full refresh	updated, created	—
`metrics`	A metric in Klaviyo that defines a type of tracked event (e.g. Placed Order, Opened Email).	Incremental, Full refresh	—	—
`profiles`	Includes each profile's subscriptions object by default: consent status per channel (email, sms, push), global email suppressions in subscriptions.email.marketing.suppression, and per-list email suppressions in subscriptions.email.marketing.list_suppressions	Incremental, Full refresh	updated, created	—
`list_profiles`	Maps which profiles belong to which list as {list_id, profile_id, joined_group_at} rows. Incremental syncs pick up new joins and re-joins; profiles removed from a list are only reflected on a full refresh. List membership is not the same as subscription: check the $consent array in the profiles table's properties column to see which channels (sms, email, push) a profile is currently subscribed to. Per-list email suppressions are in the profiles table's subscriptions column, under email.marketing.list_suppressions	Incremental, Full refresh	joined_group_at	—
`segment_profiles`	Maps which profiles belong to which segment as {segment_id, profile_id, joined_group_at} rows. Segments are recomputed by Klaviyo, so profiles that no longer match are only removed on a full refresh	Incremental, Full refresh	joined_group_at	—
`segments`	A segment in Klaviyo: a dynamic group of profiles that matches a set of conditions.	Incremental, Full refresh	updated, created	—
`flow_actions`	One row per step in a flow, carrying the flow_id it belongs to	Incremental, Full refresh	updated, created	—
`flow_messages`	One row per message sent by a flow step, carrying the flow_action_id and flow_id it belongs to. Opt-in: it walks every action of every flow	Incremental, Full refresh	updated, created	—
`campaign_values_reports`	Klaviyo's own computed performance statistics per campaign message over the last 365 days, replaced in full on every sync. Conversion statistics use the conversion metric recorded in the conversion_metric_id column	Incremental, Full refresh	—	—
`flow_values_reports`	Klaviyo's own computed performance statistics per flow message over the last 365 days, replaced in full on every sync. Conversion statistics use the conversion metric recorded in the conversion_metric_id column	Incremental, Full refresh	—	—
`flow_series_reports`	Klaviyo's own flow-message performance statistics bucketed by week over the last 52 weeks, one row per flow message per week. Weeks stay in the table after Klaviyo stops returning them	Incremental, Full refresh	date_time	—
`form_values_reports`	Klaviyo's own signup-form performance statistics per form over the last 365 days, replaced in full on every sync	Incremental, Full refresh	—	—
`segment_values_reports`	Klaviyo's own segment membership statistics per segment over the last 365 days (members added, removed, net change, and total). Replaced in full on every sync	Incremental, Full refresh	—	—
`form_series_reports`	Klaviyo's own signup-form performance statistics bucketed by week over the last 52 weeks, one row per form per week. Weeks stay in the table after Klaviyo stops returning them	Incremental, Full refresh	date_time	—
`segment_series_reports`	Klaviyo's own segment membership statistics bucketed by week over the last 52 weeks, one row per segment per week. Weeks stay in the table after Klaviyo stops returning them	Incremental, Full refresh	date_time	—
`templates`	A reusable email template in Klaviyo that campaigns and flow messages render from.	Incremental, Full refresh	updated, created	—
`forms`	A signup form in Klaviyo that collects profiles from your site.	Incremental, Full refresh	updated_at, created_at	—
`reviews`	A product review collected by Klaviyo Reviews.	Incremental, Full refresh	created	—
`images`	An image uploaded to your Klaviyo image library.	Incremental, Full refresh	updated_at	—
`web_feeds`	A web feed Klaviyo fetches to render dynamic content in messages.	Incremental, Full refresh	updated, created	—
`catalog_items`	A product in your Klaviyo catalog, used for product feeds, blocks, and attribution.	Incremental, Full refresh	—	—
`catalog_variants`	A variant of a catalog item, such as a specific size or color.	Incremental, Full refresh	—	—
`catalog_categories`	A category that groups catalog items together.	Incremental, Full refresh	—	—
`coupons`	A coupon in Klaviyo that unique codes are issued from.	Incremental, Full refresh	—	—
`coupon_codes`	A unique coupon code assigned to a profile.	Incremental, Full refresh	—	—
`tags`	A tag used to organize Klaviyo campaigns, flows, lists, and segments.	Incremental, Full refresh	—	—
`tag_groups`	A group that the tags in your account belong to.	Incremental, Full refresh	—	—
`push_tokens`	A push notification token registered against a profile's device.	Incremental, Full refresh	—	—
`data_sources`	A source that feeds custom object data into Klaviyo.	Incremental, Full refresh	—	—
`custom_metrics`	A custom metric in Klaviyo, defined by combining and filtering other metrics.	Incremental, Full refresh	—	—
`object_types`	A custom object type defined in Klaviyo, describing the shape of records you send it.	Incremental, Full refresh	—	—
`webhooks`	Requires Klaviyo's Advanced KDP add-on	Incremental, Full refresh	—	—
`accounts`	Your Klaviyo account's settings, including its timezone and preferred currency.	Incremental, Full refresh	—	—
`custom_object_records`	One row per custom object record, carrying the object_type_id it belongs to	Incremental, Full refresh	—	—

Troubleshooting

If your sync is failing or data looks wrong, see the Data warehouse troubleshooting guide. If that doesn't help, contact support – we're happy to help.