How to Integrate ConvertKit with V0

Open V0 at v0.dev and describe the email signup form for your creator site. ConvertKit audiences expect polished, creator-aesthetic designs — describe the visual style you want, including the specific call to action copy, benefit-focused language, and the confirmation state. V0 generates React components with Tailwind CSS that work well for creator landing pages and inline blog components. For ConvertKit specifically, the form typically collects email (required) and first name (optional but important for personalized ConvertKit automations — ConvertKit sequences commonly include the subscriber's first name in email greetings). Specify both fields in your V0 prompt if your ConvertKit sequences use first name personalization. V0 does not have native ConvertKit integration, so all API work happens in your Next.js routes. Your V0 component just needs to know the API route path (/api/convertkit/subscribe) and the expected response format. Ask V0 to generate form state management with a loading spinner during submission, a success state showing a confirmation message, and an error state for failed submissions. After generating, use V0's Git panel to push to GitHub.

Create the Next.js API route that subscribes users through the ConvertKit API. The recommended ConvertKit approach is to subscribe via a specific form ID rather than directly creating a subscriber — form subscriptions trigger the form's associated automations and sequences. The endpoint is POST /v3/forms/{formId}/subscribe with the API key as a query parameter (ConvertKit v3 uses query string authentication, not headers). The request body is JSON with email, first_name (optional), and tags (array of tag names or IDs). ConvertKit's response includes a subscription object with the subscriber's ID, email, and current state. ConvertKit has a concept of 'subscriber states': active (confirmed), unconfirmed (pending double opt-in), cancelled, bounced, and complained. If your form is set up with double opt-in in ConvertKit, new subscribers start as 'unconfirmed' and only become 'active' after clicking the confirmation email — this is the GDPR-compliant flow. Your API route should return a useful success message based on the confirmation status: if the subscriber is 'unconfirmed', tell them to check their email for a confirmation link. The API endpoint URL format is: https://api.convertkit.com/v3/forms/{formId}/subscribe.

1// app/api/convertkit/subscribe/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const CONVERTKIT_API_BASE = 'https://api.convertkit.com/v3';
5
6interface SubscribeRequest {
7  email: string;
8  firstName?: string;
9  tags?: string[];
10  formId?: string; // Override default form
11}
12
13export async function POST(request: NextRequest) {
14  const apiKey = process.env.CONVERTKIT_API_KEY;
15  const defaultFormId = process.env.CONVERTKIT_FORM_ID;
16
17  if (!apiKey || !defaultFormId) {
18    return NextResponse.json(
19      { error: 'ConvertKit is not configured' },
20      { status: 500 }
21    );
22  }
23
24  let body: SubscribeRequest;
25  try {
26    body = await request.json();
27  } catch {
28    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
29  }
30
31  const { email, firstName, tags = [], formId } = body;
32
33  if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
34    return NextResponse.json({ error: 'Valid email is required' }, { status: 400 });
35  }
36
37  const targetFormId = formId || defaultFormId;
38
39  try {
40    const response = await fetch(
41      `${CONVERTKIT_API_BASE}/forms/${targetFormId}/subscribe`,
42      {
43        method: 'POST',
44        headers: {
45          'Content-Type': 'application/json; charset=utf-8',
46        },
47        body: JSON.stringify({
48          api_key: apiKey,
49          email,
50          first_name: firstName || '',
51          tags,
52        }),
53      }
54    );
55
56    const data = await response.json();
57
58    if (!response.ok || !data.subscription) {
59      // ConvertKit returns errors in a different shape
60      const errorMessage = data.message || data.error || 'Failed to subscribe';
61      return NextResponse.json({ error: errorMessage }, { status: 400 });
62    }
63
64    const { subscription } = data;
65    const state = subscription.subscriber?.state;
66
67    // Determine the right success message based on confirmation state
68    let message = 'Successfully subscribed!';
69    if (state === 'unconfirmed') {
70      message = 'Check your email for a confirmation link to complete your signup.';
71    }
72
73    return NextResponse.json({
74      success: true,
75      message,
76      subscriberId: subscription.subscriber?.id,
77      state,
78    });
79  } catch (error) {
80    const message = error instanceof Error ? error.message : 'Unknown error';
81    console.error('ConvertKit subscription error:', message);
82    return NextResponse.json(
83      { error: 'Failed to subscribe. Please try again.' },
84      { status: 500 }
85    );
86  }
87}

Update your V0-generated signup form to post to /api/convertkit/subscribe and handle both direct subscription (active state) and double opt-in (unconfirmed state) responses. The API returns a message field that differentiates these cases — if the subscriber is in unconfirmed state, the message asks them to check their email for a confirmation link. Your form should display this message directly rather than a generic success message. This is important for creator email lists where double opt-in is standard practice and subscribers need to understand why they don't immediately receive the welcome email. For the tags field, pass a source tag that identifies where the signup came from (e.g., tags: ['homepage', 'blog-cta', 'lead-magnet-pdf']) to enable ConvertKit segmentation. If you have multiple forms on your site targeting different audiences, pass the form ID for each form separately — ConvertKit automations are configured per-form, so using the correct form ID ensures the right welcome sequence fires. Test the full flow by subscribing with a real email address and verifying that ConvertKit's automation sequence triggers correctly.

Push your code to GitHub and configure ConvertKit credentials in Vercel. Open the Vercel Dashboard, navigate to your project, and go to Settings → Environment Variables. Add CONVERTKIT_API_KEY with your ConvertKit API key — found at ConvertKit (or Kit) → Settings → Advanced → API Key (it's a short alphanumeric string, not a long JWT). Add CONVERTKIT_FORM_ID with the numeric ID of your ConvertKit form — you can find this in the URL when you open the form in ConvertKit (it's a number like 1234567). Neither variable should have the NEXT_PUBLIC_ prefix. The API key grants full access to your ConvertKit account including subscriber data, so it must stay server-side. Set both variables for Production, Preview, and Development environments, save, and trigger a redeployment. After deployment, test the live form by subscribing with a real email and checking your ConvertKit Subscribers page — the subscriber should appear within a few seconds with the 'homepage' tag applied. If you used double opt-in, you'll see them in the 'Unconfirmed' state until they click the confirmation email. Also check your ConvertKit Automations to verify that the form's welcome sequence was triggered.