Understanding Klaviyo event types (Returns V2)

What triggers each of the four Klaviyo return events, when they arrive, and what you can build with them.

4 min readUpdated Oct 1, 2026

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

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.

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

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.

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.

More on Klaviyo