How can we help you?

This official documentation guide walks you through connecting your WordPress forms directly to Klaviyo using the Gravity Forms Klaviyo Integration Premium Addon. Follow this step-by-step tutorial to authenticate your private API key, create automated feeds, map custom profile properties, collect GDPR/TCPA marketing consent, and trigger automated welcome flows with zero ongoing middleware fees.

Step 1: Generate your Klaviyo Private API Key

The integration connects directly from your WordPress server to Klaviyo’s REST API. To establish this secure connection, you need to generate a dedicated Private API Key inside your Klaviyo dashboard:

1. Navigate to Account Settings: Log in to your Klaviyo dashboard. Click your organization name or avatar in the bottom-left corner and select Settings (or Account → Settings).
   
2. Open API Keys Management: From the settings menu, click on API Keys in the secondary navigation bar.
   
3. Create Private API Key: Click the blue Create Private API Key button in the top right corner.
   
4. Set Key Name & Permission Scopes: Enter a recognizable name (e.g. Gravity Forms Integration). Under Access Level, select Full Access Key (or ensure Custom Key has write permissions for Lists, Profiles, and Events).
   
5. Copy API Key: Copy the generated private key string (beginning with pk_). Keep this string secure, as Klaviyo will mask it once you leave this page.

Step 2: Authenticate in Gravity Forms Settings

Now that you have your private API key, connect your WordPress site to Klaviyo:

1. In your WordPress admin dashboard, navigate to Forms → Settings and click the Klaviyo tab.
2. Paste your private API key into the Klaviyo Private API Key input field.
3. Click Save Settings. A green checkmark icon will appear next to the field confirming that the API key authenticated successfully.

Step 3: Create an Integration Feed

An integration feed tells Gravity Forms which form submissions to send to Klaviyo, which target list to populate, and how each form input maps to Klaviyo profile attributes:

1. Navigate to Forms → Forms and click Edit on the form you want to connect.
2. In the top bar, go to Settings → Klaviyo and click Add New to create a feed.
3. Enter a descriptive Feed Name (e.g. Newsletter Opt-in Feed).
4. Under Klaviyo List, select your desired destination list from the dynamic dropdown populated directly from your Klaviyo workspace.

Step 4: Map Standard Fields & Custom Profile Properties

The field mapping section allows you to pass both standard contact fields and unlimited custom profile properties directly into Klaviyo:

Step 4B: Map Dynamic Event Properties for Klaviyo Flows

Starting in version 1.8.15, you can pass rich, dynamic submission metadata directly into Klaviyo Track Events using the new Event Properties mapping table. This allows your Klaviyo email & SMS automations (Welcome Series, Follow-up Flows, Lead Nurture) to trigger and branch based on submission details:

Step 5: Configure Email & SMS Marketing Consent (GDPR & TCPA)

Capturing marketing consent properly is essential for global privacy compliance and ensuring your leads can receive marketing messages without deliverability penalties:

1. SMS Consent Mapping & E.164 Phone Formatting

To enroll contacts into Klaviyo SMS campaigns, select your opt-in checkbox field in the SMS Consent feed dropdown:

2. Email Consent Mapping & List Opt-in Settings

Similarly, map your email marketing subscription checkbox to the Email Consent feed field:

Inside your Klaviyo dashboard, verify your destination list settings under Lists & Segments → [Your List] → Settings. If you want subscribers to immediately receive emails upon form submission without waiting for a confirmation email, ensure the list is set to Single opt-in:

Step 6: Conditional Logic Configuration

You can control exactly when form entries are sent to Klaviyo using Gravity Forms native conditional logic. For example, only execute the Klaviyo feed if:

• The checkbox “Sign up for our monthly marketing newsletter” is checked.
• The dropdown “Lead Type” is equal to “Enterprise Prospect”.
• The calculated order total is greater than $0.

Check Enable Condition at the bottom of your feed settings, define your rules, and click Save Settings.

Step 7: Monitoring Submissions & One-Click Resync

Starting in version 1.8.15, administrators can monitor delivery status and diagnose API failures directly inside Gravity Forms:

Developer Reference: Custom Hooks & Filters

For developers who need to customize how the add-on recognizes consent values from checkboxes or radio buttons, use the klaviyoaddon_consent_value_default filter hook:

// Customize accepted positive consent values for email and SMS
add_filter('klaviyoaddon_consent_value_default', 'custom_ge_klaviyo_consent_values');

function custom_ge_klaviyo_consent_values($default_values) {
    // By default: array('true', 'True', 'Yes', 'yes', 'Checked', 'checked', 'Selected', 'selected', 1)
    $custom_values = array('true', 'True', 'Yes', 'yes', 'Checked', 'checked', 'I agree', 'Opt-in');
    
    return $custom_values;
}

Custom Country Calling Codes Filter (v1.8.15+)

If your business operates in territories not covered by the default calling code directory, you can customize or extend supported country codes using the gravityextra_klaviyo_country_calling_codes filter hook:

// Add or override custom country calling codes for E.164 normalization
add_filter('gravityextra_klaviyo_country_calling_codes', function($calling_codes) {
    $calling_codes['IS'] = '+354'; // Iceland
    $calling_codes['MT'] = '+356'; // Malta
    return $calling_codes;
});

Troubleshooting & Frequently Asked Questions (FAQ)

1. Why are newly synced subscribers showing “Never Subscribed” in Klaviyo?

In Klaviyo, creating a contact profile is separate from granting marketing consent. If you map fields to a list but do not map an opt-in checkbox to the Email Consent field, Klaviyo creates the profile record with status Never Subscribed to comply with privacy laws. Ensure you map a consent field in your feed settings, or set your Klaviyo list to Single Opt-in.

2. Why are phone numbers not syncing or failing SMS verification?

Klaviyo enforces strict E.164 formatting (e.g. +14155552671). Local phone numbers like (415) 555-2671 without an international country prefix will fail SMS validation. Use an international phone mask field on your form to ensure valid submissions.

3. Why are my feed settings or dropdowns failing to load?

If third-party plugins conflict with Gravity Forms AJAX scripts, disable Gravity Forms “No Conflict Mode” by navigating to Forms → Settings → General and toggling No-Conflict Mode to Off.

4. Can I create multiple feeds for the same form?

Yes! You can create multiple Klaviyo feeds on a single Gravity Form. Each feed can target a completely different Klaviyo list and apply distinct conditional logic rules (e.g. sending B2B leads to a Wholesale list and consumers to a General Newsletter list).

Related Resources & Tutorials