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 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.