Klaviyo

Connect your Klaviyo account to AxiTrace over OAuth and AxiTrace reads your account, your conversion metric, your campaigns, your flows and their daily statistics. It never changes anything in Klaviyo: the connection is read-only, so campaigns, flows, lists and profiles stay exactly as you left them.

What AxiTrace reads

• Account - the account name, its time zone and its currency, so reports show your Klaviyo numbers in the same units as the rest of the workspace.
• Metrics - your metric list, used to find the conversion metric AxiTrace reports against.
• Campaigns - campaign names, statuses and daily statistics.
• Flows - flow names, statuses and daily statistics.

Every read is a Klaviyo API call made with the stored tokens. AxiTrace does not create, edit or delete a campaign, a flow, a profile or a list.

Scopes

A plain connection asks Klaviyo for four read scopes; two more are added when you turn on event sending. Each one maps to one part of the data AxiTrace shows:

If Klaviyo's consent screen shows fewer scopes than the table, you approved a partial request. Disconnect and connect again, and keep every scope ticked on Klaviyo's screen.

How to connect

From Connections

1. In your AxiTrace workspace, open Settings > Connections.
2. Find the Klaviyo card and click Connect.
3. Sign in to Klaviyo and approve the requested scopes. Klaviyo sends you back to the Klaviyo card, which shows the connected account.

From the Klaviyo marketplace

1. Open the AxiTrace listing in the Klaviyo marketplace and click Install.
2. Klaviyo sends you to /admin/integrations/klaviyo/connect. If you administer one workspace you go straight to Klaviyo's consent screen; if you administer more than one, pick the workspace first.
3. Approve the scopes. You land on the Klaviyo card of the workspace you picked, with the connection active.

A workspace can hold one Klaviyo connection at a time. Connecting a different Klaviyo account revokes the old connection and purges the data imported for the old account; reconnecting the same account keeps its data.

Re-authorizing

Re-authorize when AxiTrace shows Reconnect required on the Klaviyo card, when a scope is missing, or when you moved the workspace to a different Klaviyo account. Open the Klaviyo card under Settings > Connections and click Re-authorize. AxiTrace asks Klaviyo for the full read set again; the data already imported stays where it is.

Disconnecting

Click Disconnect on the Klaviyo card and confirm. AxiTrace revokes its tokens at Klaviyo and stops every read immediately. Data already imported is kept in your reports and is deleted only when you delete the workspace.

Reading campaigns and flows

AxiTrace reads your Klaviyo campaigns and flows, keeps their daily statistics, and puts them next to the visits and orders AxiTrace attributes itself. Nothing here changes anything in Klaviyo: every figure comes from a read call, and Klaviyo's own numbers and AxiTrace's numbers stay separate columns.

What is imported

• Campaigns - the name, status, send date and channel (email, SMS or push) of every campaign, with its daily statistics.
• Flows and flow messages - the name, status and messages of every flow, with the daily statistics of each message.
• Daily statistics - recipients, delivered, unique opens, unique clicks, orders and revenue of the conversion metric, unsubscribes, bounces and spam complaints.
• History - when you connect, AxiTrace backfills the last 180 days of campaigns, flows and their statistics.

A campaign's statistics belong to its send date in the account's time zone, never to the day AxiTrace read them. Flow statistics are daily figures for the day they cover.

Refresh and restatement

• The sync runs every hour.
• Campaigns are re-read at most once an hour, always for the whole 180-day window, so a campaign Klaviyo restates is corrected on the next run.
• Flows are re-read for the last 14 days on every run, because Klaviyo keeps adding conversions to a message for days after it is sent. Older days are imported once, in chunks, and are not re-read.
• A backfill interrupted by a token refresh or a quota pause resumes from the last finished chunk instead of starting over.

Reporting quota and the "quota paused" state

Klaviyo limits how many reporting calls an account may make. AxiTrace spaces its calls: campaigns at most once an hour, and two calls of the same report for one connection at least 30 seconds apart. AxiTrace also caps its own use at 180 report calls per report type and connection per day.

When that cap is reached, or Klaviyo answers with a long Retry-After, the import stops and the connection is recorded as quota paused. While it is paused the Klaviyo panel shows a quota paused notice above its tables; the figures imported before the pause stay and are still shown. The next hourly run continues on its own; there is nothing to click and no token to refresh for this state.

The conversion metric

Klaviyo reports conversions for one metric, and AxiTrace uses the first one that exists, in this order:

1. A Placed Order metric reported by a native store integration (Shopify, WooCommerce, BigCommerce and similar).
2. A Placed Order metric reported by AxiTrace.
3. Any other Placed Order metric.
4. No Placed Order at all: engagement-only mode, using the Active on Site metric when the account has one.

AxiTrace keeps the metric it picked, so a second store integration or a second Placed Order metric does not flip the numbers you already read. It picks again only when the stored metric disappeared from the account, or when the connection was in engagement-only mode and a Placed Order metric has appeared since.

In engagement-only mode the Klaviyo orders and revenue columns show Unavailable with a hint, and the panel compares engagement only. Everything else on the page works the same way.

The Klaviyo panel in the Overview

In the Overview, open the Email row of the Aggregated Traffic Sources table, then the Klaviyo source row inside it. The Klaviyo panel has two tabs, Campaigns and Flows, and every row puts Klaviyo's figures next to AxiTrace's:

• Klaviyo (own attribution) - recipients, unique opens, unique clicks, orders and revenue as Klaviyo reports them. For flows, unique opens and unique clicks are added up day by day, so they can be higher than in Klaviyo.
• AxiTrace - visits, orders and revenue AxiTrace attributed to that campaign or flow under the attribution model selected in the dashboard.
• Match - By ID when the utm_id of the visit is the Klaviyo campaign, flow or message id, By name when AxiTrace matched the utm_campaign name instead, and Not matched when no visit of the period points to the object. Hover the badge to read the reason.

A flow expands to its messages with the same columns. Two sections below the table close the picture: In Klaviyo only lists the campaigns and flows that sent something in the period but have no matching AxiTrace visits, and Other Klaviyo UTM campaigns lists the visits tagged with utm_source=klaviyo whose utm_campaign matches no Klaviyo object. When AxiTrace has seen no visit with Klaviyo UTM tags yet, the panel shows the recommended values and links to this guide.

How to read the two sides

• Different clocks. Klaviyo counts by send date; AxiTrace counts by order date under the selected attribution model. A campaign sent on one day can bring orders on the following ones, so a daily view splits the same order differently on the two sides.
• Different attribution rules. Klaviyo attributes an order to the last message the visitor opened or clicked within its attribution window, 5 days by default and set in Klaviyo, as a last-touch model. AxiTrace attributes by the model you selected in the dashboard, from the visits that reached the site with Klaviyo UTM tags.
• Klaviyo sees revenue AxiTrace cannot. Klaviyo's own revenue includes orders it attributes to a message that the store never reported to AxiTrace, or that AxiTrace could not tie to a visit (see the limitation below), and Klaviyo dashboards also count revenue from objects outside this panel. Klaviyo's column is therefore usually higher. Treat the two columns as two views, not as two measurements of the same thing.
• Opens are an upper bound. Klaviyo counts an open when Apple Mail Privacy Protection preloads a message, even when nobody read it. Compare clicks when you compare engagement.

Recommended UTM settings in Klaviyo

AxiTrace matches a Klaviyo object to a visit by id first and by name second. Put these UTM parameters on the links of every campaign and flow, in the message or template settings, so every link carries them:

Fill the ids with Klaviyo's template tags; there is no need to copy ids by hand. Matching by utm_id covers the visits recorded from the day this feature was released; a visit recorded before that still matches by the utm_campaign name, because its utm_id was not stored with it.

Known limitation

A click on a message link that opens the site in a new tab during an existing visit is not counted yet. The new tab joins the session that is already open, whose source stays what it was, so that click does not appear as a Klaviyo visit. A click that starts a new session is counted normally.

The same report in the API and the AI assistants

The panel and the API share one query layer. The MCP tool get_klaviyo_performance and GET /api/v1/workspaces/{workspace_id}/klaviyo/performance (scope reports:read) return the Klaviyo objects of the period with Klaviyo's figures and the AxiTrace visits and orders they brought, the connection status, the objects Klaviyo sent with no matching visit, and the klaviyo-tagged UTM campaigns that no object claimed. A workspace without a Klaviyo connection gets status: not_connected and an empty report, not an error. See Klaviyo performance in the API reference.

Send events to Klaviyo

When you turn on event sending on the Klaviyo card, AxiTrace writes the shopping events it already tracks to Klaviyo, so your browse, cart and checkout flows can trigger on them.

What is sent

Event properties include ProductName, ProductID, SKU, Categories, ImageURL, URL, Brand, Price, Items and OrderId. The metrics appear in Klaviyo with AxiTrace as their source.

Who is sent

Only customers AxiTrace already knows by e-mail address or phone number (from an order, a form, a login or a checkout). Anonymous visitors are never sent. First and last name are included when known. No address is sent, and an AxiTrace identifier is never sent as a Klaviyo identifier.

Consent

The consent rules of your workspace apply to every event. Events never subscribe anyone to e-mail or SMS marketing and never change a profile's consent in Klaviyo.

Create new Klaviyo profiles

With Create new Klaviyo profiles on, AxiTrace creates a profile for a known customer who is not in Klaviyo yet. New profiles can raise the active profile count that your Klaviyo plan is billed on. With it off, events are sent only for customers who already have a Klaviyo profile, which AxiTrace looks up by e-mail or phone number.

Orders and your store integration

Placed Order is sent only when Klaviyo has no store integration sending orders for the store. If your store platform integration already sends orders, AxiTrace does not send a second copy.

Re-pointing a flow to the AxiTrace events

AxiTrace never creates, edits or pauses your flows. To use the new events, change the flow yourself:

1. In Klaviyo, open the flow and click its trigger.
2. Change the trigger metric to the metric with AxiTrace as its source (for example Added to Cart from AxiTrace).
3. Keep or rebuild the trigger and flow filters, because filters are tied to the old metric's properties.
4. Update the template variables to the AxiTrace properties: event.ProductName, event.ImageURL, event.URL and event.Items.
5. For an abandoned checkout flow, link to the store's cart page or to event.Items.0.URL. AxiTrace does not send a checkout recovery link.
6. Run the old and the new flow side by side only with a filter that stops a customer from getting both e-mails.

Timing

Events older than 6 hours are not sent. Orders are sent up to 7 days after they happened.

Testing

After you turn sending on, open Klaviyo and go to Analytics > Metrics. The AxiTrace metrics appear there after the first events arrive, and you can open a metric to see its recent events.

Troubleshooting event sending

• Permission missing - the connection was approved without the write scopes. Click Re-authorize and keep every scope ticked.
• Needs reconnecting or disconnected - Klaviyo refused the stored tokens. Reconnect the account on the Klaviyo card.
• Not sent today counters - events skipped for a reason, such as no known e-mail or phone, missing consent, or an event older than the time limit. They are not errors.
• Refunds are not sent to Klaviyo.

Troubleshooting