Klaviyo Integration

3 min readUpdated June 21, 2026

Klaviyo is an email and SMS marketing platform popular with ecommerce brands. WP Smart Consent integrates with Klaviyo via the Marketing API, subscribing opted-in contacts to one or more lists in real time using Klaviyo’s profile subscription bulk create endpoint.

Enabling the Integration#

In the WP Smart Consent dashboard, go to CRMs & ESPs, find the Klaviyo card, open the Connection tab, and paste in your private API key. Toggle the integration on and save. WP Smart Consent connects to your Klaviyo account and populates the list picker with your available lists.

To generate a private API key, log into Klaviyo and go to Account → Settings → API Keys. Create a new private key with at minimum the Profiles: Write and Lists: Write scopes.

Screenshot of a Klaviyo integration settings page. The integration is marked "Inactive." There are tabs for Connection, Field mapping, Custom fields, and Options. The "Enabled" toggle is off, and there’s a field to paste an API key. A green "Save Klaviyo" button is at the bottom.

Custom Fields#

Klaviyo profile attributes beyond the standard fields are sent as additional keys directly inside the profile attributes object. In the Custom fields tab, add a row, select the WPSC source field on the left, and enter the Klaviyo profile attribute name on the right — for example phone_number, location.city, or any custom property you have defined in Klaviyo. These are merged directly into the profile attributes on the subscription call.

Field Mapping#

The Field mapping tab maps WPSC fields to Klaviyo’s standard profile attribute names. Klaviyo’s native profile fields include email, first_name, last_name, phone_number, organization, location (an object), and any custom properties. First name and last name are sent as first_name and last_name at the top level of the profile attributes object.

How It Works#

WP Smart Consent sends a POST to https://a.klaviyo.com/api/profile-subscription-bulk-create-jobs for each selected list. The API uses JSON:API format with Content-Type: application/vnd.api+json. Each call includes a revision header pinned to a stable API date version (2024-10-15) so the integration is not affected by Klaviyo shipping breaking changes to newer revisions.

The subscription payload sets consent: SUBSCRIBED on the email marketing channel, which subscribes the contact with explicit consent recorded in Klaviyo.

If tags are configured, a separate two-step call is made after the subscription: first a GET /profiles filtered by email to retrieve the Klaviyo profile ID, then a PATCH /profiles/{id} that merges the new tags into the existing properties.tags array without removing any existing tags.

Lists Tab#

The Lists tab is where you select which Klaviyo lists opted-in contacts are subscribed to. The list is populated automatically from your Klaviyo account after the API key is saved. One subscription call is made per list.

Options#

The Options tab has three settings.

Update existing contacts — controls whether an existing Klaviyo profile matched by email has their attributes updated on each opt-in.

Send on unchecked — when enabled, contacts are forwarded to Klaviyo even when the opt-in checkbox was not ticked.

Tags — a comma-separated list of tag strings to apply to every contact. Tags are stored as properties.tags on the Klaviyo profile. Existing tags are preserved and the new ones are merged in.

Klaviyo integration options screen showing “Update existing contacts” toggled on, “Send on unchecked” off, a field for tags with examples, and a green “Save Klaviyo” button at the bottom right. Status is marked “Inactive.”.

Troubleshooting#

List not populating — confirm the private API key is correct and has the Lists: Read scope. The list is fetched from GET /api/lists after save. A wrong key or missing scope returns a 401 or 403.

Contact not appearing in list — Klaviyo’s bulk create endpoint returns a 202 Accepted and processes asynchronously. The contact may take a few seconds to appear. Check the WPSC Logs tab to confirm the opt-in event fired and the API call returned 202.

Custom property values not saving — confirm the destination key matches the exact Klaviyo profile attribute name. Custom properties are case-sensitive. If using nested location fields like location.city, confirm Klaviyo accepts dotted-path notation for your account’s API revision.

Tags not applying — tags require a successful subscription first since the tag update is a follow-up call using the profile ID returned from the subscriber lookup. If the subscription call fails, the tag call is skipped.