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 |
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.
Quality control (QC)
Location: quality_control
Field | Description |
status | QC status |
needs_review | Whether review is required |
has_pending_items | Whether items are still pending |
Field availability
Not all fields are present in every event.
Field availability depends on:
The event type (Return Created, Processed, Tracking Update, Delivered)
The return configuration (e.g. instant exchange, QC, multi-currency)
All field names and structures in this document match the event schemas sent by Swap.