Klaviyo

Key Features

• Connects Gravity Forms to Klaviyo using the Klaviyo API
• Supports Klaviyo OAuth connection by default
• Supports private API key configuration when enabled with the gform_klaviyo_allow_api_key_configuration filter
• Creates new Klaviyo profiles from form submissions
• Updates existing Klaviyo profiles when a submitted email address already exists in Klaviyo
• Adds profiles to a selected Klaviyo list
• Maps Gravity Forms fields to Klaviyo profile fields
• Supports custom Klaviyo profile properties through custom field mapping
• Create multiple Klaviyo feeds per form
• Use Conditional Logic to control when a submission is sent to Klaviyo
• Supports background feed processing to avoid delaying form submission completion
• Built-in logging support through the Gravity Forms logging system
• Validates Klaviyo credentials before feeds can be created
• Supports disconnecting and revoking OAuth tokens from the settings page

Requirements

• WordPress
• PHP
• Gravity Forms 2.0+
• A Klaviyo account
• A Klaviyo account connection through OAuth, or a Klaviyo Private API Key if custom app configuration is enabled

Installation

1. Install the plugin on your site. If installing manually, upload it to /wp-content/plugins/.
2. Activate the plugin from the WordPress Plugins screen.
3. In WordPress, go to Forms → Settings → Klaviyo to configure your Klaviyo connection.

Setup: Connecting to Klaviyo

The add-on supports Klaviyo OAuth connection by default.

1. Go to Forms → Settings → Klaviyo.
2. Click Connect to Klaviyo.
3. Complete the Klaviyo authorization flow.
4. After authorization, you’ll be returned to the Gravity Forms Klaviyo settings page.
5. Confirm that the settings page shows the account as connected.

The add-on validates the connection by checking access to the Klaviyo account. If the connection is invalid, feed creation will be unavailable until the connection is fixed.

Optional Setup: Private API Key Configuration

Private API key configuration is available only when enabled by the gform_klaviyo_allow_api_key_configuration filter.

When enabled:

1. Go to Forms → Settings → Klaviyo.
2. Enter the Private API Key from your Klaviyo account.
3. Save the settings.

The add-on validates the private API key by attempting to access Klaviyo account data. If the credentials are invalid, feed creation will be unavailable until the connection is fixed.

Using the Add-On: Creating a Feed

Feeds control what happens when a form is submitted, including which Klaviyo list a profile should be added to and which form fields should be sent.

1. Go to Forms → choose a form → Settings → Klaviyo.
2. Click Add New to create a new feed.
3. Configure the feed options:

Feed Name

Enter an internal name to help you identify the feed later.

Klaviyo List

Choose the Klaviyo list that submitted profiles should be added to.

Map Fields

Map Gravity Forms fields to Klaviyo profile fields.

Custom Fields

Optionally map additional Gravity Forms fields to custom Klaviyo profile properties.

Each custom field mapping includes:

• Custom Key — the Klaviyo profile property name
• Value — the Gravity Forms field value to send for that property

Conditional Logic

Optionally enable conditional logic so the feed only runs when specific conditions are met.

4. Save the feed.

You can create multiple feeds per form if you want to send profiles to different Klaviyo lists or apply different logic depending on the submission.

Field Mapping

Required Mapping

The following field is required:

• Email — must be mapped to a Gravity Forms Email field containing a valid email address

Available Mapped Fields

This add-on supports mapping the following Klaviyo profile fields:

• Email
• First Name
• Last Name
• Phone Number

If the submitted email address is missing or invalid, the feed will not process successfully.

Phone Number Handling

When a phone number field is mapped, the add-on attempts to format the value for Klaviyo.

Supported Gravity Forms phone formats include:

• Standard
• International
• Formatted

For standard phone fields, the add-on adds a +1 country code. For international and formatted phone fields, the add-on adds a leading +.

If Klaviyo rejects the phone number during profile creation or update, the add-on retries the request without the phone number and adds an entry note indicating that the profile was processed without it.

Custom Field Mapping

Custom fields are sent to Klaviyo as profile properties.

The add-on supports formatting and validating several Gravity Forms field types before sending them to Klaviyo:

• Multi Select fields are converted to arrays
• Date fields are formatted as YYYY-MM-DD
• Number fields are validated and converted to numeric values
• Phone fields are formatted similarly to the mapped Phone Number field
• Website fields are validated as URLs
• Text and Hidden fields are sanitized as text
• Textarea fields are sanitized as textarea content
• Checkbox, Radio, and Select fields are passed through as choice values

Empty custom field values are skipped.

Conditional Logic

Conditional logic lets you send profiles to Klaviyo only when specific form conditions are met.

Examples include:

• Only add users who checked an “Email me updates” checkbox
• Only send profiles to Klaviyo after a specific product or option is selected
• Route different form submissions through different Klaviyo feeds based on form input
• Add profiles to different Klaviyo lists depending on form responses

When conditional logic is disabled, all qualifying submissions are sent to Klaviyo.

How It Works

When a form submission matches a Klaviyo feed:

1. The add-on reads the configured feed settings.
2. It validates that the Klaviyo API connection is available.
3. It reads the mapped Email field from the form submission.
4. It validates the submitted email address.
5. It builds Klaviyo profile data from the mapped fields.
6. It adds any configured custom properties.
7. It checks Klaviyo for an existing profile with the submitted email address.
8. If the profile already exists, it updates the profile.
9. If the profile does not exist, it creates a new profile.
10. It adds the profile to the selected Klaviyo list.
11. It records entry notes and log entries based on the result.

If the profile is created successfully, the entry receives a note indicating that the profile was added to the Klaviyo list.

If the profile already existed and was updated successfully, the entry receives a note indicating that the profile was updated in the Klaviyo list.

Logging & Troubleshooting

If something doesn’t appear in Klaviyo as expected:

• Enable Gravity Forms logging and review the Klaviyo add-on log for API requests and errors
• Confirm the Klaviyo account is connected
• If using private API key configuration, confirm the Private API Key is correct
• Make sure your feed is active
• Verify the selected Klaviyo list still exists and is accessible through the Klaviyo API
• Check that the Email field mapping points to the correct form field
• Confirm the submitted email address is valid
• Review any Conditional Logic settings to make sure the submission qualifies
• Check whether a phone number was rejected and excluded during retry
• Confirm any custom field mappings use valid custom keys and supported field values

Common failure cases include invalid credentials, missing or invalid email addresses, unavailable Klaviyo lists, invalid phone numbers, invalid custom field values, or Klaviyo API request failures.

Klaviyo API

This add-on uses the Klaviyo API.

Relevant Klaviyo API base URL:

https://a.klaviyo.com/api

The add-on sends requests using the Klaviyo API revision:

2026-01-15

Common Klaviyo API resources used by the add-on include:

• accounts
• lists
• lists/{list_id}
• lists/{list_id}/relationships/profiles
• lists/{list_id}/profiles
• profiles
• profiles/{profile_id}

The add-on can authenticate requests using either:

• OAuth Bearer token
• Klaviyo Private API Key

OAuth token exchange, refresh, and revocation are handled through the Gravity API Klaviyo authentication service.

Relevant Gravity API base URL:

https://gravityapi.com/wp-json/gravityapi/v1/auth/klaviyo

Common Gravity API authentication endpoints used by the add-on include:

• /token
• /refresh
• /revoke

Plugin Structure

Main Plugin File

klaviyo.php — plugin bootstrap file that defines constants, hooks into gform_loaded, loads the main add-on class, and registers the add-on with Gravity Forms.

Main Add-On Class

class-gf-klaviyo.php — contains the GF_Klaviyo class, plugin settings, feed settings, feed processing, Klaviyo list retrieval, OAuth handling, credential validation, custom field preparation, and Klaviyo integration logic.

API Wrapper

includes/api/class-gf-klaviyo-api.php — contains the GF_Klaviyo_API class, which handles authenticated requests to the Klaviyo API, account validation, list operations, profile operations, token refresh, and token revocation.

Admin JavaScript

assets/js/dist/scripts-admin.js and assets/js/dist/scripts-admin.min.js — admin scripts used on the plugin settings and form settings pages.

assets/js/dist/vendor-admin.js and assets/js/dist/vendor-admin.min.js — vendor admin scripts used by the add-on settings UI.

Images

images/klaviyo-icon.svg — fallback Klaviyo icon used in the Gravity Forms settings menu when the newer Gravity Forms icon is unavailable.

Notes

• This is a feed-based Gravity Forms add-on built on GFFeedAddOn
• The plugin uses the singleton pattern for the main add-on class
• The plugin uses the WordPress HTTP API for Klaviyo and Gravity API requests
• Feed creation is gated behind successful Klaviyo API initialization
• Feed processing runs asynchronously in the background
• OAuth is the default connection method
• Private API key configuration is disabled by default and can be enabled with the gform_klaviyo_allow_api_key_configuration filter
• The add-on can duplicate feeds
• The plugin is primarily written in PHP with JavaScript used for the admin settings experience