Klaviyo

This page contains the setup guide and reference information for the Klaviyo source connector.

Prerequisites

• Klaviyo account
• Klaviyo Private API key

Setup guide

Step 1: Set up Klaviyo

1. Create a Klaviyo account
2. Create a Private API key. Make sure you selected all scopes corresponding to the streams you would like to replicate. You can find which scope is required for a specific stream by navigating to the relevant API documentation for the streams Calabi Connect supports.

Step 2: Set up the Klaviyo connector in Calabi Connect

For Calabi Connect:

1. Log into your Calabi Connect account.
2. Click Sources and then click + New source.
3. On the Set up the source page, select Klaviyo from the Source type dropdown.
4. Enter a name for the Klaviyo connector.
5. For Api Key, enter the Klaviyo Private API key.
6. For Start Date, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated. This field is optional - if not provided, all data will be replicated.
7. For Lookback Window (Days), enter the number of days to look back when syncing data in incremental mode. This helps capture any late-arriving data. Defaults to 0 days if not provided. Only applies to the events_detailed stream.
8. (Optional) For Conversion Metric ID(s), enter a comma-separated list of Klaviyo metric IDs to limit the Campaign Values Reports and Flow Series Reports streams to specific conversion metrics. If not provided, the connector fetches reports for all metrics, which can be slow due to rate limits. See Analytics streams for details.
9. Click Set up source.

For Calabi Connect:

1. Navigate to the Calabi Connect dashboard.
2. Click Sources and then click + New source.
3. On the Set up the source page, select Klaviyo from the Source type dropdown.
4. Enter a name for the Klaviyo connector.

Supported sync modes

The Klaviyo source connector supports the following sync modes:

• Full Refresh - Overwrite
• Full Refresh - Append
• Incremental - Append
• Incremental - Append + Deduped

Supported Streams

• Campaigns
• Campaigns Detailed
• Campaign Values Reports - Analytics stream for campaign performance metrics
• Email Templates
• Events
• Events Detailed
• Flows
• Flow Series Reports - Analytics stream for automated flow performance over time
• GlobalExclusions
• Lists
• Lists Detailed
• Metrics
• Profiles

Analytics streams

The Campaign Values Reports and Flow Series Reports streams provide performance analytics from Klaviyo's Reporting API. Campaign Values Reports returns aggregated campaign performance metrics, while Flow Series Reports returns daily time-series data for automated flow performance.

These streams require the following API key scopes:

• Campaign Values Reports: campaigns:read
• Flow Series Reports: flows:read

Both streams partition data by conversion metric. By default, the connector fetches reports for all metrics in your account. You can use the optional Conversion Metric ID(s) configuration field to specify a comma-separated list of metric IDs (for example, RESQ6t,ABC123) to limit reporting to specific conversion metrics.

warning

These analytics endpoints have strict Klaviyo API rate limits (see documentation): 1 request per second burst, 2 requests per minute steady, and 225 requests per day. Because the connector makes a separate API request for each metric and each time window, syncing all metrics can take several hours and may exceed the daily rate limit. Specify only the conversion metrics you need using the Conversion Metric ID(s) field.

To find your conversion metric IDs:

1. Log into your Klaviyo account.
2. Navigate to Analytics > Metrics.
3. Select the metric you want to track conversions for (for example, "Placed Order").
4. Copy the metric ID from the URL, or use the Metrics stream to list all available metrics and their IDs.

Performance considerations

The connector is restricted by Klaviyo requests limitation.

The Klaviyo connector should not run into Klaviyo API limitations under normal usage. Create an issue if you encounter any rate limit issues that are not automatically retried successfully.

The Campaigns Detailed stream contains fields estimated_recipient_count and campaign_message in addition to info from the Campaigns stream. Additional time is needed to fetch extra data.

The Lists Detailed stream contains field profile_count in addition to info from the Lists stream. Additional time is needed to fetch extra data due to Klaviyo API limitation.

The Events Detailed stream contains field name for metric relationship - addition to info.

The Profiles stream can experience transient API errors under heavy load. In order to mitigate this, you can use the "Disable Fetching Predictive Analytics" setting to improve the success rate of syncs.

warning

Using the "Disable Fetching Predictive Analytics" setting means records on the Profiles stream will no longer contain the predictive_analytics field and workflows depending on this field will stop working.

Data type map

Integration Type	Calabi Connect Type
string	string
number	number
array	array
object	object