Klaviyo + TrackLayer server-side event sync guide

Context

Why sync to Klaviyo server-side

Klaviyo is only as useful as the events that arrive in time to trigger flows. If the browser is the only source of truth, the most valuable moments are also the easiest to lose. Ad blockers can block Klaviyo's client-side pixel, privacy extensions can suppress onsite tracking, Safari can shorten browser state, and checkout redirects can detach a cart or order from the original session. The result is not just weaker reporting. It is lost flow triggers, delayed abandon-cart messages, missing browse abandonment entries, and purchase automations that fire late or not at all.

A TrackLayer server-side sync uses backend events as the source of truth. Cart, checkout, purchase, lead, subscription, refund, and product events can move to Klaviyo after your application has confirmed the action. That makes lifecycle automation less dependent on a fragile page script while still giving marketers the Klaviyo metrics and profile properties they already use.

Requirements

Prerequisites

A Klaviyo account with permission to create private API keys, read metrics, inspect profiles, and validate flow triggers.

A Private API key from Klaviyo Account → Settings → API Keys, stored as a server secret and never exposed in browser JavaScript.

The list_id for the main newsletter list used by your Welcome series, consent checks, and subscription reporting.

An event schema mapping decided before implementation, including canonical TrackLayer event names, Klaviyo metric names, required properties, consent rules, and dedup keys.

Build

Step-by-step setup

Step 1

Create the event sender

Send TrackLayer events to Klaviyo from your backend or event worker, not from the browser. The events endpoint accepts metric events that can appear in customer timelines and trigger flows. Use the private key in the Authorization header, include the current Klaviyo API revision used by your account, and log the response body because validation errors are specific enough to fix quickly.

POST https://a.klaviyo.com/api/events
Authorization: Klaviyo-API-Key pk_live_xxxxxxxxx
Content-Type: application/json
revision: 2026-04-15

{
  "data": {
    "type": "event",
    "attributes": {
      "metric": { "data": { "type": "metric", "attributes": { "name": "Added to Cart" } } },
      "profile": { "data": { "type": "profile", "attributes": { "email": "ava@example.com" } } },
      "properties": {
        "event_id": "cart_10492_add_1",
        "source": "tracklayer",
        "currency": "EUR",
        "value": 89.95
      },
      "time": "2026-04-23T10:15:30Z"
    }
  }
}

Step 2

Build the required payload contract

Treat the Klaviyo payload as an explicit contract between TrackLayer and lifecycle marketing. The required shape is data.type set to event, attributes.profile.email, attributes.properties with the business fields your flows need, attributes.metric.name, and attributes.time. Put flow conditions on stable properties, not on incidental labels from the website.

{
  "data": {
    "type": "event",
    "attributes": {
      "profile": {
        "data": {
          "type": "profile",
          "attributes": { "email": "ava@example.com" }
        }
      },
      "metric": {
        "data": {
          "type": "metric",
          "attributes": { "name": "Placed Order" }
        }
      },
      "properties": {
        "event_id": "ord_10492_purchase",
        "order_id": "10492",
        "value": 129.95,
        "currency": "EUR",
        "items": ["SKU-481", "SKU-812"],
        "checkout_url": "https://shop.example/orders/10492"
      },
      "time": "2026-04-23T10:20:00Z"
    }
  }
}

Step 3

Create or update profiles before sending lifecycle events

Klaviyo can resolve profiles during event creation, but many teams create or update the profile first so marketing properties are fresh before flows evaluate. Use POST /api/profiles when TrackLayer receives email, phone, customer ID, locale, country, predicted preference, or acquisition source. Keep this profile update small and deterministic.

POST https://a.klaviyo.com/api/profiles
Authorization: Klaviyo-API-Key pk_live_xxxxxxxxx
Content-Type: application/json
revision: 2026-04-15

{
  "data": {
    "type": "profile",
    "attributes": {
      "email": "ava@example.com",
      "phone_number": "+4915112345678",
      "external_id": "cust_34982",
      "properties": {
        "tracklayer_customer_id": "cust_34982",
        "last_source": "paid_social",
        "preferred_category": "skincare"
      }
    }
  }
}

Step 4

Subscribe the profile to the newsletter list

Metric events and list subscriptions are different jobs. A sign_up event can trigger analytics and segmentation, but the newsletter list relationship is what places a profile into your main list. Use POST /api/list-relationships with the list_id you selected in the prerequisites, and only run this route when your consent policy permits subscription.

POST https://a.klaviyo.com/api/list-relationships
Authorization: Klaviyo-API-Key pk_live_xxxxxxxxx
Content-Type: application/json
revision: 2026-04-15

{
  "data": {
    "type": "list-relationship",
    "attributes": {
      "list_id": "Y6nRLr",
      "profile": {
        "email": "ava@example.com",
        "external_id": "cust_34982"
      },
      "consented_at": "2026-04-23T10:18:00Z",
      "source": "tracklayer_signup"
    }
  }
}

Step 5

Back-fill migrations with bulk jobs

When migrating from another customer data pipeline, do not replay months of historical events through the live single-event endpoint. Use /api/events-bulk-create-jobs for controlled batches, preserve original timestamps, and tag migrated events with a property such as migration_id so marketers can exclude them from live flows if needed.

POST https://a.klaviyo.com/api/events-bulk-create-jobs
Authorization: Klaviyo-API-Key pk_live_xxxxxxxxx
Content-Type: application/json
revision: 2026-04-15

{
  "data": {
    "type": "events-bulk-create-job",
    "attributes": {
      "events": [
        {
          "type": "event",
          "attributes": {
            "metric": { "name": "Placed Order" },
            "profile": { "email": "ava@example.com" },
            "properties": {
              "event_id": "legacy_ord_7781",
              "order_id": "7781",
              "value": 74.50,
              "currency": "EUR",
              "migration_id": "spring_2026_import"
            },
            "time": "2025-11-20T13:12:00Z"
          }
        }
      ]
    }
  }
}

Schema

Event mapping

Klaviyo metrics should read like marketing actions, while TrackLayer events should remain canonical and destination-neutral. Keep the mapping table in code or configuration, and version it when marketers add new flow branches. The right-hand properties are examples of the fields that usually become Klaviyo flow filters, email personalization tokens, and segment criteria.

TrackLayer canonical event	Klaviyo metric name	Typical properties
purchase	Placed Order	order_id, value, currency, items, discount_code, shipping_country
add_to_cart	Added to Cart	cart_id, product_id, sku, product_name, value, checkout_url
sign_up	Subscribed to List	list_id, source, consented_at, signup_form, campaign
view_content	Viewed Product	product_id, sku, product_name, category, price, product_url
begin_checkout	Started Checkout	checkout_id, checkout_url, value, currency, item_count
search	Searched Site	query, result_count, category, source_page
lead	Submitted Lead Form	form_id, source, interest, consent_state, landing_page
refund	Refunded Order	order_id, refund_value, currency, reason, items

Deduplication

Dedup with Klaviyo native web tracking

Some teams keep Klaviyo's client-side tracker for onsite behavior while TrackLayer sends backend-confirmed events. That is a valid setup, but only if both paths agree on which events they own. Let the browser tracker keep low-risk browsing events if you need immediate onsite personalization, then let TrackLayer own checkout, purchase, subscription, refund, and lead events. If both paths can emit the same action, include the same event_id property and build flow filters that ignore duplicate source combinations.

The practical rule is simple: one user action gets one business event. A button click can create a browser hint, but the cart service should create the authoritative Added to Cart event. A thank-you page can render fast, but the order service should create the authoritative Placed Order event. Keep source set to tracklayer on server events so Metric Activity makes the path visible during debugging.

{
  "metric": "Placed Order",
  "profile_email": "ava@example.com",
  "properties": {
    "event_id": "ord_10492_purchase",
    "source": "tracklayer",
    "dedup_scope": "order",
    "order_id": "10492"
  }
}

Automation

Flow triggers

Server-side Klaviyo metrics are most valuable when they unlock automations that depend on reliable timing. Abandon cart should start when the backend knows the cart exists and the checkout URL is recoverable. Welcome series should start only after the profile is subscribed to the intended list. Post-purchase flows should use completed order truth, not a page view that may fire before the payment provider confirms the order.