Map the business process to Klaviyo's data model, not just the source schema
Start with the business process, not the tables in your source system.
Before designing payloads, identify:
- Are you hosting sign-up forms on your site?
- Which profile properties will you use for segmentation or to personalize message content?
- Which onsite actions should trigger messages?
- What dynamic data do you want to display in messages?
- Will any metric need unique content? (For example, content by order type)
Start with the use cases, required event metrics, and the data needed in messages before defining the integration. Then work with your business team to understand what Klaviyo should be able to do with this data.
Treat events as immutable
An event is a record that something happened. It's not an order row that Klaviyo will continuously update.
Once an event is created, don't design your integration around overwriting it. Use clear event names and include the properties needed for segmentation, personalization, and reporting.
For each event, define and test:
- The event name
- The profile identifier
- The event timestamp
- A stable unique event ID for deduplication
- The properties required by downstream flows and segments
- The numeric value and value_currency, when applicable
- The behavior when the same event is replayed
Test each event in a test account before going live. Test representative payloads: not just whether the request succeeds, but whether the resulting profile, event, segment, and flow behavior is correct. Sync a representative sample of historical events using the backfill flag so they don't trigger flows, and use a limited rollout for high-risk integrations.
Backfill the history your use cases require
Backfilling well pays off beyond migration. Done right, it also feeds segmentation, reporting, and predictive analytics.
When you backfill data:
- Use the original event timestamp, not the time the data was imported or changed
- Use the backfill flag so historical events don't trigger live flows
- Include a stable unique ID for each event
- Include a profile identifier that resolves to the intended profile
- Send numeric values and currency correctly
- Validate the backfill before enabling campaigns, flows, or predictions that depend on it
For predictive analytics specifically, backfilling alone doesn't guarantee that predictions will appear. Klaviyo requires Placed Order events from an ecommerce integration or the API, at least 500 customers who have placed an order, at least 180 days of order history with orders in the last 30 days, and some customers with three or more orders. Include the actual order value with each Placed Order event so CLV can be calculated correctly.
Make consent a deliberate part of your architecture
Consent is also part of the data model, and it's channel-specific. Don't treat an event, profile identifier, or consent in one channel as permission to message through another channel.
Preserve email marketing, text messaging marketing, and WhatsApp consent as separate states. Update consent explicitly through the appropriate subscription or consent path. Decide which system is the source of truth for consent, so syncs between systems don't overwrite newer consent with older data.