In this lesson, you'll build one part of Poppy & Pine's roadmap: campaign reporting.
Poppy & Pine's analytics team wants campaign performance in BigQuery, refreshed daily and matching the Klaviyo UI.
Here's how the developers can build it.
Open each step in order. Each one builds on the one before it
Step 1: Before we start, set up Postman
To model Poppy & Pine's data, let's quickly build some tests in Postman.
Create a new request. The server-side API base URL is:
https://a.klaviyo.com/api/
Save the private key as a secure Postman variable called klaviyo_private_key. Use a key with only the read scopes required by the endpoints in this workflow.
Warning: Keep this key server-side. Every request in this workflow uses private-key authentication. If the key ends up in browser code, anyone can access data or take actions within that key's scopes.
Save the current revision date as a Postman variable called klaviyo_revision, for example 2026-10-15. Check developers.klaviyo.com for the latest stable revision.
Use that same pinned revision for every request below; confirm revision-sensitive endpoint filters and request shapes against its reference.
On the Headers tab, add:
Authorization: Klaviyo-API-Key {{klaviyo_private_key}}
revision: {{klaviyo_revision}}
accept: application/vnd.api+jsonFor POST requests with a JSON body, also add:
content-type: application/vnd.api+jsonThis way, you can reuse these headers for the metric lookup, reporting, and campaign metadata requests.
Step 2: Find the conversion metric
The Reporting API needs to know which metric counts as a conversion. For revenue, that's usually Placed Order. Accounts often have several metrics with similar names (for example, Placed Order from Shopify vs. one from a custom integration), and picking the wrong one produces wrong revenue.
In Postman:
- Send a GET request to https://a.klaviyo.com/api/metrics/. It returns metrics in pages of up to 200 results; follow pagination links if the account has more.
- Find Placed Order. Match on name and integration.
- Confirm it's the same metric the account uses as its conversion metric in the UI, then copy its id.
Step 3: Add campaign names with a paginated pull
The Reporting API returns statistics by campaign ID, not by name. Leadership wants campaign names and send times too, so the team pulls campaign metadata with standard GET first, then joins it to the report on campaign ID.
Standard GET responses are JSON:API, so the actual fields are under attributes, and related data comes in included, not nested. Results are paged with a cursor through links.next.
In Postman:
- Create a new GET request to https://a.klaviyo.com/api/campaign-messages/?include=campaign&page[size]=100. Send.
- Scroll to links.next at the bottom of the response.
- Copy that URL exactly as returned into a new GET request and send again. Don't change filters or sort order along the way, because the cursor is tied to the original query.
- Repeat until links.next is null. That's the last page.
Step 4: Pull campaign performance with the Reporting API
The Reporting API returns the same performance statistics shown in the Klaviyo UI, so it's the right tool when the numbers must match.
{
"data": {
"type": "campaign-values-report",
"attributes": {
"timeframe": { "key": "last_30_days" },
"conversion_metric_id": "PLACED_ORDER_METRIC_ID",
"statistics": ["recipients", "delivered", "opens_unique", "clicks_unique",
"open_rate", "click_rate", "conversions", "conversion_value"],
"filter": "equals(send_channel,\"email\")"
}
}
}- timeframe takes either a preset key (last_7_days, last_30_days, last_12_months, and so on) or a custom start and end.
- A key pain point our team sees is identifying the difference between similar keys: last_30_days and last_month. last_30_days is the past 30 days, no matter the month. last_month is the previous calendar month.
- conversion_metric_id determines which metric counts as a conversion for the conversion and revenue statistics. It should be the same metric the account uses as its conversion metric in the UI, or the numbers won't match.
- statistics takes every stat you need in one call. Rate limits are very tight, so never make one call per stat.
In Postman:
- Create a new request. Set the method to POST and the URL to https://a.klaviyo.com/api/campaign-values-reports/.
- On the Body tab, choose raw and JSON. Paste the body above and swap in the metric ID from Step 2. Send.
- Compare three recent campaigns against their reports in Klaviyo.
Step 5: Keep it fresh and validate
Postman proves the requests work. To refresh daily, the team runs them as a scheduled job.
- Schedule it. A daily job (Cloud Scheduler plus Cloud Run), with a read-only scoped key in Secret Manager.
- Handle late-arriving stats. Stats keep changing for days after a send. Re-pull a rolling 30-day window each day and MERGE into a table partitioned by send date.
- Store counts, not rates, plus conversion_metric_id and pulled_at on each row.
- Validate. Compare three recent campaigns against the UI.
A successful pipeline has no pagination gaps, uses the correct conversion metric, survives a 429, and produces the same table when run twice.