Klaviyo

Email and SMS marketing platform with deep ecommerce integration, behavioural segmentation, and automated flows.

⚠️

This integration is currently in alpha. Configuration and behaviour may change.

Prerequisites

Complete these steps in Klaviyo before configuring Signal.

Access your Klaviyo account

Log in to the Klaviyo dashboard at klaviyo.com. If you do not have an account, sign up for a Klaviyo plan that includes API access.

Find your Public API Key (Site ID)

Navigate to Account > Settings > API Keys. Your Public API Key (also called Company ID or Site ID) is a 6-character alphanumeric string displayed at the top of the page. Copy it.

Create a Private API Key

On the same API Keys page, click Create Private API Key. Configure:

Give it a name (e.g. “Datafly Signal”).
Select the Custom Key scope and grant at minimum:
- Profiles: Read, Write
- Events: Write
- Lists: Read, Write (if you plan to sync subscribers)
Click Create.
Copy the Private API Key immediately — it will not be shown again.

⚠️

Use a Private API Key (server-side), not the Public API Key, for event tracking. Public keys are designed for browser use and lack the necessary write scopes.

Configuration

Field	Type	Required	Description
`public_api_key`	string	Yes	Your Klaviyo public API key (6-char Site ID). Found in Account > Settings > API Keys.
`private_api_key`	secret	Yes	A Klaviyo private API key with `events:write` and `profiles:write` scopes.

Signal Setup

Quick Setup

Navigate to Integrations in the sidebar.
Open the Integration Library tab.
Find Klaviyo under the Marketing Automation category.
Click Install, and fill in the required fields with the credentials gathered above.
Click Install Integration to create the integration with a ready-to-use default configuration.

API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/klaviyo/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Klaviyo",
    "variant": "default",
    "config": {
      "public_api_key": "ABC123",
      "private_api_key": "pk_xxxxxxxxxxxxxxxxxxxx"
    },
    "delivery_mode": "server_side"
  }'

Event Mapping

The default Klaviyo blueprint maps:

Datafly Event	Klaviyo Event	Notes
`page`	`page_view`	URL and page title forwarded as event properties.
`Product Viewed`	`product_viewed`	Product ID, name, and price.
`Order Completed`	`purchase`	Order ID, revenue, and currency — used for revenue attribution.
Custom events	Dropped by default	Enable the event in the blueprint editor to forward.

All events are sent to POST https://a.klaviyo.com/api/events/ with Authorization: Klaviyo-API-Key {private_api_key} and revision: 2024-10-15.

Identity

Klaviyo identifies profiles primarily by email, and supports phone and an external ID as additional match keys.

Field	Source	Notes
`email`	`traits.email`	Klaviyo’s primary profile key.
`phone_number`	`traits.phone`	E.164 format. Used for SMS subscribers and as a secondary match key.
`external_id`	`user_id` from `datafly.identify()`	Your stable customer ID. Useful for unifying Klaviyo with your own backend.
`anonymous_id`	Datafly anonymous identifier	Browser-scoped identifier so pre-login activity stitches when the user identifies.

Call datafly.identify() whenever a user logs in or submits a form:

datafly.identify("user-123", {
  email: "jane@example.com",
  phone: "+447700900123"
});

Klaviyo events should be sent under the marketing consent category. Klaviyo also manages its own subscription consent records per channel (email, SMS) — Signal forwards the visitor’s CMP consent state on every event so flows can suppress messaging where appropriate.

Verify it’s working

After installing the integration, trigger a test event from your website or via the Signal event API.
In Klaviyo, navigate to Audience > Profiles and search for the test user by email to verify the profile was created.
Click into the profile and check the Activity Feed for the events Signal delivered.
In Signal, check Live Events to confirm delivery with a 202 response status (Klaviyo returns 202 Accepted on success).

Troubleshooting

Symptom	Possible Cause	Resolution
`401 Unauthorized`	Invalid private API key or missing scopes	Verify the private key in Klaviyo Account > Settings > API Keys. Ensure `events:write` and `profiles:write` scopes are granted.
`400 Bad Request`	Missing profile identifier	Klaviyo requires at least one of `email`, `phone_number`, or `external_id` on every event.
Events not appearing on profile	Profile lookup mismatch	Klaviyo creates a new profile if the identifier doesn’t match an existing one. Confirm the email/phone matches the existing profile exactly.
`429 Too Many Requests`	Rate limit exceeded	Klaviyo applies per-endpoint rate limits. Signal retries on 429 automatically; if persistent, contact Klaviyo support.

Visit Klaviyo API documentation for full reference and event tracking details.