Understanding data warehouse event import in Klaviyo

You will learn

Learn how to use data warehouse event import to sync event data from your warehouse into Klaviyo, so you can power segments, flows, and reporting with behavior that originates outside of Klaviyo’s native integrations (e.g., POS systems, support platforms, or custom applications).

What is data warehouse event import?

Data warehouse event import lets Klaviyo connect directly to your data warehouse and configure import syncs from warehouse tables or views that contain event data.

Each row in your source table is treated as a single event in Klaviyo:

• The row’s timestamps, metric name, and identifiers define what happened, when, and for whom.
• Additional columns become event properties that you can use in segmentation, flows, and analytics.

Event import is built on the same data warehouse import infrastructure as profile import, but targets Klaviyo’s event ingestion pipeline instead of profiles.

How does data warehouse event import work?

After you connect Klaviyo to your warehouse and configure an event sync:

1. Klaviyo queries your warehouse for the configured table or view.
2. The first import reads the available history in your source. Later runs resume from saved progress using the change detection timestamp, so Klaviyo does not reprocess the entire table.
3. Each row is then processed as follows:
   • Klaviyo determines the metric name (event type) from either an existing API metric you select or the value of a designated metric name column in each row.
   • Event timestamp, profile identifiers, and optional unique ID and value are set based on field mappings configured during sync setup.
   • All remaining columns are ingested as event properties, using the column names as property names. Column names with 3 underscores (e.g., parent___child1, parent___child2) can be used to create an event property (parent) with child properties.
4. Klaviyo loads the resulting events into your account, where they behave like other custom API metrics in segmentation, flows, and analytics.

You can schedule recurring imports (e.g., hourly) or choose Manual to run imports when needed.

Before you begin

Make sure the following requirements are met before creating an event import sync:

• Your account has access to Advanced KDP and data warehouse import.
• Prepare the service-account credentials and schemas required for your warehouse. See the connection guides in Understanding data warehouse import in Klaviyo.
• Your source table or view contains the required columns below.
• You have sufficient privileges in your warehouse to expose the necessary tables/views to Klaviyo’s service user.

Source table structure for events

To ensure that your event data can be imported correctly, your source table or view must satisfy Klaviyo’s required fields and structure.

Required fields

The following columns are required for data warehouse event import:

Optional fields

These fields are recommended when applicable but not strictly required:

Event properties

All other columns in your table are treated as event properties:

• Column names become top-level property names unless they contain 3 underscores (___), which create nested child properties as described above.
• You don’t need to explicitly map every property; unmapped columns will be included as event properties.
• Nested JSON can be stored inside an individual property value if needed (for example, a JSON object of line items), but the property name itself comes from a top-level column.

Klaviyo performs best-effort type parsing for event properties and does not provide per-field transformation logic as part of the event import setup.

Common use cases

Customers typically use data warehouse event import for:

1) Importing offline or POS events

Bring in in-store or offline events (e.g., POS purchases, returns, or appointments) from your warehouse so that they behave like other Klaviyo events and metrics.

Examples:

• In-Store Purchase events with order totals, store location, and tender type
• Appointment Completed events with staff member, service type, and duration

2) Service and support interactions

Sync support and service events like ticket creation, resolution, or returns to enrich your customer timelines and power messaging based on service history.

Examples:

• Support Ticket Created and Support Ticket Resolved
• Order Returned with reason codes and refund amounts

3) Modeled or derived events

Convert warehouse-modeled behaviors into events that are easier to use in Klaviyo.

Examples:

• High Churn Risk events generated from a model in your warehouse
• Lifecycle Milestone Reached events when a customer moves stages in a custom lifecycle model

Set up a data warehouse event import sync

1) Connect your data warehouse

If your warehouse is already connected, skip to step 2. Otherwise:

1. In Klaviyo, go to Advanced KDP > Data management > Syncing.
2. Click Create sync if you already have syncs configured. Select Import data from your data warehouse, then select your warehouse connector.
3. Complete the warehouse preparation steps in the applicable connection guide linked from Understanding data warehouse import in Klaviyo.
4. Click Connect to followed by your warehouse name. Enter the required connection details, then click Next.
5. Click Test. After the connection succeeds and Klaviyo can access at least 1 table or view, click Next.

You can create multiple data warehouse import connections and add source tables or views to each connection.

Before creating the sync, decide which historical events to include. You can either:

• Point your event import at a table or view that already includes all relevant historical events, or
• Start with a dedicated historical table and later switch to a change-data-capture-backed view for ongoing updates. Keep the same mapped columns and give new rows change detection timestamps later than the sync’s saved progress.

2) Create a new event import sync

For a new connection, continue in the setup you opened above. For an existing connection, first:

1. From Advanced KDP > Data management > Syncing, select your warehouse connection.
2. Click Add source.

In sync setup:

1. Enter a Name for the sync and, optionally, a Description.
2. Under Data source, select the table or view that contains the events you want to import.
3. Under Data object types, select Events.

3) Choose sync cadence

1. Under Cadence, choose how to run the sync:
   • Schedule run: choose the interval under Every and set the Start Date, Start Time, and Timezone. The default interval is 1 hour.
   • Manual: save the sync without a recurring schedule and run it when needed.
2. Click Next to map fields.

4) Map required fields

Next, you’ll map columns from your warehouse table to Klaviyo’s required event fields.

Complete these mappings:

1. Under Change detection, select your change detection timestamp column in New Row Detection. Use a different source column from the event timestamp.
2. Under Event type, choose 1 of these options:
   • Same event type: select an existing API metric for all rows.
   • Specific event type for each row: select the column containing each row’s metric name. Use this option if the metric you need is not in the existing API metric list.
3. Under Event timestamps, select the column that records when the event occurred.
4. Under Profile properties, click Add mapping and map at least 1 profile identifier (e.g., email, phone number, external ID, or Klaviyo ID).

You can also map recommended fields:

• Unique ID
• Value

To keep currency metadata (e.g., USD), leave its column unmapped so it becomes an event property. There is no dedicated Value currency mapping.

Any remaining columns that you don’t explicitly map to these core fields automatically become event properties.

The configuration UI prevents you from mapping multiple columns to the same top-level field and validates that all required fields are present before allowing you to save.

5) Save and check the sync

1. Review your settings, then click Done to save the event import sync.
2. On the warehouse connection page, click the sync name. If setup returned you to the Syncing overview, select the warehouse connection first.
3. If you chose Manual, click Run sync to start the import. Scheduled imports run according to the cadence you selected.
4. Check Run history for progress and Logs for errors.

How imported events behave in Klaviyo

Once imported:

• Each row appears as an event of a custom API metric in Klaviyo.
• The metric name you mapped (or configured as a constant) determines the event type name you see in the product (for example, Placed Order).
• All profile identifiers are resolved to existing profiles where possible; otherwise, Klaviyo creates new profiles using the identifier fields provided, similar to other event ingestion paths.

You can use these events to:

• Build segments based on what someone has done and filter on event properties.
• Trigger and filter flows.
• Analyze behavior in metrics and reporting alongside events from other sources.

Limitations and best practices

Keep the following in mind when using data warehouse event import:

• Use event import for event data. To update profile properties, use profile import or other supported paths.
• The change detection timestamp must be different from the event timestamp. Using the same column for both can prevent you from safely importing historical events after your first sync.
• For historical backfills, use the time each row was loaded into the warehouse as its change detection timestamp. A job that creates a historical table can store that job’s timestamp on the rows to keep the range narrow. Do not recalculate this timestamp every time a view is queried, and follow the row-volume guidance below.
• Use a stable unique ID per event where possible to improve deduplication and make debugging easier. Reimporting the same ID for the same profile and metric is treated as a duplicate; it does not update the event’s properties.
• You can keep multiple event types (metrics) in the same table. Unmapped columns are included as event properties, so use separate views if you need different property sets for different metrics.
• For complex nested objects (e.g., line item arrays), we recommend flattening into multiple columns where feasible, especially for properties you expect to use in segmentation or flows.
• Keep historical change detection timestamps in a narrow range. During the initial backfill, Klaviyo reads data in 1-hour windows starting at the oldest change detection timestamp. A single record from 2023 when all others are recent can make that backfill slower because Klaviyo must advance through the intervening windows. Later runs resume from saved progress instead of starting from the oldest record again.
• Do not exceed approximately 100,000 rows in a single 1-hour change detection timestamp window. If too many rows share the same 1-hour window, the syncing query may time out.

Improve Snowflake query performance

Recommended Snowflake clustering key setup

For large Snowflake tables, a clustering key on the change detection timestamp can help queries skip unnecessary micro-partitions. Test representative queries before adding a key, and weigh any query savings against the Snowflake credits used to maintain clustering:

ALTER TABLE your_schema.your_table CLUSTER BY (your_change_timestamp_column);