App guides
The Klaviyo app sends your store's checkout and order events to Klaviyo, and subscribes customers who opt in to email or SMS marketing. Each event arrives in Klaviyo as a metric, like Order Submitted, with the cart or order total, the items and the customer's profile, so you can use it to trigger flows.
The app replaces Swell's built-in Klaviyo integration and sends the same metric names and properties.
| When | What the app does |
| A cart is created | Sends Checkout Started. |
| Swell marks a cart abandoned | Sends Abandoned Checkout. |
| An order is placed | Sends Order Submitted. |
| An order is delivered | Sends Order Fulfilled. |
| An order is canceled | Sends Order Canceled. |
| The event's customer accepts email or SMS marketing | After sending the event, subscribes the customer in Klaviyo and adds them to your list. |
Each event can be turned off in the app settings. Events for carts and orders linked to a customer account are sent with the customer's profile.
- A Klaviyo account, and the Owner or Admin role in it to manage API keys.
- A Klaviyo list for customers who accept email marketing. If you want SMS subscribers, SMS set up in your Klaviyo account, and optionally a separate list for them.
- Opt-ins at checkout. Customers accept marketing with the opt-ins in Settings > Checkout in Swell. The SMS opt-in is off by default, so turn it on to collect SMS subscribers.
- If your store uses Swell's built-in Klaviyo integration, plan to turn it off when you install the app. Running both sends every event to Klaviyo twice.
Install Klaviyo from the Swell App Store, and set it up in your test environment before the live one.
If the built-in Klaviyo integration is on when you install the app, Swell asks how to handle the conflict. Click Disable conflicting integration to turn off the built-in integration and install the app. Ignore conflict installs the app and leaves the built-in integration on. You can turn the built-in integration on again later from Integrations, and its settings are kept.
Copy your API keys
In Klaviyo, click your account name in the lower left, click Settings, and open the API keys tab. Copy the Public API Key (also called the Site ID). Then click Create Private API Key, choose Custom, give it Full access to Lists, Profiles and Subscriptions, and copy the key. Klaviyo shows a private key only once.
Find your list IDs
In Klaviyo, go to Audience > Lists & segments, open the list for email subscribers, and open its Settings. Copy the List ID. If you use a separate list for SMS subscribers, copy its ID too.
Add them to the app
In Swell, go to Apps > Klaviyo > Settings and enter the Public API Key (Site ID), Private API Key and Email List ID. To subscribe customers to SMS, turn on Enable SMS Marketing, and enter the SMS List ID if you use a separate list. Click Save settings.
Choose the events
All five events are on by default. Turn off the ones you don't use, such as Track Checkout Started, and save.
Place a test order
Place a test order with a customer who accepts email marketing at checkout. In Klaviyo, open the customer's profile: Order Submitted is in the activity log, email consent shows Subscribed, and the Lists and segments tab shows your list.
Go live
Settings are saved separately for each environment. In the live environment, repeat steps 3 and 4 with the keys and lists your store uses. Test events go to the Klaviyo account whose keys you enter, so use a separate Klaviyo account or test list for the test environment.
Klaviyo creates each metric the first time the app sends it, and you can then use it as a flow trigger. For example, trigger cart recovery emails on Abandoned Checkout, order follow-ups on Order Submitted, and review requests on Order Fulfilled.
Each event's value is the cart or order total, in the record's currency. Its properties are the cart or order record from Swell, with items replaced by a short list of each item's name, SKU, image, price, discount, tax and quantity, and items_product_slugs with the product slugs. Use these properties in flow emails, for example to list the items in an order.
Events for a cart or order linked to a customer account are sent with the customer's email, first and last name, phone number and the account's shipping address. The phone number is converted to international format, using the shipping country for numbers without a country code, and left out if it can't be converted. Carts and orders that aren't linked to a customer are sent with an anonymous ID, such as a cart created before the customer enters an email.
After sending an event for a customer account, the app checks the account's opt-ins:
- A customer who accepts email marketing gets email marketing consent in Klaviyo.
- A customer who accepts SMS marketing gets SMS marketing and transactional consent, if Enable SMS Marketing is on and the account has a valid phone number.
- The customer is added to the Email List ID list for email and to the SMS List ID list for SMS, so a customer who accepts both joins both lists. When the SMS list is empty, SMS subscribers are added to the email list.
- Customers who didn't opt in aren't subscribed or added to a list.
Klaviyo applies the list's opt-in setting. With double opt-in, the customer gets a confirmation email and is subscribed once they confirm. The app never unsubscribes anyone: a customer who stops accepting marketing in Swell stays subscribed in Klaviyo until they unsubscribe there.
Settings are in Apps > Klaviyo > Settings and are saved separately for each environment.
| Setting | Description | Default |
| Public API Key (Site ID) | Your Klaviyo public API key. Required. Used to send events. | None |
| Private API Key | A Klaviyo private API key with full access to Lists, Profiles and Subscriptions. Required. Used to find profiles and subscribe them. | None |
| Email List ID | The list for customers who accept email marketing. Required. | None |
| Enable SMS Marketing | Subscribes customers who accept SMS marketing to SMS. | Off |
| SMS List ID | A separate list for SMS subscribers. When it's empty, SMS subscribers are added to the Email List ID list. | None |
| Track Checkout Started | Sends Checkout Started when a cart is created. | On |
| Track Abandoned Checkout | Sends Abandoned Checkout when a cart is abandoned. | On |
| Track Order Submitted | Sends Order Submitted when an order is placed. | On |
| Track Order Fulfilled | Sends Order Fulfilled when an order is delivered. | On |
| Track Order Canceled | Sends Order Canceled when an order is canceled. | On |
If one of the three required settings is empty, the app sends nothing.
- The app sends these five events only. Product views, added-to-cart, refunds and subscription events aren't sent.
- Checkout Started is sent when the cart is created, usually when the first item is added, not when the customer reaches checkout. At that point most carts aren't linked to a customer yet, so the event goes to an anonymous profile. Use Abandoned Checkout for cart recovery.
- Klaviyo records each metric once per cart or order and profile. A cart abandoned a second time doesn't create a second Abandoned Checkout.
- Customers are subscribed from events for carts and orders linked to their account. Orders from checkout always are, but carts often aren't until the customer enters an email. The app subscribes customers but never unsubscribes them.
- Past carts and orders aren't sent. The app sends events that happen after it's set up.
- Events aren't retried. If Klaviyo can't be reached or rejects an event, the error is logged and the event isn't sent again. The exception is a rejected phone number: the event is sent once more without it.
- One list for email subscribers and one for SMS subscribers. Per-product or per-segment lists aren't supported.
The app logs each event it sends and each error. In the Swell dashboard, the logs are under Developer > Console > Logs.
Check that the Public API Key (Site ID), Private API Key and Email List ID are all filled in, and that the event's switch is on. The logs show "Klaviyo: missing required settings" when a required setting is empty.
Check that the customer accepted marketing: the Swell customer page shows Accepts email marketing or Accepts SMS marketing. Then check that the private key has full access to Lists, Profiles and Subscriptions, and that the list ID is right. If the list uses double opt-in, the customer is subscribed after they confirm. For SMS, also check that Enable SMS Marketing is on, that the account has a valid phone number, and that SMS is set up in Klaviyo.
The built-in Klaviyo integration is probably still on. Turn it off in Integrations.
This is expected. The cart is created before the customer enters an email, so the event isn't linked to a customer yet.
Uninstalling the app stops sending events and subscribing customers. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.
Profiles, metrics, consent and list members stay in Klaviyo. To send events with the built-in integration again, turn it on in Integrations.
The app adds no fields to Swell records. The cart-events function runs on cart.created and cart.abandoned, and order-events runs on order.submitted, order.delivered and order.canceled. Each loads the cart or order with its account and items, and sends it to Klaviyo's Client Events API with the public key, using API revision 2024-02-15:
{
"type": "event",
"attributes": {
"unique_id": "order-submitted-<order id>",
"value": 128,
"value_currency": "USD",
"metric": { "data": { "type": "metric", "attributes": { "name": "Order Submitted" } } },
"profile": { "data": { "type": "profile", "attributes": {
"email": "maya.chen@example.com", "first_name": "Maya", "last_name": "Chen",
"phone_number": "+15035550142",
"location": { "address1": "1420 SE Ash St", "city": "Portland", "region": "OR", "country": "US", "zip": "97214" }
} } },
"properties": { "...": "the order record", "items": ["..."], "items_product_slugs": ["..."] }
}
}| Field | Description |
| unique_id | The metric name in lowercase with hyphens, and the cart or order ID. Klaviyo records only the first event with the same ID for a profile. |
| value, value_currency | The record's grand_total and currency. |
| profile | Email, first and last name, phone number and the account's shipping address. For a record without an account: anonymous_id, checkout- |
| properties | The record, with items replaced by id, price, price_total, discount_total, tax_total, product_slug, product_name, product_sku, product_image_url and quantity, plus items_product_slugs. |
To subscribe a customer, the app waits 2 seconds, finds the profile by email with the private key, and creates a profile subscription job with the consent and the list. Errors are logged and not thrown, so Swell doesn't retry the function.
Swell builds and maintains the Klaviyo app. For help with the app, email support@swell.is. For questions about your Klaviyo account, flows or lists, contact Klaviyo.