Skip to main content
liftstack
Sign In Start Free Trial

Klaviyo

Prerequisites

  • A Klaviyo account with API key access
  • A private API key with full read/write scope (Klaviyo > Settings > API Keys > Create Private API Key)

liftstack needs permission to read segments and lists, read and write profile properties, create and update templates, and read engagement events. Your private API key must have full read/write scope to support all of these operations.

Connecting Klaviyo

  1. In liftstack, go to Settings > Integrations.
  2. Click Connect Platform.
  3. Select the Klaviyo tab.
  4. Fill in:
    • Connection name: a friendly label (e.g. “Production Klaviyo” or “Staging”). This helps you tell connections apart if you have more than one.
    • Private API key: your Klaviyo private API key. This is masked as you type.
  5. Click Save.

liftstack will store your credentials securely and redirect you to the connections list. You should see your new connection with an “Active” badge.

Event tracking

Klaviyo’s event tracking works via automatic polling, so there is no webhook to set up. liftstack will start pulling engagement data as soon as your first campaign begins tracking.

How it works

liftstack reads profiles from your Klaviyo lists or segments, assigns variants, and writes a custom property (lf_assignments) to each profile so your template knows which content to show each person. liftstack then generates a conditional template in Liquid (Klaviyo uses a Django/Liquid hybrid syntax) that renders the right variant per recipient automatically. You do not need to write any template code yourself.

All API calls happen during the campaign wizard steps, not at send time. When you hit send in Klaviyo, the email renders using the pre-written profile property. There is zero additional latency at send time.

Testing your connection

After creating a connection, you can verify it works:

  1. Go to Settings > Integrations.
  2. Find your connection in the list.
  3. Click the Test button on the connection card.

liftstack will make a test API call to Klaviyo. If successful, a green “Connected” badge appears. If something is wrong, you will see an error message explaining the issue (e.g. “Invalid API key”, “Unauthorized”).

Testing is non-destructive: it only verifies that your credentials are valid and have the necessary permissions. It does not create, modify, or delete anything on your platform.

Rate limits and timing

liftstack includes built-in rate limiting that respects Klaviyo’s published API limits. You do not need to configure anything.

For the property writeback step, liftstack uses Klaviyo’s bulk profile import endpoint (up to 10,000 profiles per batch). For a large audience of 500,000 profiles, expect the writeback to take 10 to 20 minutes. For smaller audiences (under 50,000), the writeback typically completes in under 5 minutes.

If Klaviyo returns a rate limit response (HTTP 429), liftstack reads the Retry-After header and waits before continuing. The writeback simply takes longer rather than failing.

Security

Your Klaviyo credentials are never stored in plain text. All credentials are encrypted at rest using Fernet symmetric encryption with per-workspace derived keys. All API calls between liftstack and Klaviyo use HTTPS/TLS. Only workspace Owners and Admins can view, edit, or create integrations. Members can use integrations (e.g. selecting a connection when creating a campaign) but cannot view or modify credentials.

Troubleshooting

”Connection test failed” or “Invalid API key”

  • Double-check that you copied the full API key with no extra spaces.
  • Verify the key has full read/write scope.
  • Some platforms invalidate old API keys when you generate new ones. Make sure the key you entered is the current active key.

Events are not appearing

Klaviyo events are polled automatically. There can be a short delay (up to a few minutes) between an event occurring and it appearing in liftstack. Check the Events page for the connection to see if events are arriving. If you see events arriving but they are the wrong type, use Configure Event Types to adjust which events are processed.

Audience sync is slow or timing out

For very large segments (500,000+), the sync can take 15 to 30 minutes. This is normal. If the sync fails, check that your API key has permission to read segments and profiles.

Profile writeback shows failures

The campaign wizard shows how many profiles succeeded and how many failed during writeback. Failures are typically caused by temporary API errors. You can re-trigger the writeback step from the campaign wizard. The operation is idempotent (writing the same property value twice is harmless), so it safely re-processes all profiles from the beginning. If failures persist, check Klaviyo’s API status page for outages or degraded performance.