Klaviyo Integration

Documentation Index

Fetch the complete documentation index at: https://docs.fanfare.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Import Klaviyo lists as Fanfare audiences
• Automatically sync consumer profiles between platforms
• Target specific customer segments in your experiences
• Trigger email campaigns based on experience participation

​

Prerequisites

• A Klaviyo account with at least one list
• A Klaviyo Private API Key with the following permissions:
  • Lists: Read
  • Profiles: Read
  • Profiles: Write (if using bidirectional sync)

​

Setup

​

Step 1: Get Your Klaviyo API Key

1. Log in to your Klaviyo account
2. Navigate to Account > Settings > API Keys
3. Click Create Private API Key
4. Give it a descriptive name (e.g., “Fanfare Integration”)
5. Select the required scopes:
   • Lists: Read
   • Profiles: Read
6. Copy the generated API key (starts with pk_)

​

Step 2: Configure Klaviyo in Fanfare

1. Navigate to Settings > Integrations in the Fanfare admin
2. Find Klaviyo and click to configure
3. Paste your Klaviyo API key
4. Click Save

​

Step 3: Verify Connection

​

Data Sync

​

How Sync Works

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│   Klaviyo       │       │   Fanfare       │       │   Fanfare       │
│   List          │──────▶│   Sync Source   │──────▶│   Audience      │
└─────────────────┘       └─────────────────┘       └─────────────────┘
        │                         │
        │                         │
        ▼                         ▼
    Profiles                  Consumers

​

Sync Source Types

​

Importing a Klaviyo List

1. Go to Audiences in the Fanfare admin
2. Click Import from Klaviyo
3. Select the list(s) you want to import
4. Click Import Selected

1. Create a sync source for the list
2. Create a new audience with the list name
3. Queue a background job to sync all profiles
4. Create or update consumer records for each profile

​

Sync Status

​

Automatic Resync

​

Consumer Mapping

​

Profile to Consumer Mapping

​

Deduplication

• If a consumer with the same email exists, the existing record is updated
• The Klaviyo profile is linked via primarySyncSourceId
• New consumers are created for profiles without a matching email

​

Audience Membership

-- Example audience membership
INSERT INTO audience_list_memberships (
  organization_id,
  audience_id,
  consumer_id
) VALUES (
  'org-123',
  'aud-456',  -- The synced audience
  'con-789'   -- The imported consumer
);

​

API Reference

​

Get Klaviyo Lists

GET /api/klaviyo

[
  {
    "id": "RtPqXs",
    "attributes": {
      "name": "Newsletter Subscribers",
      "created": "2024-01-15T10:30:00Z",
      "updated": "2024-06-20T14:45:00Z",
      "optInProcess": "single_opt_in"
    },
    "isSynced": true,
    "syncStatus": "SUCCESS",
    "audienceId": "aud_abc123",
    "lastSyncedAt": "2024-06-20T15:00:00Z"
  },
  {
    "id": "XyZaBc",
    "attributes": {
      "name": "VIP Customers",
      "created": "2024-03-01T09:00:00Z",
      "updated": "2024-06-18T11:20:00Z",
      "optInProcess": "double_opt_in"
    },
    "isSynced": false,
    "syncStatus": null,
    "audienceId": null,
    "lastSyncedAt": null
  }
]

​

Configure Klaviyo Settings

PUT /api/settings
Content-Type: application/json

{
  "klaviyo": {
    "apiKey": "pk_your_api_key_here"
  }
}

​

Best Practices

​

API Key Management

• Use a dedicated API key for the Fanfare integration
• Only grant the minimum required scopes
• Rotate the API key periodically
• Revoke the key immediately if compromised

​

List Management

• Keep list names consistent between Klaviyo and Fanfare
• Avoid importing very large lists (>100k profiles) in a single sync
• Monitor sync status for failed imports

​

Performance

• The sync processes profiles at ~75 per second (Klaviyo rate limit)
• Large lists may take several minutes to fully sync
• Syncs run in the background and don’t block the UI

​

Troubleshooting

​

Common Issues

• Verify the key starts with pk_
• Check the key hasn’t been revoked in Klaviyo
• Re-enter the key in Settings > Integrations

• Check event processor logs for errors
• Verify the Klaviyo sync queue is operational
• Contact support if the issue persists

• Verify profiles have valid email addresses in Klaviyo
• Check for duplicate email handling
• Review sync source logs for errors

• Check for existing audiences with the same name
• Verify organization permissions
• Review the sync source status

​

Checking Sync Status

GET /api/sync-sources/search?syncSource=klaviyo:list

​

Logs

• Handler: klaviyo.handler
• Processor: klaviyo/sync-list
• Log Fields: organizationId, syncSourceId, profileId

​

Limitations

​

Future Enhancements

​

Related Resources

• Audiences Overview
• Sync Sources
• Klaviyo API Documentation