Many developers building SaaS and online services face the challenge of seamlessly connecting user authentication with subscription billing. Combining Clerk and Stripe creates a secure, scalable authentication and billing system, but the implementation requires attention to detail. In this article, I’ll walk through how to automatically assign new users a free plan when they register, handle upgrades to paid plans, and manage user deletion cleanly.

Prerequisites and Setup

This article assumes you’re working with the following tech stack:

Remix (deployed on Cloudflare Pages)

Clerk (authentication service)

Stripe (payment service)

TypeScript

First, install the necessary packages:

npm install @clerk/remix svix stripe

You’ll also need to set up the following environment variables:

CLERK_SECRET_KEY=sk_test_*****
CLERK_PUBLISHABLE_KEY=pk_test_*****
CLERK_WEBHOOK_SECRET=whsec_*****
STRIPE_SECRET_KEY=sk_test_*****

Implementation Overview

Here’s the flow we’ll implement:

A user registers with Clerk

We receive a user creation event via webhook

We create a Stripe customer and assign them a free subscription plan

We store the Stripe Customer ID in Clerk’s user metadata

We provide a way for users to manage their subscription in account settings

We clean up Stripe customer information when users delete their accounts

This approach creates a unified system for managing both users and billing.

Webhook Signature Verification

First, we need to verify that webhook requests from Clerk are legitimate. This is crucial for security.

import { WebhookEvent } from '@clerk/remix/ssr.server';
import { ActionFunctionArgs, json } from '@remix-run/cloudflare';
import { Webhook } from 'svix';
import Stripe from 'stripe';
import { createClerkClient } from '@clerk/remix/api.server'

export async function action({ context, request }: ActionFunctionArgs) {
  const {
    CLERK_WEBHOOK_SECRET,
    STRIPE_SECRET_KEY,
  } = context.cloudflare.env;
  if (!CLERK_WEBHOOK_SECRET) {
    throw new Error(
      'Please add CLERK_WEBHOOK_SECRET from Clerk Dashboard to .env or .env.local'
    );
  }

  const svixId = request.headers.get('svix-id');
  const svixTimestamp = request.headers.get('svix-timestamp');
  const svixSignature = request.headers.get('svix-signature');

  // If there are no headers, error out
  if (!svixId || !svixTimestamp || !svixSignature) {
    return new Response('Error occured -- no svix headers', {
      status: 400,
    });
  }

  const payload = await request.json();
  const body = JSON.stringify(payload);
  const webhook = new Webhook(CLERK_WEBHOOK_SECRET);
  let evt: WebhookEvent;
  try {
    evt = webhook.verify(body, {
      'svix-id': svixId,
      'svix-timestamp': svixTimestamp,
      'svix-signature': svixSignature,
    }) as WebhookEvent;
  } catch (err) {
    console.error('Error verifying webhook:', err);
    return new Response('Error occured', {
      status: 400,
    });
  }
  // Verification completed
  
  // Event-specific handling will be implemented below
}

This code relies on the fact that Clerk uses the Svix library to generate webhook signatures. We extract the svix-id, svix-timestamp, and svix-signature headers and verify them using the Webhook library.

Handling User Creation Events

When a user registers with Clerk, a user.created event is triggered. We’ll capture this event, create a Stripe customer, and assign them a free subscription.

  const stripe = new Stripe(STRIPE_SECRET_KEY);
  const clerkClient = createClerkClient({ secretKey: context.cloudflare.env.CLERK_SECRET_KEY })
  try {
    if (evt.type === 'user.created') {
      const {
        id: newUserId,
        username,
        email_addresses: email,
        first_name: firstName,
        last_name: lastName,
      } = evt.data;
      const customerProps: Stripe.CustomerCreateParams = {
        metadata: {
          clerk_user_id: newUserId
        }
      };
      if (firstName || lastName) {
        customerProps.name = [firstName, lastName].filter(Boolean).join(' ');
      } else if (username) {
        customerProps.name = username;
      }
      if (email) {
        customerProps.email = email[0].email_address;
      }
      const customer = await stripe.customers.create(customerProps);
      const {
        data: [price],
      } = await stripe.prices.list({ lookup_keys: ['free'] });
      await stripe.subscriptions.create({
        customer: customer.id,
        items: [
          {
            price: price.id,
            quantity: 1,
          },
        ],
      });

      await clerkClient.users.updateUserMetadata(newUserId, {
        privateMetadata: {
          stripeCustomerId: customer.id
        }
      })
    }
    // user.deleted event handling will follow

Key points here:

We use user information (name, email) for the Stripe customer record

We store the Clerk user ID in Stripe customer metadata (for later user lookups)

We search for the free plan using lookup_keys and create a subscription with the corresponding Price

We save the Stripe customer ID in Clerk user metadata (for subscription management)

Note the careful handling of user input data with filter(Boolean) since not all fields may be present.

Retrieving Stripe Customers and Customer Portal Redirection

To let users manage their subscriptions, we implement a redirect to Stripe’s Customer Portal:

import { getAuth } from '@clerk/remix/ssr.server';
import {
  LoaderFunction,
  LoaderFunctionArgs,
  redirect,
} from '@remix-run/cloudflare';
import Stripe from 'stripe';
import { createClerkClient } from '@clerk/remix/api.server';

export const loader: LoaderFunction = async (args: LoaderFunctionArgs) => {
  const { userId } = await getAuth(args, {
    // @ts-expect-error
    publishableKey: import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
  });
  if (!userId) {
    throw new Response('Unauthorized', {
      status: 401,
    });
  }
  const { CLERK_SECRET_KEY, STRIPE_SECRET_KEY } =
    args.context.cloudflare.env;

  const clerkClient = createClerkClient({ secretKey: CLERK_SECRET_KEY })
  const user = await clerkClient.users.getUser(userId)
  const stripeCustomerId = user.privateMetadata.stripe_customer_id as string

  const url = new URL(args.request.url);
  const baseUrl = `${url.protocol}//${url.host}`;
  const stripe = new Stripe(STRIPE_SECRET_KEY);
  console.log(userId)

  if (!stripeCustomerId) {
    throw new Response('Unauthorized', {
      status: 401,
    });
  }

  const billingPortalSession = await stripe.billingPortal.sessions.create({
    customer: stripeCustomerId,
    return_url: baseUrl,
  });
  if (billingPortalSession.url) {
    return redirect(billingPortalSession.url);
  }
  throw new Response('Internal server error', {
    status: 500,
  });
};

In this code:

We get the user ID from Clerk authentication

We retrieve the Stripe customer ID from user metadata

We create a Stripe billing portal session and redirect to its URL

This gives users easy access to Stripe’s portal where they can change plans, manage payment methods, and more.

Handling User Deletion Events

When a user deletes their Clerk account, we need to clean up their Stripe customer information:

    // Following the user creation event handler
    } else if (evt.type === 'user.deleted') {
      const deletedUserId = evt.data.id;
      if (!deletedUserId) {
        throw new Error("user id not found")
      }
      
      const searchResult = await stripe.customers.search({
        query: `metadata['clerk_user_id']:'${deletedUserId}'`,
      });
      if (searchResult.data && searchResult.data.length > 1) {
        const stripeCustomer = searchResult.data.find(customer => customer.metadata.clerk_user_id === deletedUserId)
        if (stripeCustomer) {
          await stripe.customers.del(stripeCustomer.id)
        }
      }
    }
    return json({
      message: 'ok',
    });

Important considerations:

At the time of deletion, we can’t directly fetch user info from Clerk, so we use the Clerk user ID stored in Stripe metadata

We use Stripe’s search API (customers.search) to find the customer by metadata

We delete the found customer record

Implementation Considerations

Metadata Consistency

It’s crucial to maintain cross-references between Clerk user IDs and Stripe customer IDs. This allows you to find corresponding entities from either system.

// Store Clerk user ID in Stripe customer metadata
const customerProps: Stripe.CustomerCreateParams = {
  metadata: {
    clerk_user_id: newUserId
  }
};

// Store Stripe customer ID in Clerk user metadata
await clerkClient.users.updateUserMetadata(newUserId, {
  privateMetadata: {
    stripeCustomerId: customer.id
  }
});

Idempotency

Webhooks can be sent multiple times, so your implementation must handle duplicate events gracefully. For Stripe customer and subscription creation, check whether they already exist to prevent duplicates.

Stripe Price Configuration

For all pricing tiers, including the free plan, set them up in the Stripe dashboard with lookup_keys for easy reference:

// Using lookup_key to find a price
const {
  data: [price],
} = await stripe.prices.list({ lookup_keys: ['free'] });

Conclusion and Next Steps

In this article, we’ve covered how to integrate Clerk and Stripe to create a subscription system with free trials. Key takeaways include:

Securing webhooks with signature verification

Automatically creating Stripe customers and assigning free plans on user registration

Implementing cross-references with metadata

Cleaning up customer information during user deletion

These techniques create a seamless experience for users while giving developers a manageable subscription system.

Advanced Implementations

To expand functionality, consider implementing:

Custom plan change flows: Create your own UI for plan changes instead of using Stripe’s billing portal

Usage limitations: Implement feature restrictions or quotas based on plan

Coupon support: Add a system for discounts and promotions

Team plans: Manage multiple users under a single billing account

The Clerk + Stripe combination offers a simple initial implementation while providing the flexibility to grow with your business. Give it a try in your next service!

Category: Clerk

Implementing Free Trial Subscriptions by Integrating Clerk and Stripe