Rahul Sharma

Posted on Sep 18

CF7 to ConvertKit (Kit) Not Tagging Subscribers - Four Causes Explained

#wordpress #convertkit #emailmarketing #webdev

ConvertKit rebranded to Kit in 2024 and migrated their API from v3 to v4. They also changed from API Key + Secret authentication to OAuth 2.0. These changes, combined with the longstanding confusion between tag names and tag IDs, explain almost every CF7 to ConvertKit/Kit integration failure.

This post covers each cause with the exact technical detail needed to fix it.

Cause 1: API Key vs Secret Key Confusion

A WordPress forum user reported that their plugin showed the ConvertKit connection as validated but no forms were visible in the mapping screen. After back and forth, the resolution was simple: the client had given them the API key instead of the API secret.

ConvertKit's legacy v3 API used two separate credentials:

API Key: Used for some read operations
API Secret: Required for subscriber creation and tagging

Most CF7 integration plugins that use ConvertKit's v3 API require the API Secret, not the API Key. These two values are shown in the same settings page in ConvertKit under Advanced > API but they look different and have different lengths. Entering the API Key where the Secret is expected causes the connection to validate (it is a valid credential format) but subscriber operations fail silently.

Check: In ConvertKit (now Kit), go to Settings, then Advanced, then scroll to the API section. Confirm which credential your CF7 plugin is asking for and enter the matching one.

Cause 2: ConvertKit Rebranded to Kit — Old API Endpoints Are Changing

In 2024, ConvertKit officially rebranded to Kit and began migrating their API from v3 to v4. The v4 API uses OAuth 2.0 instead of API Key/Secret. Plugins that were built against the v3 API need to be updated to work with v4.

What this means for CF7 integrations:

Plugins using the old api.convertkit.com/v3/ base URL may stop working as Kit deprecates v3 endpoints
The new v4 API is at api.kit.com/v4/ with a completely different authentication flow
The tag application and subscriber creation payloads have changed between v3 and v4

If your CF7 to ConvertKit plugin was last updated before 2024, it may be running against deprecated v3 endpoints with an authentication pattern that is being phased out.

Check your plugin's last updated date. If it has not been updated since 2023, check the plugin changelog or support forum for v4/Kit migration notes.

Cause 3: Tag Name vs Tag ID Confusion

This is the most common cause of tags not being applied even when the subscriber is added correctly.

ConvertKit's v3 API applies tags using the tag's numeric ID, not its name. The tag named "Website Enquiry" has an ID like 4567890. If your integration is sending the tag name instead of the tag ID, ConvertKit accepts the subscriber but ignores the tag.

This is a confusing failure because some plugin UIs show tag names in a dropdown (they look up the IDs behind the scenes) while others require you to manually enter the tag ID. If your plugin asks for a "tag" and shows you a text field rather than a populated dropdown, it probably wants the numeric ID.

Find your tag IDs:

# ConvertKit v3
curl "https://api.convertkit.com/v3/tags?api_secret=YOUR_API_SECRET"

# Kit v4
curl "https://api.kit.com/v4/tags" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Each tag object in the response has an id field. That number is what goes in your tag configuration.

Apply a tag to a subscriber (v3):

POST https://api.convertkit.com/v3/tags/{TAG_ID}/subscribe
api_secret: YOUR_SECRET

{
  "api_secret": "YOUR_SECRET",
  "email": "subscriber@example.com"
}

Tag a subscriber (v4):

POST https://api.kit.com/v4/subscribers/{subscriber_id}/tags
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "tag_ids": [TAG_ID_1, TAG_ID_2]
}

Note: in v4, tagging requires the subscriber's ID, which means you must first create the subscriber and capture their ID from the response before you can apply tags. This is a two-step flow.

Cause 4: ConvertKit Forms vs Tags — Different Subscription Mechanisms

ConvertKit has two ways to subscribe someone: through a Form or through a Tag. These behave differently.

Subscribing via a Form: Uses the form's specific subscribe endpoint. Triggers the form's opt-in confirmation email if double opt-in is enabled. Places the subscriber in the form's subscriber list.

Subscribing with a Tag: Adds a tag to an existing or new subscriber. Does not send an opt-in confirmation unless you have an automation set up to trigger one.

Many CF7 to ConvertKit integrations only support Form-based subscription. If you configure one of these integrations expecting tags to be applied, you will find subscribers are added to the form's list but no tags appear.

If you need tags applied at subscription time, you need a plugin or direct API implementation that specifically supports the tag subscription endpoint, not just the form subscription endpoint.

Direct API Integration With Contact Form to API

Contact Form to API gives you direct control over which ConvertKit/Kit endpoint receives your data and what the payload looks like.

For a two-step ConvertKit v3 flow (create subscriber then apply tag):

Step 1 — Subscribe:

POST https://api.convertkit.com/v3/forms/{FORM_ID}/subscribe
Content-Type: application/json

{
  "api_key": "YOUR_API_KEY",
  "email": "[your-email]",
  "first_name": "[your-name]"
}

Step 2 — Apply tag (use the subscriber_id from Step 1 response):

POST https://api.convertkit.com/v3/tags/{TAG_ID}/subscribe
Content-Type: application/json

{
  "api_secret": "YOUR_SECRET",
  "email": "[your-email]"
}

The Pro version's chained API call feature passes the subscriber ID from Step 1's response into Step 2's payload automatically.

Quick Diagnosis

Symptom	Most Likely Cause
Connection validated but no forms in dropdown	API Key used instead of API Secret
Subscribers added but no tags applied	Tag name sent instead of Tag ID
Integration stopped working after Kit rebrand	Plugin using deprecated v3 endpoints
Double opt-in confirmation sent when using tag subscription	Wrong endpoint — using form subscribe instead of tag subscribe
Tags applied but automations not triggering	Tag ID correct but automation trigger not set up in Kit

DEV Community