This article explains what the Klaviyo integration does, what you need to use it, and which return events Swap sends to Klaviyo.
ℹ️ This article covers Returns V2. If your store is on Returns V1, see Klaviyo x Swap Integration (Returns V1), which covers a different and larger set of events.
What the integration does
The Klaviyo integration lets you use Klaviyo as the email platform for your return communications instead of Swap's native templates, so your return emails use your own flows, segmentation, and branding.
Swap sends return events to Klaviyo as they happen. Each event arrives in Klaviyo as a custom metric carrying structured data about the return, the order, the customer, and the items. You can use those metrics to:
Trigger Klaviyo flows from return activity
Control email content and timing entirely from Klaviyo
Personalise messaging using return data
Segment customers on return behaviour
Requirements
A Klaviyo account. If you do not have one, Klaviyo's documentation covers how to set up your account
A Klaviyo private application programming interface (API) key, which you create in Klaviyo — see How to create or clone a private API key
Returns V2 enabled on your store
The Klaviyo app available on your Returns → Integrations page
The four return events
Swap sends four events across the lifecycle of a return.
Return created — a customer submits a return request
Return processed — a return is processed, whether that results in a refund, an exchange, or store credit
Return tracking update — the return shipment's tracking status changes
Return delivered — the returned item is delivered to the warehouse
Each event can be switched on or off independently for your store.
Event names differ between Swap and Klaviyo
This is the most common source of confusion. The same event is labelled differently in each system.
Label in the Swap dashboard | Metric name in Klaviyo |
Return created |
|
Return processed |
|
Return tracking update |
|
Return delivered |
|
Build your Klaviyo flows using the metric names in the right-hand column. To find them quickly, search V2- Return in Klaviyo's metric picker.
⚠️ Klaviyo metric filters are exact-match, and values are case-, space-, and punctuation-sensitive. Note that the prefix is V2- followed by a single space, and that the tracking metric includes the word Label. A metric name that looks correct but has an extra space fails silently: the flow simply never triggers, with no error.
For the full list of properties carried on each event, along with the exact values that fields such as return_type and shipping_status can take, see the Klaviyo Events API documentation. Copy values from that page rather than transcribing them from a live payload.
How Klaviyo and Swap emails work together
Klaviyo and Swap's native tools operate independently, and both can be active at the same time. Enabling Klaviyo does not switch Swap's native emails off. If you want Klaviyo to be the only sender, disable the native emails yourself.
Both are configured on the Returns → Settings → Emails tab:
The Email platform panel holds the Klaviyo and Swap's native tools cards. Each card shows Activated once that platform is set up, and both can show Activated at once.
The Events management panel holds the Enable Klaviyo Email Management toggle and the four events. At least one event must be active for Enable Klaviyo Email Management to stay on.
Where the two platforms overlap
Swap's native tools send two return emails. Klaviyo covers four events, two of which describe the same moment as a native email.
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 |
The return is processed | Not available | Return processed |
The tracking status changes | Not available | Return tracking update |
Klaviyo is the only way to send email on Return processed and Return tracking update, so running both platforms together is a deliberate choice for some merchants: native templates for the first two emails, Klaviyo for the rest.
⚠️ Where a native email and its matching Klaviyo event are both active, the customer receives two emails for the same moment. Before enabling Return created or Return delivered in Klaviyo, check whether the equivalent native email is switched on. To edit or disable the native emails, see How to customise Swap emails (Returns V2).
Where things live in the dashboard
Task | Path |
Connect or disconnect Klaviyo | Returns → Integrations, in the Apps panel |
Choose your email platform, and enable events | Returns → Settings → Emails |