> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Klaviyo as a data source

> Bring data from Klaviyo to Nekt.

## Overview

Klaviyo is an email and SMS marketing automation platform used for targeted campaigns, customer segmentation, and marketing analytics. This connector extracts campaign metadata, automation flows, event data, and metric definitions from the Klaviyo API.

## Configuration

<Steps>
  <Step title="Add account access">
    To connect Klaviyo to Nekt, you need a **Private API Key** with read access.

    | Field               | Description                                                                                                                                                        |
    | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **Private API Key** | Your Klaviyo private API key. Found in **Settings > API Keys** in your Klaviyo account. The key must have read scopes for campaigns, events, flows, and metrics.   |
    | **Start Date**      | *(Optional)* Start date for incremental data sync in ISO 8601 format (e.g., `2024-01-01T00:00:00Z`). Only applies to streams that support incremental replication. |

    <Tip>
      To create an API key, go to your Klaviyo account **Settings > API Keys > Create Private API Key**. Grant **Read** access to Campaigns, Events, Flows, and Metrics.
    </Tip>
  </Step>

  <Step title="Select streams">
    Choose which streams you want to sync. Available streams are listed in the **Streams and Fields** section below.
  </Step>

  <Step title="Configure data streams">
    For each selected stream, configure:

    * **Layer**: Choose the destination layer (e.g., Bronze).
    * **Folder**: Organize data within the layer.
    * **Table name**: The table name in your lakehouse.
    * **Sync Type**: Incremental (recommended) or Full Sync.
  </Step>

  <Step title="Configure data source">
    Set up the source-level configuration:

    * **Description**: Add a description for this data source.
    * **Triggers**: Configure sync triggers (schedule or manual).
    * **Delta Log Retention Days**: Number of days to retain delta log history.
    * **Full Sync**: Optionally force a full sync on first run.
  </Step>

  <Step title="Check your new source">
    After saving, verify the source appears in your **Sources** list. Run a manual sync to validate that data flows correctly.
  </Step>
</Steps>

## Streams and Fields

<AccordionGroup>
  <Accordion title="campaigns">
    Email campaign metadata including status, audiences, scheduling, and tracking configuration. Supports incremental sync via `updated_at`.

    | Field              | Type     | Description                                    |
    | ------------------ | -------- | ---------------------------------------------- |
    | `id`               | string   | Unique campaign identifier                     |
    | `name`             | string   | Campaign name                                  |
    | `status`           | string   | Campaign status (e.g., draft, scheduled, sent) |
    | `archived`         | boolean  | Whether the campaign is archived               |
    | `audiences`        | string   | Target audience configuration (JSON)           |
    | `send_options`     | string   | Send options configuration (JSON)              |
    | `tracking_options` | string   | Tracking settings (JSON)                       |
    | `send_strategy`    | string   | Send strategy configuration (JSON)             |
    | `created_at`       | datetime | When the campaign was created                  |
    | `scheduled_at`     | datetime | When the campaign is scheduled to send         |
    | `updated_at`       | datetime | When the campaign was last updated             |
    | `send_time`        | datetime | Actual send time                               |
  </Accordion>

  <Accordion title="events">
    Raw event data including email opens, clicks, bounces, purchases, and custom events. Supports incremental sync via `datetime`. This is the granular data behind Klaviyo's reporting, enabling custom aggregations downstream.

    | Field              | Type     | Description                                   |
    | ------------------ | -------- | --------------------------------------------- |
    | `id`               | string   | Unique event identifier                       |
    | `timestamp`        | integer  | Event timestamp (Unix epoch)                  |
    | `event_properties` | string   | Event-specific properties and metadata (JSON) |
    | `datetime`         | datetime | Event date and time (ISO 8601)                |
    | `uuid`             | string   | Event UUID                                    |
  </Accordion>

  <Accordion title="flows">
    Automation flow definitions including status and trigger configuration. Supports incremental sync via `updated`.

    | Field          | Type     | Description                                          |
    | -------------- | -------- | ---------------------------------------------------- |
    | `id`           | string   | Unique flow identifier                               |
    | `name`         | string   | Flow name                                            |
    | `status`       | string   | Flow status (e.g., draft, manual, live)              |
    | `archived`     | boolean  | Whether the flow is archived                         |
    | `created`      | datetime | When the flow was created                            |
    | `updated`      | datetime | When the flow was last updated                       |
    | `trigger_type` | string   | What triggers the flow (e.g., segment, metric, date) |
  </Accordion>

  <Accordion title="metrics">
    Metric definitions that describe the types of events tracked in Klaviyo (e.g., "Opened Email", "Clicked Email", "Placed Order"). Reference data for joining with events.

    | Field         | Type     | Description                               |
    | ------------- | -------- | ----------------------------------------- |
    | `id`          | string   | Unique metric identifier                  |
    | `name`        | string   | Metric name                               |
    | `created`     | datetime | When the metric was created               |
    | `updated`     | datetime | When the metric was last updated          |
    | `integration` | string   | Integration details for the metric (JSON) |
  </Accordion>
</AccordionGroup>

## Implementation Notes

* **Authentication**: Uses Klaviyo's private API key via the `Klaviyo-API-Key` authorization header.
* **Rate limits**: The Klaviyo API enforces rate limits per endpoint. The connector handles rate limiting automatically with backoff.
* **Campaigns filter**: The campaigns stream currently syncs email campaigns only. SMS and push campaigns use separate channel filters.
* **Events volume**: The events stream can produce a high volume of records. Use the Start Date configuration to limit the initial sync window.
* **JSON fields**: Fields like `audiences`, `send_strategy`, `tracking_options`, `event_properties`, and `integration` are serialized as JSON strings for maximum flexibility. Parse them downstream as needed.