Klaviyo Event Data Reference | Swap Knowledge Base

Each event sent from Swap to Klaviyo includes structured data about the return, order, customer, and items.

This data can be used in Klaviyo flows to:

Personalise email content
Apply conditional logic
Build segmentation based on return behaviour

How event data is structured

All Klaviyo events follow a consistent top-level structure:

customer
order
return
items
shipping or tracking (depending on event)
financials
additional_shipments
instant_exchange_details
quality_control

The exact fields included may vary depending on the event type.

Customer information

Each event includes customer details used to identify or create a Klaviyo profile.

Location in payload: customer

Field	Description
email	Customer email address
first_name	Customer first name
last_name	Customer last name
phone	Customer phone number (if available)
address	Nested object containing shipping address

Address fields include:

street_1
street_2
city
post_code
province_code
country
country_code

Order and return details

Information about the original order and the return.

Location in payload: order, return

Order

Field	Description
order_name	Order reference (e.g. “#1001”)
order_id	Internal order ID
store_currency	Store currency

Return

Field	Description
return_number	Human-readable return number
return_id	Unique return identifier
return_status	Current return status
return_type	Refund, exchange, or store credit
submitted_at	Timestamp when return was created
processed_at	Timestamp when return was processed (if applicable)
instant_exchange	Whether this is an instant exchange
faulty_order	Whether the return contains faulty items
is_global_order	Whether this is a global order
is_native_taxes_order	Whether native taxes were used

Returned items

Details of the items included in the return.

Location in payload: items.item_details[]

Field	Description
name	Product name
sku	Product SKU
variant_id	Variant identifier
quantity	Quantity returned
return_reason	Main return reason
sub_reason	Sub-reason (if provided)
comment	Customer comment
faulty_item	Whether item was marked faulty
return_required	Whether item must be returned
image	Product image URL (if available)

Additional arrays:

items_returned_names
items_returned_skus

Financial summary

Information about the financial outcome of the return.

Location in payload: financials.return_summary

Field	Description
returned_value	Total value of returned items
refund_value	Amount refunded
new_items_value	Value of exchanged items
giftcard_credit_value	Store credit issued
total_credit_value	Total credit provided
additional_value	Additional charges or payments
returned_item_count	Number of items returned
status	Financial status

Multi-currency fields (if applicable)

Field	Description
conversion	Whether conversion was applied
conversion_rate	Exchange rate used
base_currency	Store currency
base_currency_amount	Amount in store currency
presentment_currency	Customer currency
presentment_currency_amount	Amount in customer currency

Other

Field	Description
handling_fee	Any return handling fee

Shipping and tracking

Tracking-related fields vary depending on the event.

Return Created / Processed (label data)

Location: shipping

Field	Description
return_carrier	Carrier used
return_label	Label URL
return_label_primary	Primary label
return_label_secondary	Secondary label
return_qr	QR code (if applicable)
return_label_commercial_invoice	Commercial invoice
drop_off_url	Drop-off instructions URL

Tracking Update / Delivered (tracking data)

Location: tracking

Field	Description
shipping_status	Status (e.g. In Transit, Delivered)
tracking_number	Tracking number
carrier_name	Carrier name
tracking_url	Tracking link
delivery_date	Delivery timestamp

Additional tracking fields

The tracking object includes the following additional fields:

shipping_details.status
shipping_details.delivered_date
shipping_details.tracker_id
package_weight
package_dimensions.height
package_dimensions.length
package_dimensions.width
package_dimensions.weight_unit

Split shipments

If a return includes multiple shipments:

The primary shipment is included in the main event payload
Additional shipments are included in additional_shipments[]

Each object in additional_shipments[] contains shipment-level data, including:

Tracking information
Carrier information
Shipment status
Associated items

Instant exchange data

Location:

return.instant_exchange
instant_exchange_details

The following fields are used to represent instant exchange behaviour:

Field	Description
instant_exchange	Boolean indicating whether the return is an instant exchange
instant_exchange_details	Object containing additional instant exchange information

instant_exchange_details is included in the payload when applicable to the return.