Poppy & Pine's developer team sat down with stakeholders to plan the next phase of their Klaviyo integration roadmap. These requests made the top of the list:
1. Data science needs Klaviyo data in the warehouse to sharpen their lifetime value model.
2. The ERP (enterprise resource planning) system needs consent information and custom profile properties, like favorite flowers and birthdays.
3. Leadership needs a weekly dashboard on Klaviyo's impact.
4. Finance needs a report that reconciles with the ecommerce platform.
Same direction (out of Klaviyo). Four very different jobs. The model needs individual events. The ERP needs current profile data. Leadership needs attributed performance stats. Each one calls for a different tool and a different refresh schedule.
So which tool fits which job? Start with the three ways to pull data from Klaviyo.
The three tools to pull data from Klaviyo
Tool | What it returns | Use cases | Watch out for |
|---|---|---|---|
Standard GET (/api/events, /api/profiles, /api/campaigns) | Returns raw records (individual events or profiles) in JSON:API format, paged with a cursor through links.next. Supports filters, sparse fieldsets (fields[...]), and includes for related resources. Results are paged. Follow links.next until it's null. | Row-level data. Poppy & Pine uses it to: pull Placed Order events into the warehouse for the lifetime value model; sync profiles with consent and custom properties (favorite flower, birthday) to the ERP; pull campaign names and send times for leadership's report. | No attribution logic. Large backfills are slow. |
Query Metric Aggregates (POST /api/metric-aggregates) | Returns pre-aggregated counts, sums, or unique counts for one metric, bucketed by interval (hour, day, week, month), optionally grouped by dimensions such as $attributed_message, $flow, or $message. | Trend analysis on a single metric. Good for lightweight dashboards. Poppy & Pine uses Query Metric Aggregates to see daily revenue trends from placed orders. Useful for spotting trends over time. | Its numbers often do not match the Klaviyo UI because it filters and buckets by event time, while campaign and flow performance in the UI is based on send date. Setting a timezone does not remove that difference. However, setting the timezone explicitly controls the time boundaries used in the query. Only one metric per request. In the response, each value in a measurements array lines up by position with the dates array. sum_value adds up each event's value, so events sent without a value don't add to the total. |
Reporting API (POST /api/campaign-values-reports, /api/flow-values-reports, and others) | Returns the same performance statistics shown in the Klaviyo UI (ex: opens, clicks, open rate, conversions) per campaign, flow, or message, using a conversion metric you specify. | Whenever the numbers must match what stakeholders see in Klaviyo. Poppy & Pine uses it for leadership's campaign performance in BigQuery, refreshed daily. It's the default for campaign and flow performance reporting in a warehouse. | Very tight rate limits. See Query Campaign Values for the current limits. You must batch carefully and request many statistics in a single call instead of one call per stat. |
Common gotchas
If the numbers must match the UI, use the Reporting API instead. If you must use Query Metric Aggregates, set the timezone explicitly for the intended time boundaries, but note that this will not make the results match the UI: aggregates use event time, while campaign reporting uses send date.
For paginated resource collections, follow links.next exactly as returned until it is null. Do not change filters or sort order while following the cursor. Check endpoint-specific page-size limits.
Request only what you need with fields[profile]=email,updated,properties, and use additional-fields[profile]=subscriptions or predictive_analytics when you need those. An absent subscriptions object is not an unsubscribed state.
Check the endpoint's supported filter fields. If it cannot filter by the custom property, a segment such as "Gold tier" can define the audience, and GET /api/segments/{id}/profiles can retrieve its members.
Schedule extraction, request multiple statistics together, and serve stored results. Honor Retry-After on a 429.
On revision 2026-10-15, use GET /api/campaign-messages, which filters by campaign_id, name, status, created, and updated. Older revisions of GET /api/campaigns may require a channel filter, such as filter=equals(messages.channel,'email'). Check the endpoint reference for your pinned revision.
Always pin the revision header, and use the endpoint reference for that revision to update the request shape. Examples that call Klaviyo's retired v1/v2 legacy endpoints no longer work; verify other older examples against the pinned revision.
If the numbers must match the UI, use the Reporting API instead. If you must use Query Metric Aggregates, set the timezone explicitly for the intended time boundaries, but note that this will not make the results match the UI: aggregates use event time, while campaign reporting uses send date.
For paginated resource collections, follow links.next exactly as returned until it is null. Do not change filters or sort order while following the cursor. Check endpoint-specific page-size limits.
Request only what you need with fields[profile]=email,updated,properties, and use additional-fields[profile]=subscriptions or predictive_analytics when you need those. An absent subscriptions object is not an unsubscribed state.
Check the endpoint's supported filter fields. If it cannot filter by the custom property, a segment such as "Gold tier" can define the audience, and GET /api/segments/{id}/profiles can retrieve its members.
Schedule extraction, request multiple statistics together, and serve stored results. Honor Retry-After on a 429.
On revision 2026-10-15, use GET /api/campaign-messages, which filters by campaign_id, name, status, created, and updated. Older revisions of GET /api/campaigns may require a channel filter, such as filter=equals(messages.channel,'email'). Check the endpoint reference for your pinned revision.
Always pin the revision header, and use the endpoint reference for that revision to update the request shape. Examples that call Klaviyo's retired v1/v2 legacy endpoints no longer work; verify other older examples against the pinned revision.
Ready to practice? The next lesson, Try it yourself, walks you through pulling Poppy & Pine's campaign performance in Postman.