> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/marketing/klaviyo.md).
# Klaviyo
Connect Klaviyo to Google Sheets, BigQuery, or Looker Studio via Coupler.io. Export campaigns, profiles, flows, and performance data automatically without manua
Klaviyo is an email and SMS marketing platform for customer engagement and automation. It tracks customer behavior, segments audiences, and powers campaigns and automated flows. Connecting Klaviyo to Coupler.io lets you pull that data into your reporting stack automatically — no manual exports needed.
**Why connect Klaviyo to Coupler.io?**
* Export campaigns, flows, profiles, segments, forms, and performance reports on a schedule
* Send data to Google Sheets, BigQuery, Looker Studio, Excel, or AI tools like ChatGPT and Gemini
* Combine Klaviyo data with other sources — ads platforms, CRMs, e-commerce stores, or other sending tools — using Join or Append transformations
* Build live dashboards without writing a single line of code
**Prerequisites**
* A Klaviyo account (any plan)
* A Klaviyo Private API key with read permissions for the entities you want to export
* A Coupler.io account
## Quick start
{% hint style="success" %}
For campaign or flow performance metrics (opens, clicks, revenue), use the **Campaign performance report** or **Flow performance report** entity. For account-wide event trends, use **Metrics analytics**. For a flat list of your campaigns, profiles, or other objects, use the corresponding core entity.
{% endhint %}
{% stepper %}
{% step %}
**Create a new data flow.** In Coupler.io, click **Add data flow**. Search for and select **Klaviyo** as your source.
{% endstep %}
{% step %}
**Enter your Klaviyo API key.** In Klaviyo, go to **Settings → API Keys** and create a new Private API key. Give it at least read access to the data you need, then paste the key into Coupler.io.
{% endstep %}
{% step %}
**Choose an entity.** Select from the available entities. Report entities (Metrics analytics, Campaign performance report, Flow performance report, Segment performance report, Forms performance report) require a date range and metric selection. Core entities (Campaigns, Profiles, Flows, Segments, Forms) are full exports.
{% endstep %}
{% step %}
**Choose a destination.** Connect a destination — Google Sheets, BigQuery, Looker Studio, Excel, or an AI tool like ChatGPT or Claude — and configure where you want the data to land.
{% endstep %}
{% step %}
**Run the data flow.** Click **Run** to do a manual run and confirm your data loads correctly.
{% endstep %}
{% endstepper %}
## Available entities
| Entity | What it contains |
| --------------------------- | --------------------------------------------------------------------------------------------- |
| Metrics analytics | Event aggregates for any standard or custom metric, broken down by dimensions you choose |
| Campaign performance report | Delivery, engagement, conversion, and revenue stats grouped by campaign |
| Flow performance report | Delivery, engagement, conversion, and revenue stats grouped by flow, with time-series support |
| Segment performance report | Segment membership stats (total members, adds, removes) over time |
| Forms performance report | Sign-up form funnel stats (views, submits, closures) over time |
| Campaigns | All campaigns with status, channel, send time, and list/segment info |
| Profiles | All subscriber profiles with contact info, consent status, and predictive analytics |
| Flows | All automated flows with trigger, status, and channel details |
| Segments | All segments with definition, active status, and membership metadata |
| Forms | All sign-up forms with status and A/B test configuration |
## Klaviyo data overview
Klaviyo exposes nine entities through Coupler.io, split into two groups: reports (performance data you configure with metrics and dimensions) and core entities (flat exports of your account objects).
## Entities at a glance
| Entity | Group | Best for |
| --------------------------- | ------------- | --------------------------------------------------------------------- |
| Metrics analytics | Reports | Account-wide event tracking — any standard or custom metric over time |
| Campaign performance report | Reports | Aggregated campaign stats: delivery, engagement, conversions, revenue |
| Flow performance report | Reports | Aggregated flow stats: delivery, engagement, conversions, revenue |
| Segment performance report | Reports | Segment membership trends: total members, adds, removes |
| Forms performance report | Reports | Sign-up form funnel: views, submits, closures, qualified leads |
| Campaigns | Core entities | Campaign metadata — status, channel, scheduling, send options |
| Profiles | Core entities | Subscriber data — contact info, consent, predictive analytics |
| Flows | Core entities | Automation structure — trigger, status, channel |
| Segments | Core entities | Segment definitions and active status |
| Forms | Core entities | Form configurations and A/B test setup |
***
## Reports
### Metrics analytics
Metrics analytics aggregates event data (counts, sums, unique users) for any standard or custom metric in your Klaviyo account. Use it to track total volume and growth for events like "Placed Order" or "Opened Email" across all channels.
#### Metrics (loaded from your account)
Metrics are dynamic — they come from your Klaviyo account's metric library. Common built-in metrics include Opened Email, Clicked Email, Placed Order, and any custom events you track. Select up to 10 metrics per data flow.
#### Dimensions
| Dimension | Description |
| --------------------- | ------------------------------------------ |
| Message | Message ID |
| Message name | Human-readable message name |
| Message type | Campaign or flow message |
| Attributed message | Message credited for the conversion |
| Flow | Flow ID |
| Attributed flow | Flow credited for the conversion |
| Variation | A/B test variation |
| Attributed variation | Variation credited for the conversion |
| Message send cohort | Cohort based on send date |
| Variation send cohort | Cohort based on variation send date |
| Campaign channel | Email or SMS |
| Flow channel | Email or SMS |
| Attributed channel | Channel credited for the conversion |
| Campaign name | Name of the parent campaign |
| Subject | Email subject line |
| Email domain | Recipient email domain |
| URL | Specific link clicked |
| List | List or segment used |
| Form ID | Sign-up form attributed to a profile |
| Method | Delivery method |
| Client canonical | Standardized client identifier |
| Client name | Email client (e.g., Gmail, Outlook) |
| Client type | Client category (mobile, desktop, webmail) |
| Bounce type | Hard or soft bounce |
| Failure type | Reason for delivery failure |
| Failure source | System that reported the failure |
| From number | Sending phone number |
| From phone region | Region of the sending number |
| To number | Recipient phone number |
| To phone region | Region of the recipient number |
| Usage amount | Usage quantity |
| Value currency | Currency of the conversion value |
| Bot click | Whether click was bot-generated |
| Inbox provider | Recipient's inbox provider |
| Segment count | SMS segment count |
#### Period granularity
Hour, Day, Week, or Month.
***
### Campaign performance report
Returns aggregated delivery, engagement, and conversion data for campaigns over a selected date range. Results are always grouped by Campaign ID and Campaign Message ID. You can add up to 3 optional dimensions for deeper breakdowns.
This report always returns totals for the full date range (no time series).
#### Standard campaign metrics
| Group | Metric | Description |
| ------------------- | ---------------------- | --------------------------------- |
| Delivery | Recipients | Total intended recipients |
| Delivery | Delivered | Emails/SMS successfully delivered |
| Delivery | Delivery rate | Delivered ÷ recipients |
| Email engagement | Opens | Total email opens |
| Email engagement | Unique opens | Deduplicated opens per recipient |
| Email engagement | Open rate | Unique opens ÷ delivered |
| Email engagement | Clicks | Total link clicks |
| Email engagement | Unique clicks | Deduplicated clicks per recipient |
| Email engagement | Click rate | Unique clicks ÷ delivered |
| Email engagement | Click-to-open rate | Unique clicks ÷ unique opens |
| Bounces & failures | Bounced | Emails that bounced |
| Bounces & failures | Bounce rate | Bounced ÷ sent |
| Bounces & failures | Failed | Messages that failed to send |
| Bounces & failures | Failed rate | Failed ÷ sent |
| Bounces & failures | Bounced or failed | Combined bounce + failure count |
| Bounces & failures | Bounced or failed rate | Combined rate |
| List health | Unsubscribes | Recipients who opted out |
| List health | Unique unsubscribes | Deduplicated unsubscribes |
| List health | Unsubscribe rate | Unsubscribes ÷ delivered |
| List health | Spam complaints | Recipients who marked as spam |
| List health | Spam complaint rate | Spam complaints ÷ delivered |
| Revenue & orders | Average order value | Revenue ÷ conversions |
| Revenue & orders | Revenue per recipient | Revenue ÷ recipients |
| Audience / segments | Segment size (sum) | Sum of SMS segment counts |
| SMS | SMS credit usage | SMS credits consumed |
| SMS | SMS spend | Cost of SMS sends |
| SMS | SMS ROI | Revenue ÷ SMS spend |
#### Conversion metrics
Select one or more Klaviyo events (e.g., Placed Order, Custom Event) to track as conversions. For each selected metric, the report adds four columns:
* `[Metric name] - total` — total conversion count
* `[Metric name] - rate` — conversions ÷ recipients
* `[Metric name] - unique` — unique converters
* `[Metric name] - value` — attributed revenue (only if the metric tracks a $value property)
#### Optional dimensions
| Dimension | Description |
| ------------------- | ------------------------------------- |
| Group | Campaign group |
| Send channel | Email, SMS, or push |
| Tag ID | ID of the tag applied to the campaign |
| Tag name | Name of the tag |
| Text message format | SMS message format |
| Variation | A/B test variation |
***
### Flow performance report
Returns aggregated delivery, engagement, and conversion data for automated flows. Results are always grouped by Flow ID and Flow Message ID. Supports time-series breakdowns.
#### Standard flow metrics
Same metric set as the Campaign performance report (see table above).
#### Conversion metrics
Same behavior as Campaign performance report — select Klaviyo events; each adds total, rate, unique, and value columns.
#### Optional dimensions
| Dimension | Description |
| ------------------- | ------------------------------------------- |
| Flow name | Human-readable flow name |
| Flow message name | Human-readable message name within the flow |
| Send channel | Email, SMS, or push |
| Tag ID | ID of the tag applied to the flow |
| Tag name | Name of the tag |
| Text message format | SMS message format |
| Variation | A/B test variation |
| Variation name | Human-readable variation name |
#### Period granularity
Hourly, Daily, Weekly, Monthly, or Total only. Coupler.io automatically splits the request into intervals per granularity (7 days for hourly, 60 days for daily, 365 days for weekly/monthly) — you can set any date range and Coupler.io handles the pagination.
***
### Segment performance report
Returns membership statistics for your segments over a selected date range. Data is always grouped by Segment ID. Supports time-series breakdowns.
#### Metrics
| Group | Metric | Description |
| ------------------ | ------------------- | ----------------------------------- |
| Segment membership | Total members | Total profiles in the segment |
| Segment membership | Members added | Profiles that joined the segment |
| Segment membership | Members removed | Profiles that left the segment |
| Segment membership | Net members changed | Members added minus members removed |
#### Period granularity
Hourly, Daily, Weekly, Monthly, or Total only.
***
### Forms performance report
Returns performance statistics for your Klaviyo sign-up forms over a selected date range. Results are always grouped by Form ID. Supports time-series breakdowns.
#### Metrics
| Group | Metric | Description |
| ---------------- | ------------------------ | ------------------------------------ |
| Form views | Form views | Total form impressions |
| Form views | Unique form views | Deduplicated views per visitor |
| Form views | Form step views | Total views of individual form steps |
| Form views | Unique form step views | Deduplicated form step views |
| Form submissions | Submits | Total form submissions |
| Form submissions | Submit rate | Submits ÷ unique form views |
| Form submissions | Form step submits | Total step-level submissions |
| Form submissions | Unique form step submits | Deduplicated step-level submissions |
| Form engagement | Closed forms | Forms dismissed without submitting |
| Form engagement | Unique closed forms | Deduplicated form closures |
| Form engagement | Qualified forms | Forms shown to qualified visitors |
| Form engagement | Unique qualified forms | Deduplicated qualified form shows |
#### Optional dimensions
| Dimension | Description |
| --------------- | ------------------------------------- |
| Form version ID | Specific form version (for A/B tests) |
#### Period granularity
Hourly, Daily, Weekly, Monthly, or Total only.
***
## Core entities
### Campaigns
Full export of all campaigns across email, SMS, and mobile push channels.
| Field | Description |
| ----------------- | -------------------------------------------- |
| id | Campaign ID |
| name | Campaign name |
| status | Draft, Scheduled, Sent, Cancelled, etc. |
| archived | Whether the campaign is archived |
| message | ID of the associated campaign message |
| audiences | Included and excluded lists/segments |
| send\_options | Smart sending flag |
| tracking\_options | Open and click tracking settings |
| send\_strategy | Method, scheduled datetime, and send options |
| created\_at | Creation timestamp |
| scheduled\_at | Scheduled send timestamp |
| updated\_at | Last update timestamp |
| send\_time | Actual send timestamp |
### Profiles
Full export of all subscriber profiles. Includes contact info, location, consent status for email and SMS, and predictive analytics fields.
Key predictive analytics fields: `historic_clv`, `predicted_clv`, `total_clv`, `historic_number_of_orders`, `churn_probability`, `expected_date_of_next_order`.
Use the **Advanced filters** option to limit the export to a specific segment, list, or consent status.
### Flows
Full export of all automated flows. Schema is dynamic — fields depend on your flow configuration.
### Segments
Full export of all segments in your account.
| Field | Description |
| -------------- | ----------------------------------------- |
| id | Segment ID |
| name | Segment name |
| definition | Segment conditions and logic |
| created | Creation timestamp |
| updated | Last update timestamp |
| is\_active | Whether the segment is currently active |
| is\_processing | Whether the segment is being calculated |
| is\_starred | Whether the segment is starred in Klaviyo |
### Forms
Full export of all sign-up forms in your account.
| Field | Description |
| ----------- | --------------------------------------- |
| id | Form ID |
| name | Form name |
| status | Published, Draft, etc. |
| ab\_test | Whether the form has an active A/B test |
| created\_at | Creation timestamp |
| updated\_at | Last update timestamp |
***
## Use cases by role
{% tabs %}
{% tab title="Email marketers" %}
* Use **Campaign performance report** to get delivery, engagement, and conversion metrics per campaign in one flat table — no manual report building in Klaviyo
* Compare subject line performance by adding the Variation dimension to the Campaign performance report
* Pull **Campaigns** (core entity) to audit campaign status, scheduling, and targeting settings across your account
{% endtab %}
{% tab title="E-commerce teams" %}
* Use **Campaign performance report** or **Flow performance report** with a Placed Order conversion metric to track email- and SMS-driven revenue
* Use **Segment performance report** to monitor list growth and churn across your key audience segments
{% endtab %}
{% tab title="Marketing analysts" %}
* Use **Metrics analytics** for account-wide event trend analysis — break any metric by message, list, or channel dimension
* Use **Forms performance report** to build a sign-up funnel: views → qualified → submits, split by day or week
* Send any report entity to ChatGPT or Claude for AI-assisted analysis and recommendations
{% endtab %}
{% endtabs %}
## Platform-specific notes
* **Campaign performance report** always returns totals — it does not support time-series breakdowns
* **Metrics analytics** supports multi-year date ranges. Data cannot go further back than 5 years from today.
* **Revenue and conversion columns** in performance reports only populate when the conversion metric is actively tracked and attributed in your Klaviyo account
* Revenue attribution in Klaviyo follows its own attribution window — numbers may differ from your e-commerce platform's reported revenue
* SMS metrics (SMS spend, SMS ROI, SMS credit usage) only return data if you use Klaviyo SMS
## Klaviyo common issues
### Connection issues
API key is rejected or returns a permission error
There are two common causes:
**Wrong key type** — Klaviyo's Public API key is designed for client-side event tracking only and has no read access to account data. Make sure you're using a **Private API key**. In Klaviyo, go to **Settings → API Keys** and create a new Private key.
**Missing scope permissions** — Private API keys in Klaviyo have granular read/write permissions per resource. If the key exists but a specific entity fails, check that read access is enabled for the resources you need (Campaigns, Profiles, Metrics, Flows, Segments, Forms). You can review and update permissions on the key's settings page in Klaviyo.
### Data discrepancies
Metrics analytics numbers don't match what I see in Klaviyo's Reports
This is expected. Metrics analytics uses Klaviyo's metric aggregates API, which processes raw event counts differently from Klaviyo's own reporting engine. Klaviyo's documentation [explicitly notes](https://developers.klaviyo.com/en/reference/query_metric_aggregates) that metric aggregates are not designed to match the UI. If you need numbers that align with what Klaviyo shows in its Reports section, use the **Campaign performance report**, **Flow performance report**, **Segment performance report**, or **Forms performance report** entities instead — those use the Klaviyo Reporting API and return the same data as the UI.
### Missing data
Placed orders or revenue columns are empty
Revenue and order metrics are only populated when Klaviyo has attributed those events to a message. If your Klaviyo account hasn't tracked placed order events — or if the attribution window hasn't closed yet — these columns will be blank. Confirm that your Klaviyo account has the **Placed Order** metric configured and that the integration with your store (e.g., Shopify) is active.
## Klaviyo FAQ
Where do I find my Klaviyo API key?
In Klaviyo, go to **Settings → API Keys**. Click **Create Private API Key**, give it a name, and set the appropriate read permissions for the data you want to export (e.g., Campaigns, Profiles, Metrics). Copy the key and paste it into Coupler.io when prompted. Do not use your Public API key — it won't work for data exports.
What's the difference between Campaigns and the Campaign performance report?
The **Campaigns** entity returns metadata about your campaigns — name, channel, status, send time, target lists — but no performance numbers. The **Campaign performance report** returns performance metrics (opens, clicks, conversions, revenue, etc.) grouped by campaign and message. Use Campaigns to audit your campaign setup, and Campaign performance report to measure results.
What's the difference between Campaign performance report, Flow performance report, and Metrics analytics?
They serve different reporting needs and use different Klaviyo APIs:
* **Campaign performance report** — aggregated stats per campaign (delivery, engagement, conversions). Always returns totals, no time series. Uses the Klaviyo Reporting API — numbers match what you see in the Klaviyo UI.
* **Flow performance report** — same stats but for automated flows, with time-series support (hourly, daily, weekly, monthly). Also uses the Reporting API — UI-aligned.
* **Metrics analytics** — account-wide event aggregation for any standard or custom metric. Uses the metric aggregates API, which processes raw events differently from Klaviyo's reporting engine — results will not match the Klaviyo UI. Use this when you need event-level trends not tied to a specific campaign or flow.
How do conversion metrics work in the Campaign and Flow performance reports?
You select one or more Klaviyo events (e.g., Placed Order) as your conversion metric. For each event you select, the report adds four columns: `[Metric name] - total` (count), `[Metric name] - rate` (conversions ÷ recipients), `[Metric name] - unique` (unique converters), and `[Metric name] - value` (attributed revenue, only if the event tracks a dollar value). If the value column is empty, the metric doesn't have a $value property in Klaviyo.
Why is my revenue or "Placed Orders" column empty?
Revenue and order data in Klaviyo only appears when the Placed Order event is actively tracked in your account and attributed to a message. Check that your Klaviyo integration with your store (e.g., Shopify) is enabled and that the Placed Order metric exists under **Analytics → Metrics**. If the metric isn't there, the column will always be empty.
Can I pull data from multiple Klaviyo accounts into one report?
Yes. Add each Klaviyo account as a separate source within the same data flow, each with its own API key. Then use Coupler.io's **Append** transformation to merge all the data into a single dataset. This is the recommended approach for agencies managing multiple brands.
Can I export more than one year of Metrics analytics data?
Yes. Coupler.io automatically splits large date ranges into smaller intervals and reassembles the results, so you can set any date range without hitting the API's per-request limit. The only hard constraint is that data older than 5 years is not available through the Klaviyo API.
Can I use Klaviyo data with AI tools?
Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw. You can send your Klaviyo Report data directly to these tools for automated analysis, recommendations, or content generation based on your email performance.
{% hint style="info" %}
For a full breakdown of available metrics and dimensions, see [Data Overview](#klaviyo-data-overview). For known issues and errors, see [Common Issues](#klaviyo-common-issues). For setup and optimization tips, see [Best Practices](/sources/category/marketing/klaviyo/best-practices.md).
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.coupler.io/sources/category/marketing/klaviyo.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.