Skip to main content

Fundamentals of building with Klaviyo

Course overview
Best Practice
3 min read

Foundational best practices for building with Klaviyo

The most important data decisions happen before you send your first API request. A strong Klaviyo integration starts with the customer experience you want to create, then works backward to determine how data should be modeled, identified, tested, and activated. Four practices make that possible.

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.

A receptionist sitting at a front desk, talking on a mobile phone while writing on a clipboard.

Treat events as immutable

An event is a record that something happened. It's not an order row that Klaviyo will continuously update.

A woman wearing glasses and a blue blouse holds printed design sheets while speaking with a colleague.

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.

A smiling woman with curly dark hair stands behind a counter in a juice bar, surrounded by fresh fruits and a juicer machine.

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.

A woman standing with her arms crossed in front of a dark teal wall decorated with vintage woodworking tools, wearing a white button-down shirt and a tiger-print midi skirt.

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.

Foundational best practices for building with Klaviyo