Understanding data warehouse import in Klaviyo

Introduction

Data warehouse import allows Klaviyo to connect directly to your Snowflake, BigQuery, Redshift, or Databricks data warehouse and configure import syncs for tables (or views) of profile and event data.

How does data warehouse import in Klaviyo work?

After establishing a connection to your warehouse, you can select a dataset (e.g., a table or a view) to sync.

Your table or view must include a timestamp column that records when each row was added or updated, such as updated_at or modified_at. Select this column under Change detection when you configure the sync. Update its value whenever a row changes, and do not move it backward to an earlier time.

For a profile sync, include at least 1 profile identifier, such as an email address, phone number, or external ID. Map your data columns to the profile properties you want to update, including custom properties.

For an event sync, map an event timestamp and at least 1 profile identifier. Choose a single event type for the sync or map a column containing an event type for each row. Use a separate column for change detection so historical event dates do not determine when rows are picked up for import.

Scheduled syncs import existing data and continue importing new or updated rows at your chosen interval (e.g., hourly or daily), using the change detection timestamp to identify changes. Profile syncs create or update profiles; event syncs add events.

You can also choose a manual sync, which runs when you select Run sync.

If you do not have a fully joined dataset with all the fields you want to sync, you can create multiple syncs with different field mappings (e.g., contact info, loyalty balances, and custom segments).

When using multiple profile syncs, use consistent identifiers across your tables to help match rows to the same profile. Each non-identifier profile property can be mapped from only 1 source; identifiers can be reused across sources.

Email and text messaging consent use the same valid values and formats as file or SFTP uploads. For consent fields and formatting guidance, see How to import subscribers to a list.

Common use cases

Profile management

• Create new profiles in Klaviyo that originate in systems not directly integrated with Klaviyo (e.g., POS, reservation, or order management systems).
• Update profile info in Klaviyo from offline sources that are available in-warehouse.

Profile enrichment

• Sync loyalty program balances to a custom Loyalty_Balance property.
• Sync scores or categories from custom models running in the warehouse (e.g., intent scores for bespoke lifecycle events, affinity categories, churn risk, or LTV metrics).
• Sync third-party demographic or behavioral enrichment data to custom profile properties.
• Sync support or service touch points into custom profile fields to represent whether the customer has open service requests, days since last service visit, or the most recent category of support interaction.

Custom segmentation

• Perform complex segmentation in-warehouse and sync the segment names to custom profile properties to use as criteria in segments or flows.
• Perform segmentation in-warehouse based on sensitive, confidential, or regulated data and sync segment group assignments or profile flags with sanitized names (e.g., Group A, Group B) as a custom profile property.

Setup guide

Establishing a connection

These articles provide step-by-step instructions for setting up data warehouse import.

Connecting Klaviyo and Snowflake

Connecting Klaviyo and BigQuery

Connecting Klaviyo and Redshift

Connecting Klaviyo and Databricks

Create a profile import sync

After preparing your warehouse and validating its connection, create a profile import sync in Klaviyo:

1. Go to Advanced > Data management > Syncing, then select your warehouse connection.
2. Click Add source. Enter a unique sync name in the Name field and select your table or view under Data source.
3. Select Profiles under Data object types.
4. Under Cadence, choose Schedule run and set the interval, start date, start time, and timezone. Choose Manual if you want to start each run yourself.
5. Click Next. Under Change detection, select your timestamp column in New Row Detection. Map at least 1 profile identifier and the other profile properties you want to import.
6. Click Done to save the sync.

If you chose Manual, open the saved sync and select Run sync to begin importing.

Importing event data

For event-specific fields and setup instructions, see Understanding data warehouse event import in Klaviyo.

Troubleshooting syncs

If a sync does not import the data you expect, check its status and error details before testing your profile data with a CSV upload.

1. Go to Advanced > Data management > Syncing, select your warehouse connection, then click the sync name.
2. On the Runs tab, review the Ingested and Failed counts. A Completed status can still include failed rows.
3. For a completed run with failed rows, open the run’s menu and select Download error file if the option is available.
4. Open the Logs tab and review Periodic or Historical logs for details about the affected sync.

Validate profile data with a CSV import

A CSV import can help identify profile-data formatting problems, especially with consent values and timestamps. It does not test your warehouse connection or the sync’s change detection configuration. For the full upload procedure, see How to import subscribers to a list.

Use a separate test list with no list-triggered flows. The import still creates or updates profiles in your account and applies any consent values you map from the file.

1. Export your profile table or view to a CSV file.
2. Go to Audience > Lists & segments in Klaviyo.
3. Select a separate test list, or create a new list for testing.
4. Select Import contacts in the Manage list menu in the top right.
5. Upload the CSV file from step 1.
6. Map the columns you want to test to the same Klaviyo profile properties and data types used by your warehouse sync.
7. If you see Next after mapping, click it, then select No on the consent confirmation screen to avoid adding bulk consent. Consent values mapped from the file still apply.
8. Click Import. When processing finishes, review the import details and select Download error file if available to see skipped rows and their errors.

Correct any errors in your warehouse data and advance the affected rows’ change detection timestamps to reflect when you corrected them, so a later incremental sync can import them.