This article covers common issues you may encounter when setting up or using the Klaviyo integration with Swap Returns V2, and how to resolve them.
Events not appearing in Klaviyo
Check that the integration is enabled
The Klaviyo integration must be activated by Swap Support before it can be used. If you haven't requested this yet, contact support.
Check that Klaviyo Email Management is enabled
Go to Settings → Returns → Emails and confirm that Klaviyo Email Management is turned on.
Check that at least one event is enabled
At least one event must be toggled on in the Klaviyo Email Management panel. If all events are disabled, nothing will be sent to Klaviyo.
Check your API key
Go to Integrations → Klaviyo → Settings and confirm your API key is correct. If you've regenerated the key in Klaviyo, you'll need to update it in Swap as well.
Use a test event
Go to Settings → Returns → Emails, find any event, and click Send test. This sends a sample payload to Klaviyo so you can confirm the connection is working and the metric appears.
Flows not triggering
Check the metric name matches exactly
Klaviyo flow triggers are case-sensitive. Make sure your flow uses the exact metric name as it appears in Klaviyo — for example, V2- Return Created, not Return Created. See the full event name list in Klaviyo event types explained.
Check the flow is active
In Klaviyo, make sure the flow is published and not in draft or manual mode.
Check the event is enabled in Swap
If the event is disabled in the Klaviyo Email Management panel, no data will be sent, and the flow won't trigger.
Duplicate emails being sent to customers
This happens when both Klaviyo and Swap's native emails are active at the same time.
Go to Settings → Returns → Emails and make sure Klaviyo Email Management is enabled, and Swap's native emails are disables
Missing or incomplete event data
Some fields are only present in certain events or when specific features are in use:
quality_controlfields are only included when QC is part of the returninstant_exchange_detailsis only included for instant exchange returnstrackingfields are only present in Tracking Update and Delivered events
If a field is missing from your payload, check the Klaviyo event data reference to confirm whether it applies to that event type.
Customer profiles not being created in Klaviyo
Swap creates a Klaviyo profile using the customer's email address. If profiles aren't being created:
Confirm the customer has an email address on their Shopify account
Confirm your API key has the correct permissions to create and update profiles in Klaviyo
API key errors
If you see an error after saving your API key in Swap:
Make sure you're using a private API key, not a public key
Check the key hasn't been deleted or rotated in Klaviyo
If needed, regenerate the key in Klaviyo and update it in Swap under Integrations → Klaviyo → Settings