How to Setup ConvertKit with a WordPress Form

Integrate ConvertKit and WPForms easily connects forms on your website to your ConvertKit email marketing account, enabling you to capture more leads and manage campaigns more effectively.

WPForms‘ simple drag-and-drop form builder allows you to create new forms with ease and its clean, modern code makes customizations a snap. This integration also works with the free version, WPForms Lite, but I highly recommend purchasing the full WPForms for the valuable premium features and support.

Please support the development of this free plugin by using the affiliate links above. I’ve also included a developer’s tutorial at the bottom of this post for those who want to build their own WPForms integrations.

Using the Plugin

  1. Install WPForms (or WPForms Lite) and Integrate ConvertKit and WPForms.
  2. In the WordPress Dashboard, go to WPForms > Add New and create a form. You can add whatever fields you like, but at a minimum you must include a Name and Email field.
  3. Click “Settings” in the left column, then select “ConvertKit”. From the two dropdowns, select the Name and Email fields you created.
  4. In a separate browser tab, go to ConvertKit, log in, and click Account. Copy the API Key, go back to the WPForms ConvertKit settings page, and paste it in the field titled “ConvertKit API Key”.
  5. Back on the ConvertKit site, click “Forms” then select the form you want to use (or create a new one). When editing the form, look at the URL. It should be something like https://app.convertkit.com/landing_pages/12345/edit. The number after “landing_pages/” and before “/edit”  is your Form ID. Copy this number, go back to WPForms ConvertKit settings page, and paste it in the field titled “Form ID”.
  6. Click “Save” in the top right corner, and exit out of the form builder.
  7. Insert the form somewhere on your site and test it out! Go to Pages, select a page, and above the content editor click “Add Form”. Select your form and click “Insert” to add it to the page.

Building the Plugin

If you’re a developer and haven’t purchased WPForms yet, I strongly recommend it. Within the next few months, the Ultimate plan – a lifetime license for early adopters – will be discontinued.

There are two components to building an integration like this: adding a backend settings panel, and processing the form once it’s been submitted.

In the plugin I’m using a class to organize the code, but the examples below use procedural functions so it’s easier to read. Either approach will work, and the code can go in your theme’s functions.php file, a Core Functionality plugin, or your own custom plugin. Any time you see __( 'Some Text', 'integrate_convertkit_wpforms' ) that’s making “Some Text” translatable.

1. Backend Settings Panel

We will first use the wpforms_builder_settings_sections filter to add a section to the settings panel. It’s a simple array with a unique slug and label.

<?php
/**
* Add Settings Section
*
*/
function be_wpforms_settings_section( $sections, $form_data ) {
$sections['be_convertkit'] = __( 'ConvertKit', 'integrate_convertkit_wpforms' );
return $sections;
}
add_filter( 'wpforms_builder_settings_sections', 'be_wpforms_settings_section', 20, 2 );
view raw functions.php hosted with ❤ by GitHub

Then we use the wpforms_form_settings_panel_content filter to specify what content appears in that section.

<?php
/**
* ConvertKit Settings Content
*
*/
function be_wpforms_settings_section_content( $instance ) {
echo '<div class="wpforms-panel-content-section wpforms-panel-content-section-be_convertkit">';
echo '<div class="wpforms-panel-content-section-title">' . __( 'ConvertKit', 'be_wpforms_convertkit' ) . '</div>';
wpforms_panel_field(
'text',
'settings',
'be_convertkit_api',
$instance->form_data,
__( 'ConvertKit API Key', 'be_wpforms_convertkit' )
);
wpforms_panel_field(
'text',
'settings',
'be_convertkit_form_id',
$instance->form_data,
__( 'ConvertKit Form ID', 'be_wpforms_convertkit' )
);
wpforms_panel_field(
'select',
'settings',
'be_convertkit_field_first_name',
$instance->form_data,
__( 'First Name', 'be_wpforms_convertkit' ),
array(
'field_map' => array( 'text', 'name' ),
'placeholder' => __( '-- Select Field --', 'be_wpforms_convertkit' ),
)
);
wpforms_panel_field(
'select',
'settings',
'be_convertkit_field_email',
$instance->form_data,
__( 'Email Address', 'be_wpforms_convertkit' ),
array(
'field_map' => array( 'email' ),
'placeholder' => __( '-- Select Field --', 'be_wpforms_convertkit' ),
)
);
echo '</div>';
}
add_filter( 'wpforms_form_settings_panel_content', 'be_wpforms_settings_section_content', 20 );
view raw functions.php hosted with ❤ by GitHub

You’ll output a div with a class of “wpforms-panel-content-section wpforms-panel-content-section-{your slug}”, where {your_slug} is whatever you used array above.

wpforms_panel_field() is a helper function for adding fields to the section – WPForms will do all the work sanitizing and storing the data. Here are the parameters of the function: wpforms_panel_field( $option, $panel, $field, $form_data, $label, $args, $echo )

  • Option: What type of field it is (ex: text, select…). Look in wpforms/includes/admin/builder/functions.php for a list of all available options
  • Panel: What panel it is in. These are all in a section of the Settings panel so we’re setting them all to ‘settings’
  • Field: The field ID you’ll use to save/access this data.
  • Form Data: Pass all the form data, which has important information for building out the fields. Use $instance->form_data, which is provided by the filter we’re using.
  • Label: The label you want associated with this field.
  • Args: Any additional arguments you want to pass. For instance, 'field_map' => array( 'email' ) on a “select” field type will pre-populate the dropdown with every email field in the form
  • Echo: defaults to true

We’re adding 4 fields: ConvertKit API Key (text field), Form ID (text field), First Name Field (select dropdown pre-populated with form fields) and Email Field (select dropdown pre-populated with form fields).

2. Processing the Form

The wpforms_process_complete hook runs after a form entry has successfully been processed. We run our code at the end because there are reasons a form submission might not reach the complete hook (required fields weren’t filled out, message was determined to be spam…). This hook runs on ANY form completion. If you wanted to restrict it to a specific form you should instead use the wpforms_process_complete_{$form_id} hook.

I used the ConvertKit API documentation to create this code. If you’re building a separate integration, you’ll need to find the API docs to guide your development as APIs are all different.

I first check to see if the API Key and Form ID are defined for this form. We’ll usually have many forms on a site and only a few of them connecting to ConvertKit, and each form that does connect might be linked to a different ConvertKit form.

Next I get the First Name and Email field IDs that were selected in the settings panel. I use these IDs to pull the field value from $fields which has the values the user submitted. I prepare the arguments into an array, add the arguments to the API url using add_query_arg(), then use wp_remote_post() to submit this via POST. We’re setting a variable ( $request ) equal to this so that we can see the response from the API. I’ve left three lines commented out at the bottom, which you can use to see the server response. The “exit” is there to end the process because if the form is set to redirect to another URL you won’t have time to see the response.

<?php
/**
* Integrate WPForms with ConvertKit
*
*/
function be_wpforms_send_data_to_convertkit( $fields, $entry, $form_data, $entry_id ) {
// Get API key and CK Form ID
$api_key = $ck_form_id = false;
if( !empty( $form_data['settings']['be_convertkit_api'] ) )
$api_key = esc_html( $form_data['settings']['be_convertkit_api'] );
if( !empty( $form_data['settings']['be_convertkit_form_id'] ) )
$ck_form_id = intval( $form_data['settings']['be_convertkit_form_id'] );
if( ! ( $api_key && $ck_form_id ) )
return;
// Get email and first name
$email_field_id = $form_data['settings']['be_convertkit_field_email'];
$first_name_field_id = $form_data['settings']['be_convertkit_field_first_name'];
$args = array(
'api_key' => $api_key,
'email' => $fields[$email_field_id]['value'],
'first_name' => $fields[$first_name_field_id]['value']
);
if( empty( $args['email'] ) || empty( $args['first_name'] ) )
return;
// Submit to ConvertKit
$request = wp_remote_post( add_query_arg( $args, 'https://api.convertkit.com/v3/forms/' . $ck_form_id . '/subscribe' ) );
// $response = json_decode( wp_remote_retrieve_body( $request ) );
// print_r( $response );
// exit;
}
add_action( 'wpforms_process_complete', 'be_wpforms_send_data_to_convertkit', 10, 4 );
view raw functions.php hosted with ❤ by GitHub

For more information on building integrations with WPForms, I recommend you read my earlier post, Integrating your contact form with external services, and my collection of WPForms code snippets.

email-marketing form plugin wpforms

Receive New Posts by Email

Comments

  1. Hey Bill thanks for the post and the best part about this is you have made it very easy for us to understand it Thanks.

Leave a comment