Understanding Klaviyo event types (Returns V2)

This article explains what triggers each of the four Klaviyo events, when they arrive, and what you can build with them.

ℹ️ This article covers Returns V2. If your store is on Returns V1, see Klaviyo x Swap Integration (Returns V1), which sends a different and larger set of events.

The four events

Label in the Swap dashboard	Metric name in Klaviyo
Return created	`V2- Return Created`
Return processed	`V2- Return Processed`
Return tracking update	`V2- Return Tracking Label Update`
Return delivered	`V2- Return Delivered`

Use the metric names in the right-hand column when building flows. They are exact-match and space-sensitive.

Return created

Fires when a customer submits a return request.

This is the richest of the four events. Alongside the customer, order and item data common to every event, it carries the shipping label details: carrier, tracking number, label and QR code URLs, drop-off location, return instructions, and a commercial invoice on international returns. Where a return is split across several shipments, each additional shipment appears with its own label and item list.

Use it for return confirmations, "what happens next" messaging, and retention or cross-sell flows.

Return processed

Fires when you process a return in the dashboard, whichever outcome you choose.

The event carries the financial outcome and who processed it, so a single flow can branch to cover every case. The return_type field tells you which outcome applied. Its values are always lowercase:

refund
exchange
store credit
shop now credit
shop later credit
additional payment

Where a return combines credit with exchange items, the value is suffixed — for example refund + exchange or store credit + exchange.

Use it for refund, exchange and store credit confirmations. Branch on return_type rather than building a separate flow per outcome.

💡 This event is sent after a short delay of around 30 seconds, so that every processing step has finished before the data reaches Klaviyo. The other three events are sent as soon as they occur.

Return tracking update

Fires every time the return shipment's tracking status changes.

The shipping_status field carries the current status. Values are Title-Case-hyphenated:

Pre-Transit, In-Transit, Delivered, Failed, Shipping-Issue, Green-Return, Label-Created, No-Status, Own, Return-To-Store

⚠️ A single return usually produces several In-Transit events as the parcel moves between distribution centres. Without a filter, a flow on this event emails the customer on every carrier scan. Always filter it — see How to build Klaviyo flows with Swap events (Returns V2).

Use it for in-transit updates and reassurance messaging, filtered down to the statuses you actually want to email on.

Return delivered

Fires when the return shipment is confirmed as delivered to the warehouse.

This event carries the same payload as Return tracking update, with shipping_status set to Delivered and delivered_date populated.

Use it for receipt confirmations, follow-up messaging, and review or feedback requests.

⚠️ Because Return tracking update also fires on delivery with shipping_status set to Delivered, having unfiltered flows on both events sends two emails when a return arrives. Either filter the tracking flow to exclude Delivered, or use only one of the two events for your delivery message.

When events arrive

Events are sent as they happen, apart from Return processed, which waits around 30 seconds. Two things can make the timing feel less immediate:

Tracking events depend on the carrier. Swap sends the event when the carrier reports a scan, so gaps between updates reflect the carrier's own reporting rather than a delay in Swap.
Processing depends on your workflow. Where a return goes through quality control or manual review, Return processed fires when you process it, not when the parcel arrives.

One difference worth knowing when building templates

The array of returned items is named differently depending on the event:

Return created and Return processed use item_details
Return tracking update and Return delivered use items_details

A template variable that works in one flow renders empty in the other, with no error. Check the event you are building against. For how to reference event data in a Klaviyo template, see Klaviyo's How to use event data to personalize email and SMS flows.

For the full property list on each event, see the Klaviyo Events API documentation.