Klaviyo

Previous Next

Connect Klaviyo

Squoosh reads your Klaviyo order count. It does not yet change how your AI shoppers behave. This connection prepares order evidence for future use; it does not currently calibrate shoppers or provide a conversion rate.

Beta: credential-ready

This connector has not been validated against a live account. It remains at the auth stage. The request and response parser has fixture-based tests, but live validation is still needed before the connector can advance.

What the connection does

Squoosh finds your Placed Order metric and reads its aggregate event count for the last requested number of full UTC days, excluding today. A window with zero events is recorded as a real zero.

Klaviyo provides no web-session denominator for this query. Squoosh therefore stores an order count without calculating a conversion rate. Cross-source pairing with another source's sessions is not available, and Klaviyo cannot currently be activated as a conversion calibration source.

Connect Klaviyo

You need a Private API key with the metrics:read scope. A public site ID is not sufficient.

  1. In Klaviyo, open Settings → API keys → Create Private API Key.
  2. Name the key for Squoosh. Choose a Custom Key with metrics:read, or a Read-Only Key. A custom key limits access to the scope this connector needs. Scopes cannot be added to an existing key; create a new key if the scope is missing.
  3. Copy the private key, which starts with pk_.
  4. In Squoosh, open Integrations, find Klaviyo, and click Connect.
  5. Enter the Private API key. Optionally enter the Placed Order metric ID:
  6. In Klaviyo, open Analytics → Metrics, then open the relevant Placed Order metric.
  7. Copy the ID from the page URL: https://www.klaviyo.com/metric/METRIC_ID/metricname. Paste only the letters and digits of METRIC_ID, not the whole URL.
  8. Leave this field blank to let Squoosh discover the metric. If several integrations have a metric named Placed Order, Squoosh asks you to specify the ID so it does not choose the wrong one.
  9. Click Connect. Squoosh checks access using the Metrics API, which needs the same metrics:read scope as the order-count query. It does not require accounts:read.

Private-key setup is documented in Klaviyo authentication. The metric-page URL is documented in Query Metric Aggregates.

What Squoosh reads and never reads

Data Use
Metric ID, name, and integration label Select the intended Placed Order metric. Discovery also supports API-created metrics.
Daily aggregate event counts Sum the order count for the requested window. A manually selected metric retains its actual name.
Profile records, email addresses, phone numbers, billing addresses Never requested by this connector.
Raw individual events or order line items Never requested. The connection uses aggregate counts.
Campaign content, messages, lists, or subscribers Never requested or modified. Squoosh does not send email or SMS.
Shopper device, geography, acquisition channel, or sessions Not supplied by this aggregate query and never inferred.

The private key is sent only in the authorization header to Klaviyo's fixed API host, a.klaviyo.com. It is never included in an order snapshot, log message, or error message.

Limits and caveats

  • Order count only. The connection does not yet change how your AI shoppers behave. It produces no conversion rate or audience distribution.
  • Gross placed orders can include offline orders. Shopify POS orders sync into the same Placed Order metric. Cancelled Order and Refunded Order are separate metrics; Squoosh does not subtract them. Whether Klaviyo retroactively removes reversed events is unverified. See Shopify metrics and Shopify POS orders.
  • Window: 1 to 365 full UTC days. Today is excluded. Date boundaries and event-time reporting can differ from another Klaviyo report's timezone or attribution view.
  • Metric discovery is bounded. Squoosh examines up to five pages, with up to 200 metrics per page. If another page remains, it asks for a metric ID instead of reporting an unproven selection or an incomplete order count. This is a discovery limit, not a cap of 1,000 orders.
  • No invented truncation. The ungrouped aggregate query expects one row of daily counts. It rejects malformed or grouped responses. The API does not document an observable order cap for that single-row query, so Squoosh does not label a successful result truncated.
  • Message attribution is not acquisition channel. Klaviyo's attributed email/SMS/push channels are not a visitor source/medium distribution. Email-client and SMS-region fields are also not shopper device or geography.
  • Account-wide quotas apply. Private-key integrations share Klaviyo's per-account quota. Metric reads allow 10 requests/second and 150/minute; aggregate queries allow 3/second and 60/minute. The connector declares a minimum refresh interval of 15 minutes. A 429 reports valid Retry-After seconds when supplied; wait before retrying. See Klaviyo rate limits.
  • A new store connection may still be syncing history. An older window can undercount while Klaviyo imports historical data.
  • Live validation is pending. Request content type, trailing slashes, date literals, empty-window behavior, and the numeric-array response need confirmation against a test account. The connector pins API revision 2026-07-15 and will need maintenance as revisions retire.

Troubleshooting

Problem What to do
Invalid private key or HTTP 400/401 authentication error Confirm you copied a private key from the correct account. Create a replacement key if needed.
Missing scope or HTTP 403 Re-create the key with metrics:read. Scopes cannot be added to the existing key.
Metric not found or HTTP 404 Check the metricId belongs to this account. Paste the ID only, not the full metric-page URL.
No Placed Order metric found Connect a store in Klaviyo, confirm order events exist, or enter the intended metric ID.
Several Placed Order metrics found Use the integration names in the error to identify the intended metric, then enter its ID.
Metric discovery reaches its page cap Enter the metric ID directly. Squoosh does not guess from a partial list.
Rate limited or HTTP 429 Wait at least the reported Retry-After interval. Other private-key integrations share the account quota.
HTTP 410 Contact Squoosh support. The API revision pin needs updating; reconnecting will not fix it.
HTTP 415, another query-related 400, or malformed aggregate data Contact Squoosh support. The connector request or parser needs review.
HTTP 5xx or timeout Retry later; the provider or network may be temporarily unavailable.
No conversion rate or shopper behavior change This is the current connector limit. Order counts have no session denominator, and cross-source pairing is not implemented.
Hotjar mParticle