Connecting Medusa to Klaviyo

Architecture

How Medusa and Klaviyo actually connect

Two systems that know nothing about each other. Everything below exists to give them one shared reference.

1. Step 1

   Medusa holds the truth

   Because you own the event handlers, the conversion can fire from the payment-captured event specifically rather than from whatever the frontend happened to render.

2. Step 2

   Klaviyo needs a click to match

   Klaviyo needs to resolve the event to a profile. Given an email it will create or update; given nothing it discards the event.

3. Step 3

   The identifier is the bridge

   The profile identity — email or phone, captured at the visit and carried into the Medusa order. Without it there is nothing to join on and no tool fixes that.

4. Step 4

   The event source decides reliability

   Send orders at payment capture, at the paid total.

5. Step 5

   Deduplication at the destination

   Klaviyo does not deduplicate events for you. Sending the same purchase from both the store integration and your own server produces two events, two flow triggers and potentially two emails to a customer who bought once.

Diagnose it honestly

Working vs. broken, side by side

Both states look identical from the Klaviyo dashboard, which is why this runs for months before anyone notices.

Diagnostic sequence

Diagnostic order

Each step rules out a class of cause. Run them in order and the last one usually has a single explanation standing.

1. 1

   Count orders carrying the profile identity — email or phone

   The ceiling on everything else. Do this before debugging anything downstream.

2. 2

   Follow one real conversion end to end

   From the ad click through Medusa and into Klaviyo.

3. 3

   Check which event your subscriber listens to

   One line of code, and it decides whether you are counting orders or counting money.

4. 4

   Open the profile's activity feed after a test event

   One event or two? Check whether the native store integration is already sending the same metric before you add a second source.

5. 5

   Read the match rate, not the success message

   Klaviyo shows the event on the profile's activity feed within moments. Check the profile, not the API response — and specifically check whether the same metric is arriving twice from two sources.

Source-of-truth validation

How it gets proven

Against Medusa's own records, not against either platform's dashboard.

• The profile identity — email or phone confirmed present on a live order.
• A real conversion followed from click through Medusa to Klaviyo.
• The profile activity feed confirmed to show one event per conversion, with no overlap against the native integration.
• Payment-captured orders reconciled against imported conversions.
• Reconciled over a fully closed window, matched per record rather than on totals.
• Re-checked 30 days later.

Straight talk

When you don't need this

Worth reading before paying anyone, including us.

• If Klaviyo already reports conversions that reconcile against Medusa's records within a few percent, this join is working and there is nothing to buy.
• Measure identifier coverage yourself first — pull your last hundred orders and count how many carry the profile identity — email or phone. Ten minutes, free, and it tells you whether any of this is worth doing.
• If every payment method you accept is instant, the two events nearly coincide and the distinction costs more than it returns.
• If Klaviyo's native store integration already sends the events your flows need, adding a second source creates duplicates rather than value.