Skip to main content

​
Introduction

Klaviyo is a marketing-automation platform built for e-commerce, focused on email and SMS campaigns with deep e-commerce attribution. Its data model centers on Lists and Segments (audience definitions), Flows (event-triggered automations), Campaigns (one-off sends), and Forms (on-site sign-up captures). Klaviyo records every customer interaction as a metric — placed orders, viewed products, started checkout, opened email — which powers both segmentation and reporting. This data source is the metric-aggregate variant. It queries Klaviyo’s metric-aggregates endpoint live and can report any event metric in the account, broken down by event property. Because it aggregates by the time each event occurred, it is best for flexible cross-metric analysis — comparing engagement and revenue events alongside paid-media spend — rather than reproducing Klaviyo’s in-app campaign and flow reports. For send-date-aligned campaign, flow, and form reporting that matches Klaviyo’s UI, use the separate Klaviyo Reporting data reference. As an email-marketing connector, engagement and revenue metrics are standardized so widgets can aggregate alongside ad-platform sources without additional configuration. To connect this data source, see How to connect Klaviyo to Adriel.

​
Data refresh strategy

​
Architecture data

Catalogs of lists, segments, flows, campaigns, and forms are fetched on demand when a dashboard loads. There is no daily architecture sync — entities created in Klaviyo become available immediately.

​
Reports data

Report data is read from Klaviyo’s metric-aggregates endpoint on demand on every dashboard load, so send, open, click, and conversion counts always reflect the current state in Klaviyo. There is no daily cache. Event-time attribution. Dates are filtered and grouped by the time each event occurred, not by the campaign or flow send date. An email sent before the selected date range can therefore contribute to results inside the range if its opens, clicks, or conversions land there. This differs from Klaviyo’s in-app reports, which are calculated on send date, so totals may not match. For send-date-aligned figures, use the Klaviyo Reporting data reference.

​
Architecture levels

Account → List / Segment → Flow / Campaign / Form → Message → Event
  • Account — a single Klaviyo account authorized via a private API key.
  • List / Segment — a list is an explicit subscriber group; a segment is a dynamic, rule-based audience.
  • Flow / Campaign / Form — a flow is an automated, event-triggered series; a campaign is a single send; a form is an on-site sign-up capture.
  • Message — an individual email or SMS within a flow or campaign.
  • Event — a single recipient action (opened, clicked, placed order, started checkout, and so on).

​
Date range limits

The connector fetches a maximum of 1 year of data per query; requests for a wider range are truncated to the most recent year. When a query includes no date breakdown, results are aggregated at a monthly interval by default.

​
Metrics

How to read the columns Data type uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. API Key in code style like klaviyo:Opened Email is the connector’s field name for a Klaviyo event metric (event metric names carry the klaviyo: prefix). Italic text describes how a value is produced when it doesn’t map cleanly to a single event metric.
Metrics are built from the account’s metric catalog. This variant can report any metric Klaviyo tracks for the account, and each metric is available in three aggregations — count (total events), unique (distinct profiles), and value (monetary total, for metrics that carry a value such as Placed Order). The metrics below are common examples; the exact catalog varies by account.

​
Email & SMS engagement

​
Revenue & conversions

​
Contacts & sign-ups

​
Breakdowns

When a record has no value for the chosen breakdown property, it appears under the bucket Unassigned rather than being excluded. Date breakdowns default to a monthly interval when no other date grouping is applied.

​
Campaigns & flows

​
Messages & variations

​
Contacts & audience

​
Delivery & engagement

​
SMS

​
Time

These groupings are provided by Adriel rather than returned as Klaviyo event properties.

​
Limitations

  • Event-time attribution, not send date — dates are grouped by when each event occurred, so totals may not match Klaviyo’s in-app campaign and flow reports, which use send date. Use the Klaviyo Reporting data reference for send-date-aligned figures.
  • 1-year query window — a single query fetches at most one year of data; wider ranges are truncated to the most recent year.
  • Account-specific metric catalog — available metrics come from the account’s own Klaviyo metric catalog, each in count, unique, and value aggregations. Metrics not tracked in the account are not available.
  • Empty breakdown values bucket as “Unassigned” — records with no value for the selected property are grouped under Unassigned rather than dropped.
  • Rate limits may slow first render — metric-aggregate requests are throttled to 1 request per 500 ms shared across all accounts, with up to 10 sub-queries per request; a single page of results is returned per sub-query, so very large dashboards can take longer to render the first time.
  • No token refresh — authentication uses a private API key with no OAuth or refresh flow; if the key is revoked in Klaviyo, subsequent reads fail until it is replaced.

​
API references

​
See also