How to build Klaviyo flows with Swap events (Returns V2)

This article explains how to build Klaviyo flows triggered by Swap return events, including the filters you need to avoid over-emailing customers.

ℹ️ This article covers Returns V2. If your store is on Returns V1, see Klaviyo x Swap Integration (Returns V1).

Switch on the events you want before you start — see How to enable and manage Klaviyo events (Returns V2).

How to create a flow from a Swap event

Swap events arrive in Klaviyo as custom metrics, so you build these flows the same way you would build any metric-triggered flow. Klaviyo's documentation covers the mechanics: Getting started with flows and How to create a metric-triggered flow.

The Swap-specific part is which metric you pick as the trigger. The flow then runs whenever Klaviyo receives that event.

💡 Klaviyo only lists a metric once it has received it at least once. If a Swap metric is missing from the picker, send a test event from Returns → Settings → Emails first. To find all four quickly, search V2- Return.

The four metric names, exactly as Klaviyo lists them:

V2- Return Created
V2- Return Processed
V2- Return Tracking Label Update
V2- Return Delivered

⚠️ Metric names are exact-match and space-sensitive. The prefix is V2- followed by one space, and the tracking metric includes the word Label. A name that looks right but carries an extra space fails silently — the flow simply never runs, with no error to tell you why.

Always filter your tracking flow

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.

Two ways to control it, which work well together:

Limit how often a customer can re-enter the flow. Around seven days is a sensible starting point. Klaviyo sets this on the flow's trigger — see Understanding flow triggers and filters.
Filter on shipping_status so the flow only runs on the statuses you want to email about, rather than all ten.

The same applies in reverse to delivery. Return tracking update also fires on delivery with shipping_status set to Delivered, so if you have a separate Return delivered flow, exclude Delivered from the tracking flow or you will send two emails.

Using event data in your emails

Each event carries structured data about the return, order, customer and items, which you can insert as template variables, use in conditional splits, or segment on. Klaviyo's documentation covers how to reference it: How to use event data to personalize email and SMS flows. Note that event variables are only available in metric-triggered flows.

For the full property list per event, and the exact values each field can take, see the Klaviyo Events API documentation. Copy values from that page rather than transcribing them from a payload, since filters are exact-match.

Two things that catch people out:

The item array is called item_details on Return created and Return processed, but items_details on Return tracking update and Return delivered. A variable that works in one flow renders empty in the other.
return_type values are lowercase, and combined outcomes are suffixed, for example refund + exchange.

Common flows

Return confirmation

Trigger: V2- Return Created

Confirms the return and sets expectations. This event carries the shipping label, QR code and drop-off details, so it is the one to use for any email the customer needs in order to send the parcel back.

Processing outcome

Trigger: V2- Return Processed

Rather than building a separate flow per outcome, use one flow with a conditional split on return_type to cover refunds, exchanges and store credit. The event also carries the financial breakdown, so you can show the customer the actual amounts.

Tracking updates

Trigger: V2- Return Tracking Label Update

Keeps customers informed while the parcel is in transit. Filter it, as above.

Return received

Trigger: V2- Return Delivered

A final touchpoint confirming receipt, and a natural place for a review or feedback request.

Instant exchange reminders

Swap does not send a dedicated instant exchange reminder event. You can build one in Klaviyo from the events that do exist, to chase customers who started an instant exchange but have not yet sent their item back.

Trigger the flow from V2- Return Created
Add a Trigger Split where instant_exchange is true
On the Yes branch, add a time delay — three days is a reasonable starting point
After the delay, add a Conditional Split using What someone has or has not done
Check whether the customer has done V2- Return Tracking Label Update zero times since starting this flow
If they have not, send the reminder

Because the tracking event fires on the first carrier scan, no tracking event means the parcel has not entered the carrier network. The instant_exchange_details object on the event also carries the hold amount and the charge deadline, which you can use in the email itself.

Before you go live

Start with one flow, usually return confirmation, and add others once it is behaving as you expect
Test with Send test from Returns → Settings → Emails before switching a flow on
Name flows and metrics clearly, so the four V2- Return metrics stay easy to tell apart
Check whether Swap's native emails cover the same moment. Native Return created and Return received overlap the Klaviyo Return created and Return delivered events, and leaving both active sends two emails. See How to customise Swap emails (Returns V2)

💡 Swap can provide ready-made email templates as a starting point. Contact your Account Manager for access.