Klaviyo Integration (Returns V2) | Swap Knowledge Base

The Klaviyo integration allows you to replace Swap’s default email service with Klaviyo, so you can use your own Klaviyo flows, segmentation and templates for all return-related emails.

Once connected, Swap sends four return events to Klaviyo:

Return Created
Return Processed
Return Tracking Update
Return Delivered

These appear in Klaviyo as custom metrics and can trigger automated flows and personalised messaging.

This article is for users of Returns V2. For the Returns V1 version, click here.

Requirements

To use the Klaviyo integration, you need:

A Klaviyo account
A Klaviyo API Key
Swap Returns V2 enabled
The Klaviyo integration enabled on your store (Swap Support can activate this)

How the integration works

Swap sends events to Klaviyo whenever key actions occur in the returns flow.

Return Created
Sent when a customer submits a return.
Triggered immediately after the return is submitted.
Return Processed
Sent when you process a return in the dashboard (refund, exchange, QC update).
Sent with a short ~30 second delay so that all processing steps can complete.
Return Tracking Update
Sent when the return shipment receives a new tracking status (in transit, out for delivery, etc.).
Sent in real time when the carrier webhook arrives.
Return Delivered
Sent when the package is marked as delivered at your warehouse or logistics centre.

These events are displayed as custom metrics in Klaviyo and can be utilised in flows, segmentations, conditional splits, and template variables.

Event names in Klaviyo

In Klaviyo, the metrics appear with the following names:

Swap Event	Metric name in Klaviyo
Return Created	V2- Return Created
Return Processed	V2- Return Processed
Tracking Update	V2- Return Tracking Label Update
Return Delivered	V2- Return Delivered

If you cannot find your events, search for “V2- Return” inside Klaviyo’s metric picker.

Note: Klaviyo only displays a metric after it has received it at least once. If this is your first time setting up the integration, complete a test return in Swap so Klaviyo can receive the event and show it in the Metric Trigger list.

Data sent to Klaviyo

Each event includes a structured set of data that you can use inside your flows and templates. Below is a high-level overview of the available information.

Customer information

All events include the customer profile:

Email
First and last name
Phone number (if available)
Shipping address (street, city, postcode, country)

This ensures Klaviyo can create or update the customer profile and display personalised content.

Order and return details

Every event includes core return metadata:

Order name (e.g. “#1001”)
Return number
Return status
Return type (refund, exchange, store credit)
Whether the return is a Global order
Whether native taxes were used
Submitted or processed timestamps

This allows you to build flows based on refund-only returns, exchanges, international orders, etc.

Returned items and reasons

Item-level data is included on all events:

Product name
SKU
Variant ID
Quantity
Customer comment (if provided)
Main and sub return reasons
Whether an item was marked faulty
Product image URL (if available)

You can insert this into templates or create segments such as “Customers who returned faulty items” or “Returns for specific SKUs”.

Financial summary

Where applicable, events include a breakdown of financial values:

Refund amount
Store credit amount
New item value for exchanges
Additional payment or bonus amounts
Handling fees
Returned value totals

Multi-currency stores also receive:

Store currency
Customer-presented currency
Conversion rate
Both currency amounts

This ensures you can always display correct financial values in your email templates.

Shipping and tracking details

Tracking-related events include detailed shipment data:

Carrier name
Tracking number
Tracking URL
Shipping status text (e.g. “In transit”, “Delivered”)
Delivered date
Package weight and dimensions (if available)

Perfect for branded tracking emails or proactive customer updates.

Split shipments

If a return uses split shipments:

The first shipment appears in the main event data
All additional shipments appear in an array and include:
- Tracking numbers
- Labels / QR codes
- Carrier information
- Shipment statuses
- Item lists per shipment

This allows you to show multiple labels or tracking links when needed.

Instant Exchange & Quality Control (if enabled)

For stores that use these features, events also include:

Instant exchange status and hold information
Whether additional payment was made
Quality control status
Whether any items still require review
Whether faulty items were resolved

You can build flows like “Instant Exchange reminder”, “QC completed”, or “Faulty return follow-up”.

Setting up the Integration

Before you can send return data from Swap to Klaviyo, you’ll need to connect the two platforms.

Step 1: Create a private API key in Klaviyo

Go to Klaviyo → Settings → API Keys
Click Create Private API Key
Name it something like Swap Returns V2
Copy the key

For more information, please check Klaviyo’s documentation here.

Step 2: Connect Klaviyo in Swap

In the Swap dashboard, go to Integrations
Find Klaviyo and click Request (if not already enabled)
Once enabled, click Settings
Paste your API key and save

If the customer’s email address does not yet exist in Klaviyo, a new profile will be created automatically.

Step 3: Create flows based on Swap events

In Klaviyo:

Go to Flows
Create a new flow
Choose Metric Trigger
Select one of the Swap metrics (e.g. “V2- Return Created”)
Design your flow and email template using the event data

You can create flows for:

Return confirmation
Tracking updates
Exchange updates
Refund confirmations
Delivered notifications
QC review or completion
Instant exchange reminders

Note: Swap can provide ready-made email templates you can use as a starting point. Some events include additional fields (for example, faulty items or instant exchanges). You can add these fields to your Klaviyo templates if you wish. If you need access to the templates, please contact your Account Manager.

Troubleshooting

Events are not showing in Klaviyo

Try the following:

Complete a test return after enabling the integration
Check if the customer email exists in Klaviyo (or if a new profile was created)
Contact Swap Support to confirm that the Klaviyo feature is enabled for your store

The metric trigger does not appear

Search in Klaviyo for:

V2- Return

Metric names may vary slightly, but they all begin with V2- Return.

Klaviyo only displays a metric after it has received it at least once. If this is your first time setting up the integration, complete a test return in Swap so Klaviyo can receive the event and show it in the Metric Trigger list.

Emails are delayed

Only Return Processed has a delay (~30 seconds).

All other events are sent almost instantly.

Frequently asked questions

Can I use Klaviyo instead of Swap’s default email templates?

Yes. Once connected, Klaviyo completely replaces Swap’s email sending.

Does Klaviyo create customer profiles from return events?

Yes. If the profile does not exist already, Klaviyo creates it automatically when it receives the first event.

Do I need a Flow for every event?

No, you can build as many or as few flows as you want.

Most stores create at least:

Return confirmation
Tracking updates
Refund or exchange confirmation

Does the integration support multi-currency?

Yes, all events include both store and customer-facing currency values where applicable.

Event JSON Reference (Full Schemas + Examples)

The following schemas show the structure of the event data Swap sends to Klaviyo.

These are representative examples — your store’s data will vary based on configuration, shipping carriers, and return settings.

Return Created — JSON schema

{
  "customer": {
    "email": "",
    "first_name": "",
    "last_name": "",
    "phone": "",
    "address": {
      "street_1": "",
      "street_2": "",
      "city": "",
      "post_code": "",
      "province_code": "",
      "country": "",
      "country_code": ""
    }
  },
  "order": {
    "order_name": "",
    "order_id": "",
    "store_currency": ""
  },
  "return": {
    "return_number": "",
    "return_id": "",
    "return_date": "",
    "return_status": "",
    "return_type": "",
    "submitted_at": "",
    "instant_exchange": false,
    "faulty_order": false,
    "restocking": false,
    "ignore_return_window": false,
    "shop_now_bonus_applied": false,
    "return_is_required": false,
    "is_global_order": false,
    "is_native_taxes_order": false
  },
  "items": {
    "item_details": [
      {
        "name": "",
        "sku": "",
        "quantity": 1,
        "image": "",
        "return_reason": "",
        "sub_reason": "",
        "comment": "",
        "faulty_item": false,
        "return_required": false,
        "variant_id": ""
      }
    ],
    "items_returned_names": [],
    "items_returned_skus": []
  },
  "shipping": {
    "return_carrier": "",
    "return_label": "",
    "return_label_primary": "",
    "return_label_secondary": "",
    "return_qr": "",
    "return_label_commercial_invoice": "",
    "drop_off_url": ""
  },
  "financials": {
    "return_summary": {
      "returned_value": "",
      "refund_value": "",
      "exchange_products": [],
      "additional_value": "",
      "giftcard_credit_value": "",
      "new_items_value": "",
      "total_credit_value": "",
      "returned_item_count": "",
      "status": "",
      "conversion": false,
      "conversion_rate": null,
      "base_currency": "",
      "base_currency_amount": "",
      "presentment_currency": "",
      "presentment_currency_amount": ""
    },
    "handling_fee": ""
  },
  "additional_shipments": [],
  "instant_exchange_details": null,
  "quality_control": {
    "status": "",
    "needs_review": false,
    "has_pending_items": false
  },
  "applied_bonuses": {
    "shop_now_bonus_originally_applied": null,
    "shop_now_bonus_amount_used": null,
    "in_shop_shop_later_bonus": null
  }
}

Return Created — Example payload

{
  "customer": {
    "email": "[email protected]",
    "first_name": "Sarah",
    "last_name": "Jones",
    "phone": "+447000000",
    "address": {
      "street_1": "123 High Street",
      "street_2": null,
      "city": "London",
      "post_code": "E2 4AA",
      "province_code": null,
      "country": "United Kingdom",
      "country_code": "GB"
    }
  },
  "order": {
    "order_name": "#1032",
    "order_id": "123456",
    "store_currency": "GBP"
  },
  "return": {
    "return_number": "R1001",
    "return_id": "abc123",
    "return_date": "2025-11-13T12:44:00Z",
    "return_status": "pending",
    "return_type": "Refund",
    "submitted_at": "2025-11-13T12:44:00Z",
    "instant_exchange": false,
    "faulty_order": false,
    "restocking": false,
    "ignore_return_window": false,
    "shop_now_bonus_applied": false,
    "return_is_required": true,
    "is_global_order": false,
    "is_native_taxes_order": false
  },
  "items": {
    "item_details": [
      {
        "name": "Black Hoodie",
        "sku": "HD-BLK-01",
        "quantity": 1,
        "image": "<https://cdn.example.com/hoodie.jpg>",
        "return_reason": "Too Large",
        "sub_reason": "Sleeves too long",
        "comment": "Did not fit",
        "faulty_item": false,
        "return_required": true,
        "variant_id": "4324234234"
      }
    ],
    "items_returned_names": [
      "Black Hoodie"
    ],
    "items_returned_skus": [
      "HD-BLK-01"
    ]
  },
  "shipping": {
    "return_carrier": "Royal Mail",
    "return_label": "<https://label.example.com/l1>",
    "return_label_primary": "<https://label.example.com/l1>",
    "return_label_secondary": null,
    "return_qr": null,
    "return_label_commercial_invoice": null,
    "drop_off_url": "<https://dropoff.example.com>"
  },
  "financials": {
    "return_summary": {
      "returned_value": "49.99",
      "refund_value": "49.99",
      "exchange_products": [],
      "additional_value": null,
      "giftcard_credit_value": null,
      "new_items_value": null,
      "total_credit_value": null,
      "returned_item_count": "1",
      "status": "pending",
      "conversion": false
    },
    "handling_fee": null
  },
  "additional_shipments": [],
  "instant_exchange_details": null,
  "quality_control": {
    "status": "pending",
    "needs_review": false,
    "has_pending_items": false
  },
  "applied_bonuses": null
}

Return Processed — JSON schema

{
  "customer": {
    "email": "",
    "first_name": "",
    "last_name": "",
    "phone": "",
    "address": {}
  },
  "order": {
    "order_name": "",
    "order_id": "",
    "store_currency": ""
  },
  "return": {
    "return_number": "",
    "return_id": "",
    "processed_at": "",
    "return_status": "",
    "return_type": "",
    "instant_exchange": false,
    "faulty_order": false,
    "restocking": false,
    "return_is_required": false
  },
  "items": {
    "item_details": [],
    "items_returned_names": [],
    "items_returned_skus": []
  },
  "shipping": {
    "return_label": "",
    "return_label_primary": "",
    "return_label_secondary": "",
    "return_qr": "",
    "return_carrier": ""
  },
  "financials": {
    "return_summary": {},
    "handling_fee": ""
  },
  "processing": {
    "processed_by": {
      "first_name": "",
      "last_name": "",
      "user_id": "",
      "processing_mode": ""
    },
    "refund_id": "",
    "has_made_additional_payment": false,
    "are_faulty_items_resolved": false
  },
  "quality_control": {},
  "instant_exchange_details": null,
  "additional_shipments": []
}

Return Processed — Example payload

{
  "customer": {
    "email": "[email protected]",
    "first_name": "Sarah",
    "last_name": "Jones",
    "phone": "+447000000",
    "address": {
      "street_1": "123 High Street",
      "city": "London",
      "post_code": "E2 4AA",
      "country": "United Kingdom"
    }
  },
  "order": {
    "order_name": "#1032",
    "order_id": "123456",
    "store_currency": "GBP"
  },
  "return": {
    "return_number": "R1001",
    "return_id": "abc123",
    "processed_at": "2025-11-13T15:10:03Z",
    "return_status": "processed",
    "return_type": "Refund",
    "instant_exchange": false,
    "faulty_order": false,
    "restocking": false,
    "return_is_required": true
  },
  "items": {
    "item_details": [
      {
        "name": "Black Hoodie",
        "sku": "HD-BLK-01",
        "quantity": 1,
        "return_reason": "Too Large"
      }
    ],
    "items_returned_names": [
      "Black Hoodie"
    ],
    "items_returned_skus": [
      "HD-BLK-01"
    ]
  },
  "shipping": {
    "return_label": "<https://label.example.com/l1>",
    "return_carrier": "Royal Mail"
  },
  "financials": {
    "return_summary": {
      "refund_value": "49.99"
    }
  },
  "processing": {
    "processed_by": {
      "first_name": "John",
      "last_name": "Doe",
      "user_id": "789",
      "processing_mode": "manual"
    },
    "refund_id": "RF123",
    "has_made_additional_payment": false,
    "are_faulty_items_resolved": true
  },
  "quality_control": {
    "status": "passed",
    "needs_review": false,
    "has_pending_items": false
  }
}

Tracking Update — JSON schema

{
  "customer": {},
  "order": {
    "order_name": "",
    "return_type": ""
  },
  "tracking": {
    "shipping_status": "",
    "tracking_number": "",
    "carrier_name": "",
    "tracking_url": "",
    "delivery_date": "",
    "shipping_details": {
      "status": "",
      "delivered_date": "",
      "tracker_id": "",
      "tracking_number": "",
      "carrier_name": ""
    },
    "is_international": false,
    "postage_fee": null,
    "package_weight": null,
    "package_dimensions": {
      "height": null,
      "length": null,
      "width": null,
      "weight_unit": null
    }
  },
  "return": {
    "return_id": "",
    "return_number": ""
  },
  "items": {
    "item_details": []
  },
  "additional_shipments": [],
  "financials": {
    "return_summary": {}
  },
  "flags": {
    "faulty_order": false,
    "instant_exchange": false,
    "return_is_required": false
  }
}

Tracking Update — Example payload

{
  "customer": {
    "email": "[email protected]",
    "first_name": "Sarah",
    "last_name": "Jones"
  },
  "order": {
    "order_name": "#1032",
    "return_type": "Refund"
  },
  "tracking": {
    "shipping_status": "In Transit",
    "tracking_number": "TRACK123456",
    "carrier_name": "Royal Mail",
    "tracking_url": "<https://tracking.example.com/TRACK123456>",
    "shipping_details": {
      "status": "in_transit",
      "tracking_number": "TRACK123456",
      "carrier_name": "Royal Mail",
      "delivered_date": null
    },
    "is_international": false
  },
  "return": {
    "return_id": "abc123",
    "return_number": "R1001"
  },
  "items": {
    "item_details": [
      {
        "name": "Black Hoodie",
        "sku": "HD-BLK-01",
        "quantity": 1,
        "return_date": "2025-11-13T12:44:00Z"
      }
    ]
  },
  "financials": {
    "return_summary": {}
  }
}

Return Delivered — JSON schema

This is identical to Tracking Update, with:

"shipping_status": "Delivered"
delivered_date populated

Return Delivered — Example payload

{
  "customer": {
    "email": "[email protected]",
    "first_name": "Sarah",
    "last_name": "Jones"
  },
  "order": {
    "order_name": "#1032",
    "return_type": "Refund"
  },
  "tracking": {
    "shipping_status": "Delivered",
    "tracking_number": "TRACK123456",
    "carrier_name": "Royal Mail",
    "tracking_url": "<https://tracking.example.com/TRACK123456>",
    "shipping_details": {
      "status": "delivered",
      "tracking_number": "TRACK123456",
      "carrier_name": "Royal Mail",
      "delivered_date": "2025-11-16T09:20:00Z"
    }
  },
  "return": {
    "return_id": "abc123",
    "return_number": "R1001"
  },
  "items": {
    "item_details": [
      {
        "name": "Black Hoodie",
        "sku": "HD-BLK-01",
        "quantity": 1
      }
    ]
  },
  "financials": {}
}