# Set up the Klaviyo integration

> This guide describes how to set up the Talon.One Klaviyo integration.

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

## Setup steps

<StepsContainer>

### Sign in to Talon.One

1. Open your Talon.One deployment URL, for example: `https://mycompany.europe-west1.talon.one`.
1. Enter your credentials and sign in.

### Create a Third-party API key

Create a Klaviyo-specific [Third-party API
key](/docs/product/applications/manage-third-party-api-keys.md):

1. If you don't have an Application,
   [create](/docs/product/applications/create-and-manage-applications#create-an-application) one.
1. In your Application, click <Settings className="icon" /> **Settings** > **Integration API Keys**.
1. Click <Add className="icon" /> **Create API Key**.
1. In the **Create API Key** drawer, if you are asked for a key type, select **Production**.
1. In **Key name**, type a name to identify the key.
1. In **Key expiration date**, select a date.

   :::tip
   Avoid choosing expiration dates that fall at the end of the year or during other
   high-traffic periods.
   :::

1. In **Third-party integration**, select **Yes**.
1. From **Platform**, select **{props.partner}**.
1. Click **Create API Key**.
1. Click <Copy className="icon" /> to copy the key for use.

:::note
You cannot view or copy the API key after closing the drawer.
:::

### Create a custom attribute

Create a [custom
attribute](/docs/product/account/dev-tools/manage-attributes.md#create-a-custom-attribute)
in your Application to store the unique profile ID from Klaviyo:

- **Entity**: Customer Profile
- **Type**: String
- **API name**: `KlaviyoId`
- **Name**: `Klaviyo ID`
- **Description**: `The unique Klaviyo profile ID.`

### Create an instance

Create an [instance](/docs/dev/integration-hub/overview.md#integrations-and-instances) of
the Klaviyo integration in the [Integration Hub](/docs/dev/integration-hub/overview.md):

1. Open <Account className="icon"/> > **Integrations** > **Generic integrations**.
1. Open **Talon.One Klaviyo Integration** and click **Configure**. If instances
   already exist, click **Add Instance**.
1. On the **Initial Configuration** page, enter a descriptive name for the instance and
   click **Next**.

### Configure the connection

1. On the **Connections** page, in the **Talon.One Connection** section, click
   **Connection** > **Add new connection**.
1. Enter the following:

   | Field                             | Value                                                                                                                     |
   | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
   | **Name**                          | A descriptive name for the connection.                                                                                    |
   | **Talon.One Base URL**            | The base URL of your Talon.One deployment, including `https://`.Example: `https://mycompany.europe-west1.talon.one` |
   | **Talon.One Integration API Key** | The Third-party API key you [created](#create-a-third-party-api-key).                                                    |

1. In the **Klaviyo Connection** section, click **Connection** > **Add new connection**.
1. Enter a descriptive name for the OAuth connection and click **Connect**.
1. Authorize the connection in Klaviyo.
   :::note
    You may see an error message stating **Authorization failed**. You can ignore this
    message. The connection is still valid.
   :::
1. Switch back to Talon.One, ensure the connection is active, indicated by a green dot,
   and click **Next**.

### Configure the profile sync

1. On the **Profile Sync** page, under **Profile Identifier**, select the Klaviyo profile
   attribute that contains the unique customer profile ID. This attribute is matched
   against the customer integration ID in Talon.One.

   You can select from the following options:

   | Option         | Klaviyo profile attribute  |
   | -------------- | -------------------------- |
   | `external_id`  | `External ID`              |
   | `email`        | `Email`                    |
   | `id`           | `Klaviyo ID` / `Unique ID` |
   | `phone_number` | `Phone Number`             |

   For example, if you select `email` as the profile identifier, Talon.One matches
   the email addresses of your Klaviyo customers against the customer integration IDs in
   Talon.One. For more information, see [Data flow](/docs/dev/technology-partners/klaviyo/integrate-with-klaviyo.md#data-flow).
1. If desired, choose a profile identifier transformation.
1. Set the schedule for the profile sync. The default is every hour.
1. Click **Next**.

### (Optional) Configure the loyalty sync

:::note
A loyalty program is required to complete the setup. Even if you do not want to
synchronize loyalty data, you must
[create](/docs/product/loyalty-programs/profile-based/create-pb-programs.md) an empty
profile-based loyalty program in Talon.One and select it on the **Loyalty Sync** page.
:::

1. On the **Loyalty Sync** page, select the profile-based loyalty program you want to
   synchronize with Klaviyo.
1. Click **Add to Loyalty Ledgers**, enter the name of your loyalty ledger in Talon.One
   and the profile properties in Klaviyo where the ledger data should be stored.For
   example, if you only have one main ledger and want to sync the points balance to a
   `loyalty_points` property in Klaviyo, enter the following:

      - **Ledger name**: `(leave empty)`
      - **Balance property**: `loyalty_points`

   If the balance property does not exist in Klaviyo, it will be created on first sync.
1. To sync [loyalty
   tier](/docs/product/loyalty-programs/profile-based/use-loyalty-tiers.md) information,
   select the **Sync Loyalty Tiers** option and map the tier properties. If the tier
   properties do not exist in Klaviyo, they will be created on first sync.
1. If you are using [subledgers](/docs/product/loyalty-programs/use-subledgers.md), repeat
   steps 2 and 3 for each subledger you want to synchronize.
1. Click **Next**.

### (Optional) Configure the audience sync

1. On the **Audience Sync** page, configure which lists and segments are sent from Klaviyo
   to Talon.One. All of them will be created as audiences in Talon.One.
1. On the **Audience Sync Schedule** page, set the schedule for the audience sync. You can
   choose to run a full sync every day or every week, and define the time when the sync
   should run.
   :::note
   - A **full sync** removes all members from the audiences in Talon.One and adds the
     members from Klaviyo again.
   - Optionally, you can also enable **incremental syncs** every hour. An incremental sync
     only adds new members to the audiences in Talon.One, but does not remove any members.
   :::
1. Click **Finish**.

### Verify the sync results

After completing the setup, Talon.One performs an initial profile sync and, if
configured, an initial audience sync.

Verify that the syncs are working as expected:

- **Profile sync**: In your Talon.One Application, check the <Customers className="icon"/> **Customers**
  page to confirm that the customer profiles from Klaviyo have been synced.
- **Audience sync**: On the leftmost menu, click <Audiences className="icon"/> to confirm
  that the lists and segments from Klaviyo have been synced. Until the initial sync is
  complete, the audiences show `0` members.
- **Loyalty data**: For loyalty data, there is no initial sync. Loyalty data is sent to Klaviyo in real
time. To verify the flow:

  1. In Talon.One, [manually add loyalty
     points](/docs/product/loyalty-programs/profile-based/manage-pb-lp-data.md#manually-add-loyalty-points)
     to a customer's profile.
  1. In Klaviyo, open **Audience** > **Profiles** and check for the updated data.

</StepsContainer>

## Next steps

To use the integration effectively, additional configuration steps are required, based on
your specific use case.

Read our tutorials to learn more about integrating Talon.One with Klaviyo:

- [Send birthday coupons via Klaviyo](/docs/dev/technology-partners/klaviyo/send-birthday-coupons-via-klaviyo.md)
- [Send a tier upgrade email via Klaviyo](/docs/dev/technology-partners/klaviyo/send-tier-upgrade-email-via-klaviyo.md)