Meet Flexie, a large yoga and pilates studio chain migrating to Klaviyo. Before they can tap into personalized experiences, they need to connect their tech stack across the customer journey, which means Klaviyo ingesting swaths of data to drive that personalization.
This course covers the ways Klaviyo ingests data, which method fits your use case, and the nuances of each. Take Flexie's setup: they use MindBody as their fitness and wellness platform, and their developer team needs to confirm the native attributes cover their use case, or whether the API has to supply what's missing. Then they need to confirm the data is stored the way they intended. If their team stores data in the wrong place, like a profile property that should have been an event, some segments become impossible, and the Flexie developers have to redo part of their integration.
Before we get into the gotchas, here are the main ways Klaviyo ingests data.
Typical ingestion methods
Client-side API calls run from the browser or app with the public key and are limited to a safe subset of actions like creating custom events, registering consent, or updating simple profile properties.
Flexie uses a custom sign-up form on their site to subscribe to emails. Because this data originates from a user interaction in their browser or app, Flexie's developer team uses a client-side API to complete this action.
Server-side calls use the private key and grant full access: creating and updating profiles, managing consent, handling segments and flows, and triggering test events during flow debugging.
When Flexie sends membership details from their fitness and wellness platform, like a new membership and its start date, to trigger a confirmation email, they use a server-side API. That data comes from a trusted backend and requires a private key.
SDK and onsite tracking (JavaScript and Mobile SDKs)
These SDKs for web and mobile avoid building event tracking from scratch. Helpful for sending behavioral tracking or identifying users directly in Klaviyo.
When Flexie tracks onsite or in-app behavior (like the users who keep eyeing those yoga mats in their ecommerce integration), an embedded SDK creates the event Flexie's marketing team uses to send a browse abandonment email.
File and feed based (CSV uploads, SFTP, catalog feeds, web feeds)
This covers importing or syncing data through files instead of live API calls and is useful for creating profile attributes, catalogs, or bulk data that may not need continuous updates.
Flexie uses file-based imports when data doesn't need to stay continually in sync (like an upload of historical data from Flexie's previous email service provider) or when building a live integration is too costly. The trade-off here is that improperly formatted or very large files can fail or take too long to process.
Syncs, webhooks, and native capture (data warehouse, webhooks, sign-up forms)
Webhooks let you build custom logic tied to a flow: syncing data, sending information to another platform, or creating a custom event in Klaviyo that triggers a separate flow.
Use a webhook when an external system needs to react to a Klaviyo event (or vice versa) and no native integration exists. Use native syncs and sign-up forms when Klaviyo already has a built-in capture method. No custom code required.
When a member books a class in MindBody, a webhook sends the booking to Flexie's backend, which creates a Booked Class event in Klaviyo. That event triggers the class confirmation flow.
Data warehouse syncs bring in data that's already been calculated or modeled in your warehouse, on a schedule. Use them when the values already exist there and don't need to update instantly.
Flexie's data team calculates each member's lifetime value and churn risk in their warehouse. A scheduled sync sends those values to Klaviyo profiles, so marketing can segment on them.
When to use each ingestion method
If your data is... | Use this method | Why |
|---|---|---|
A real-time user action in the browser or app | Client-side API or SDK | Public key, safe data only, fires the moment it happens |
Coming from your backend, or needs a private key (orders, memberships, account changes) | Server-side API | Private key required, never exposed publicly |
Historical or doesn't need to stay live | File or feed-based import | Built for bulk, not built for speed |
A reaction to an event in another system with no native integration | Webhook | Custom logic, triggered on demand |
Already supported by a built-in Klaviyo capture method | Native sync or sign-up form | No code needed, don't rebuild what exists |
Coming from an app that many businesses will connect | OAuth | Scoped, revocable access, no private key handed over |
Already calculated in your data warehouse | Data warehouse sync | Scheduled, built for modeled values, not real-time events |
Common gotchas
When you're ingesting data into Klaviyo, keep an eye out for these common gotchas.
Select a gotcha to expand it.
Native/third-party app not syncing all the data you need
What goes wrong: A native or third-party integration, like MindBody, syncs a limited default set of fields, i.e. membership tier, name, class attendance. It omits data you need, like the goal preferences members select at sign-up. Teams often assume the integration covers everything, and don't notice the gap until marketing wants to segment by fitness goal.
Workaround: When the native sync misses a field, add narrow custom logic instead of rebuilding the whole integration.
Example: Flexie's MindBody sync carried membership tier, name, and class attendance to Klaviyo, but never sent the goal preferences (strength, flexibility, weight loss) members pick during sign-up. Flexie's dev team set up a webhook from MindBody's sign-up form that pushes the goal preference to the Klaviyo profile via API, so profiles stayed complete without touching MindBody's core sync.
Flows can't "wait" dynamically for a future date without the right data structure
What goes wrong: Klaviyo flows don't support a dynamic wait driven by an arbitrary value. You need a date-type profile property or a custom object, per Klaviyo documentation, to schedule actions relative to a specific date.
Workaround: Trigger a flow from the appointment-booked event via webhook. That flow sends the confirmation email and creates a custom object record on the profile with the appointment date. A second flow uses a date-based trigger on that record's date attribute to fire one day before the appointment. After sending the reminder, a webhook deletes the record to avoid lingering data.
Example: A Flexie member books a Vinyasa flow. A webhook triggers flow 1, which sends a confirmation and creates a custom object record with the date. Flow 2 watches the date and fires the reminder one day prior to the class. After the reminder sends, the webhook removes the custom object record.
Webhook failures happening silently
What goes wrong: If a webhook times out, experiences an outage, or is misconfigured, downstream actions don't run. No custom object record gets created, no reminder is scheduled, and there's often no alert. The automation simply "didn't run" for that person, which is hard to spot.
Workaround: Log every webhook call (success and failure) on the sending side so you can reconcile counts, and implement a periodic backfill that compares bookings against custom object records in Klaviyo to detect missed items.
Example: A brief outage on MindBody's booking platform kept three class bookings from firing the webhook. Nobody noticed until a member showed up saying she never got her class reminder. By then it was too late to send one.
Getting the trigger data type wrong (date/timezone) breaks a date-based flow
What goes wrong: Date-based triggers require correctly formatted dates with proper timezone handling. If the appointment date arrives without timezone conversion or as text instead of a date type, the reminder can fire on the wrong day or not at all.
Workaround: Verify the date property's format and timezone handling before using it as a trigger, and test bookings near timezone boundaries (for example, late evening) to catch off-by-one-day errors.
Example: An appointment booked at 11pm local time stored in UTC without conversion caused the "one day before" reminder to fire two days early because the date rolled over.
Native "Added to Cart" event doesn't carry a full product list
What goes wrong: Shopify's native "Added to Cart" event fires per product added or edited in the cart and doesn't include a consolidated list of current cart items. That prevents sending an email that shows every product added but not purchased over a time window.
Workaround: Create a custom storefront event with a different name than the native event that captures the full cart contents at that moment, and trigger the flow from that custom event instead.
Example: Flexie wanted an abandoned-cart email listing every retail item, like mats, blocks, and apparel, a customer added in the last few hours. The native event couldn't supply that, so Flexie's dev team set up a custom "Cart Snapshot" event that fired whenever the cart updated, carrying the full product list. The flow triggered off that instead of the native "Added to Cart" event.
Assuming event data can be updated later (Event Immutability)
What goes wrong: Developers sometimes treat Klaviyo's events database like a standard SQL database, assuming they can UPDATE a payload later if they missed a field. Klaviyo events are immutable, point-in-time ledgers. You can't patch, update, or append properties to an event once it's ingested.
Workaround: Ensure your event payloads are comprehensive at the exact time of ingestion. If you discover a critical data point was missing from an event, the only fix is to delete the metric entirely (wiping all history) and perform a full historical replay.
Example: A Flexie developer forgot to include the promo_code field in the payload for the annual membership sign-up event. They caught it a month later, during Flexie's New Year membership push. There was no way to retrofit the code onto past events, so that promo performance data was gone for that cohort, permanently.
Batch-loaded data used as a flow trigger
What goes wrong: A nightly warehouse sync or CSV import updates a profile property, and a flow is triggered when profiles reach that value, for example by entering a segment based on it. Two failure modes happen at once. The flow fires hours after the real-world event, and the whole batch trips the trigger simultaneously, so thousands of people get messaged in one burst.
Workaround: Trigger on real-time events sent via the API; use batch-synced properties as flow filters or segment conditions instead. Where a date drives the timing, use a date-property-based trigger so the schedule comes from the data, not from when the sync happened. Add flow filters and smart sending as a blast-radius guard before the first real import.
Example: Flexie runs a nightly sync from MindBody to calculate and update a membership_tier profile property, which triggers a "Welcome to Elite Member" flow. The latency problem: a member hits the class-count threshold for Elite status at 2pm but doesn't get the celebratory email until the batch runs at 3am. The blast-radius problem: Flexie's ops team recalculates tiers across every location after a system update and updates 10,000 profiles at once, so the flow fires for all 10,000 members simultaneously and overwhelms customer support.
Activity: Match the scenario with the best ingestion method for the data
Use data in Klaviyo
See every way to get data into Klaviyo, from native integrations to APIs and SFTP.
Integrate a wellness platform
Follow Klaviyo's guide for integrating a fitness or wellness platform, like the one Flexie uses.
Import profile and event data with SFTP
Learn how to bulk import historical profiles and events with Klaviyo's SFTP tool.