> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

# Linking Klaviyo as a source

Canonical URL: https://posthog.com/docs/data-pipelines/sources/klaviyo

> **Cloud region:** This page uses US Cloud hosts. For an EU Cloud project, use `https://eu.posthog.com` instead of `https://us.posthog.com` or `https://app.posthog.com` (app host for links).

## On this page

- [Prerequisites](#prerequisites)
- [Adding a data source](#adding-a-data-source)
- [Sync modes](#sync-modes)
- [List profiles](#list-profiles)
- [Webhooks](#webhooks)
- [Configuration](#configuration)
- [Supported tables](#supported-tables)
- [Troubleshooting](#troubleshooting)

![](https://res.cloudinary.com/dmukukwp6/image/upload/texture_tan_9608fcca70)

![](https://res.cloudinary.com/dmukukwp6/image/upload/texture_tan_dark_a92b0e022d)

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.

`npx @posthog/wizard warehouse`

![PostHog Wizard hedgehog](https://res.cloudinary.com/dmukukwp6/image/upload/wizard_3f8bb7a240.png)

![](https://res.cloudinary.com/dmukukwp6/image/upload/wizard_3f8bb7a240.png)Let AI connect your sources for you

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](https://www.klaviyo.com/settings/account/api-keys) 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

1.  In PostHog, go to the [Sources tab](https://app.posthog.com/data-management/sources) of the data pipeline section.
2.  Click **\+ New source** and click **Link** next to this source.
3.  Enter your credentials (see [Configuration](#configuration) below) and click **Next**.
4.  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](https://posthog.com/docs/data-pipelines/sources.md#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
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
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](https://help.klaviyo.com/hc/en-us/articles/17655007276059). 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 | Description |
| --- | --- |
| `API key` **Type:** password **Required:** True |  |
| `Conversion metric ID (optional)` **Type:** text **Required:** False | Paste the ID of a value-tracking metric such as Placed Order from [your Klaviyo metrics](https://www.klaviyo.com/analytics/metrics). Engagement metrics such as opens and clicks are not eligible. Leave blank to auto-select one. Only the campaign and flow performance tables use it. |

## 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. Needs a value-tracking conversion metric (such as Placed Order); set one on the source if your account has none. 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. Needs a value-tracking conversion metric (such as Placed Order); set one on the source if your account has none. 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 51 weeks, one row per flow message per week. Needs a value-tracking conversion metric (such as Placed Order); set one on the source if your account has none. Conversion statistics use the conversion metric recorded in the conversion\_metric\_id column. 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. A form with no activity in the window is listed with zero counts and no submit rate. | 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 51 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 51 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](https://posthog.com/docs/data-warehouse/troubleshooting.md). If that doesn't help, [contact support](https://us.posthog.com/#panel=support%3Asupport%3Adata_warehouse%3A%3Atrue) – we're happy to help.