This article covers the most common problems with the Klaviyo integration and how to resolve each one.
ℹ️ This article covers Returns V2. If your store is on Returns V1, see Klaviyo x Swap Integration (Returns V1).
No events are reaching Klaviyo
Work through these in order.
Check Klaviyo is connected. Go to Returns → Integrations. The Klaviyo card in the Apps panel should show a Connected status. If it shows Connect instead, the account is not linked — see How to set up the Klaviyo integration (Returns V2).
Check Klaviyo is your selected email platform. Go to Returns → Settings → Emails and confirm Klaviyo is selected in the Email platform panel.
Check Klaviyo Email Management is on. In the Events management panel on the same tab, confirm Enable Klaviyo Email Management is switched on.
Check the individual event is on. Each of the four events has its own toggle. An event switched off is not sent at all, so nothing reaches Klaviyo and no flow can trigger.
Send a test event. In the Events management panel, find any event and click Send test. If the test arrives in Klaviyo but real returns do not, the connection is fine and the problem is with the event toggles or your flows. If the test does not arrive either, it is the connection or the key.
The Swap metric is missing from Klaviyo's picker
Klaviyo only lists a metric once it has received it at least once, so on a new connection the metrics will not appear until Swap has sent something.
Click Send test against the event, or submit a test return, then look again. Search V2- Return in the metric picker to find all four. In Klaviyo, metrics your account has received are listed under Metrics on the Analytics tab.
A flow is not triggering
Check the metric name character by character. This is the most common cause. Klaviyo filters are exact-match, and values are case-, space-, and punctuation-sensitive. Two mistakes account for most failures:
Writing
V2 - Return Createdinstead ofV2- Return Created. The prefix isV2-followed by a single space, with no space before the hyphen.Writing
V2- Return Tracking Updateinstead ofV2- Return Tracking Label Update. The tracking metric includes the wordLabel.
A name that is wrong by one character fails silently. The flow simply never runs, and Klaviyo reports no error. Copy the names from Understanding the Klaviyo integration (Returns V2) rather than typing them.
Check the flow is live. In Klaviyo, confirm the flow is published rather than sitting in draft or manual mode.
Check the event is switched on in Swap. See the section above.
Customers are getting two emails for the same thing
Enabling Klaviyo does not switch Swap's native return emails off. The two platforms run independently, and both can be active at once — so if a native email and its matching Klaviyo event are both live, the customer receives both.
Swap's native tools send two return emails, and each one overlaps a Klaviyo event:
Moment in the return | Swap native email | Klaviyo event |
A customer submits a return | Return created | Return created |
Returned items reach the return address | Return received | Return delivered |
To fix it, decide which platform owns each moment and switch the other off. To disable or edit the native emails, go to Returns → Settings → Emails and see How to customise Swap emails (Returns V2).
Return processed and Return tracking update have no native equivalent, so neither can be the cause here.
If the duplicates are both coming from Klaviyo, the cause is more likely two Klaviyo flows overlapping — see the next section.
Customers are getting too many tracking emails
Return tracking update fires on every tracking status change, and a single return normally produces several In-Transit events as the parcel moves between distribution centres. An unfiltered flow on this event emails the customer on every carrier scan.
Limit how often a customer can re-enter the flow — around seven days is a sensible starting point — and filter on shipping_status so the flow only runs on the statuses you want to email about. Klaviyo sets both on the flow's trigger: Understanding flow triggers and filters.
If customers get two emails when a return arrives, it is because Return tracking update also fires on delivery with shipping_status set to Delivered, alongside your Return delivered flow. Exclude Delivered from the tracking flow, or use only one of the two events for that message.
A field is empty in the email template
Every event carries the same common properties, including quality_control and instant_exchange_details. These are always present in the payload — their values are simply empty until there is something to report, so an empty value does not mean the integration is misconfigured.
Three things genuinely do vary by event:
The item array is named differently. Return created and Return processed use
item_details. Return tracking update and Return delivered useitems_details. A template variable that works in one flow renders empty in the other.Shipping and tracking detail only appears on the tracking events.
shipping_status,shipping_details,tracking_urlanddelivered_dateare carried by Return tracking update and Return delivered.additional_shipmentsis left out entirely when a return has only one shipment, rather than being present and empty.
Check the field against the event you are building on in the Klaviyo Events API documentation, and copy values from that page rather than transcribing them from a payload.
Customer profiles are not being created
Swap identifies the customer by email address, and Klaviyo creates a profile where none exists. If profiles are not appearing:
Confirm the customer has an email address on their Shopify order
Confirm your private API key has permission to create and update profiles in Klaviyo. Klaviyo's documentation covers key scopes: How to create or clone a private API key. Scopes cannot be edited after a key is created — if the scope is wrong, create a new key
An error appears after saving your API key
Confirm you are using a private API key. A public key cannot read or write profiles and will be rejected.
Confirm the key has not been deleted or regenerated in Klaviyo since you added it.
Confirm the key has profile read and write permissions. An insufficiently scoped key is the most common cause of events failing to deliver after a connection that looked successful.
To replace the key, create a new one in Klaviyo — see How to create or clone a private API key — then reconnect Klaviyo from Returns → Integrations.
Everything looks correct and events still are not arriving
Occasionally an event does not fire even though the return completed normally and the configuration is right.
If you have worked through the checks above and a specific return is still missing its event, contact Swap Support with the RMA number and the event you expected. Support can confirm whether Swap sent it, which separates a problem on Swap's side from one inside your Klaviyo account — Klaviyo rejecting an event for its own reasons is a common cause, and that will not show up in the Swap dashboard.