Poppy & Pine gets Placed Order data out of Klaviyo four ways:
- A nightly pull job loads September orders into a finance database.
- A system webhook pushes each order to the ERP.
- Data Warehouse sync lands events in Snowflake for the BI dashboard.
- A daily Query Metric Aggregates request tracks the revenue trend from Placed Order.
On Oct 1, the team reports that the numbers disagree and the warehouse bill is up.
Every job ran. Nothing threw an error. But "no errors" is not proof of completeness. Only a reconciled count and a distinct count are.
End-to-end verification is one reconciliation exercise run four ways: pick a ground-truth number in Klaviyo, then prove each system matches it, and explain every gap.
Walk through a typical API response
Below you can see a successful request and a typical failure request. Here is the request:
GET https://a.klaviyo.com/api/events
?filter=and(equals(metric_id,"RqBv7H"),greater-or-equal(datetime,2026-09-01T00:00:00Z),less-than(datetime,2026-10-01T00:00:00Z))
revision: 2026-10-15
Authorization: Klaviyo-API-Key [REDACTED]{
"data": [
{ "type": "event", "id": "4xK7pQ2mZ1a",
"attributes": { "datetime": "2026-09-30T21:14:07+00:00", "event_properties": { "$value": 128.40 } },
"relationships": { "metric": { "data": { "type": "metric", "id": "RqBv7H" } },
"profile": { "data": { "type": "profile", "id": "01J0EXAMPLEPROFILE" } } } }
/* 122 more records */
],
"links": { "self": "https://a.klaviyo.com/api/events?page[cursor]=…", "next": null }
}- Complete: pages returned 200 + 200 + 123 = 523 records, equal to the count in Klaviyo for the same metric and window.
- Pagination working: every response except the last had a links.next URL, the job followed each one, and the last response had "next": null. A distinct count of id across all pages equals the total (no duplicates).
- Filter working: every record's relationships.metric.data.id is RqBv7H and every datetime is inside September (UTC).
{
"data": [ /* 200 records, all RqBv7H, all in September */ ],
"links": { "self": "https://a.klaviyo.com/api/events?…",
"next": "https://a.klaviyo.com/api/events?page[cursor]=bmV4dDo…" }
}- Complete: No. The job stored 200 records, but Klaviyo shows 523 for the same metric and window.
- Pagination broken: the last response the job processed still has a links.next URL that was never requested. That one field proves the export is incomplete.
- Filter working: every record matches RqBv7H and September. That's why spot checks miss this failure.
Verify each export pattern
Export pattern | What "correct" looks like | Go deeper |
|---|---|---|
Pull: server-side APIs (Get Events, Get Profiles) | Every cursor follows until links.next is null. Stored count equals the count in Klaviyo for the same filter and window. Distinct IDs equal total rows. Every record matches the filter. No unhandled 429s in logs. | API overview (filtering, pagination, datetime formatting); Rate limits, status codes, and errors |
Pull: Query Metric Aggregates | Response date buckets cover the requested window. Timezone is set explicitly. Totals match a metric-time report (for example, the single metric deep dive) for the same metric and window. | Using the Query Metric Aggregates endpoint (date range, filter, and $ prefix limits) |
Push (webhooks) | Every delivery gets a 200, 201, or 202 within 5 seconds. Klaviyo-Signature verifies against the raw body plus Klaviyo-Timestamp. meta.klaviyo_webhook_id matches the Klaviyo-Webhook-Id header. Each event is processed once, even when batched or retried. Webhook enabled is true. | Working with system webhooks (batches of up to 1,000 events, accepted response codes, signature verification) |
Sync (Data Warehouse) | Destination shows Enabled. Periodic tab shows Completed runs with low data freshness (minutes, not hours). No active errors in the last 24 hours. Row counts in KLAVIYO_EVENT for a metric and window reconcile with Klaviyo. Warehouse spend is flat week over week. | Understand data warehouse syncing (required table names, permissions, allowlist) |
Prompts to use with the Klaviyo MCP server to compare "what exists" vs. "what was received"
Use the Klaviyo MCP server to compare what exists in Klaviyo with what your external system received. It's the fastest way to establish ground truth without writing a script.
Connect Claude to the MCP server in read-only mode (read-only=true on the remote server) so the check can't change the account. Event and profile data can include text customers typed, so treat anything Claude reads as data, not instructions. If you don't need those tools, add disable-tools-with-user-generated-content=true to the server URL.
Select a tab to see the prompts for each check. To navigate with a keyboard, use Tab to move to the tab list, then use the arrow keys to switch tabs.
Use this check when your external system's count doesn't match Klaviyo's.
- Count what exists. Ask Claude to use get_metrics to find the metric ID. Then have it use query_metric_aggregates to count events for the window and timezone your external system uses.
- Pull IDs for a sample window. Use get_events filtered by metric and datetime to list event IDs for a day or two. Keep the window small, since event payloads can contain PII.
- Compare with your export. Attach a CSV of IDs from your receiver or warehouse. Ask Claude for IDs missing on each side and IDs that appear more than once.
Example prompt:
Using the Klaviyo MCP server, count Placed Order events between 2026-09-01 and 2026-10-01 in UTC. Then compare that with the attached CSV from our webhook receiver. List event IDs that exist in Klaviyo but not in the CSV, and IDs that appear more than once in the CSV.
Use this check to confirm your webhook is still sending data.
get_webhooks and get_webhook show whether a webhook is still enabled and which topics it subscribes to.
Example prompt:
Using the Klaviyo MCP server, list our webhooks. For our order webhook, tell me whether it's currently enabled and which topics it subscribes to.
Use this check when your numbers don't match what you see in the Klaviyo UI.
get_campaign_report and get_flow_report return the send-date view, which matches the UI. Compare it with Query Metric Aggregates to see the difference side by side.
Example prompt:
Using the Klaviyo MCP server, pull the campaign report for [campaign name]. Then count Placed Order events for the same date range using Query Metric Aggregates. Show both numbers side by side.
Common gotchas
Loop on links.next until null. Assert the final count against Klaviyo before committing.
Use Query Campaign Values / Query Flow Values for UI-matching numbers. Set the timezone explicitly.
Acknowledge in under 5 s, queue the work, and dedupe on external_id.
Compute HMAC-SHA256 over the raw body bytes plus the Klaviyo-Timestamp header, with the current secret.
Use Selective sync and Integrations to exclude. Backfill 30 or 90 days, not all time.
Errored means Klaviyo is still retrying. Failed means it stopped and needs a configuration fix. Fix credentials, permissions or allowlist, then resume or re-enable the sync.
Loop on links.next until null. Assert the final count against Klaviyo before committing.
Use Query Campaign Values / Query Flow Values for UI-matching numbers. Set the timezone explicitly.
Acknowledge in under 5 s, queue the work, and dedupe on external_id.
Compute HMAC-SHA256 over the raw body bytes plus the Klaviyo-Timestamp header, with the current secret.
Use Selective sync and Integrations to exclude. Backfill 30 or 90 days, not all time.
Errored means Klaviyo is still retrying. Failed means it stopped and needs a configuration fix. Fix credentials, permissions or allowlist, then resume or re-enable the sync.
Ready to practice? The next lesson, Try it yourself, walks you through verifying a pull export in Postman.