Create Stripe Subscription

Learn how to set up recurring subscription billing with Stripe in Plainform.

Goal

By the end of this recipe, you'll have created a subscription product with recurring billing in Stripe.

Prerequisites

• Stripe account set up
• Basic understanding of Stripe products
• Access to Stripe Dashboard

Steps

https://dashboard.stripe.com/products

Unlimited projects
Priority support
Advanced analytics
Custom integrations
Team collaboration

npm run dev

Subscription Management

What Plainform Already Handles

1. User database sync: Clerk users are synced through the Clerk webhook.
2. Authenticated checkout: /api/stripe/checkout redirects anonymous users to /sign-in.
3. Stripe customer linking: Checkout creates or reuses a Stripe customer and stores metadata.clerkUserId.
4. Subscription webhook handlers: customer.subscription.created, customer.subscription.updated, and customer.subscription.deleted are handled separately.
5. Local subscription state: syncSubscription() writes status, price, period end, cancellation state, and planKey to the User row.
6. Subscription management: The user menu posts to /api/stripe/portal so customers can manage billing in Stripe Billing Portal.

What You Add For Your App

1. Plan metadata: Add fields like planKey, maxProjects, maxSeats, or credits to Stripe product/price metadata.
2. Entitlement persistence: Extend syncSubscription() to store those limits on your local user.
3. Access control: Check subscription status and plan limits before showing paid features.
4. Feature gating: Enforce limits in server actions, API routes, and protected pages.
5. Side effects: Add emails, audit logs, onboarding records, or cleanup logic in the matching event handler.

Example Implementation

Below is an example of how to handle subscriptions. Adapt it to your needs.

Database Schema

Add subscription fields to track user access:

model User {
  id                           String    @id
  email                        String    @unique
  stripeCustomerId             String?   @unique
  stripeSubscriptionId         String?   @unique
  stripePriceId                String?
  subscriptionStatus           String?   // 'active', 'canceled', 'past_due'
  subscriptionCurrentPeriodEnd DateTime? // When subscription expires
  cancelAtPeriodEnd            Boolean   @default(false)
  planKey                      String?   // From Stripe product metadata or price lookup key
  createdAt                    DateTime  @default(now())
  updatedAt                    DateTime  @updatedAt

  // Add your own feature limit fields based on your app
  // Examples:
  // maxProjects              String?   @default("0")
  // isUnlimitedProjects      Boolean   @default(false)
  // maxApiCalls              Int?      @default(1000)
  // maxTeamMembers           Int?      @default(1)
}

Key fields:

• subscriptionStatus: Current subscription state
• subscriptionCurrentPeriodEnd: When access expires (user keeps access until this date)
• cancelAtPeriodEnd: Whether the subscription is scheduled to cancel
• planKey: Stable app-facing plan identifier, usually from Stripe product metadata

Feature limit fields (customize for your app):

• Add fields like maxProjects, maxApiCalls, etc. based on what limits you need
• Store these in Stripe product metadata and sync them via webhooks

Where To Add App Logic

Plainform keeps one handler per subscription event:

app/api/webhooks/stripe/route.ts
  ├─ customer.subscription.created → handleSubscriptionCreated()
  ├─ customer.subscription.updated → handleSubscriptionUpdated()
  └─ customer.subscription.deleted → handleSubscriptionDeleted()

Use these locations intentionally:

• syncSubscription() for durable fields used by access control.
• handleSubscriptionCreated() for created-only effects like onboarding emails.
• handleSubscriptionUpdated() for upgrade, downgrade, renewal, or cancellation-scheduled effects.
• handleSubscriptionDeleted() for cleanup after access ends.

Example extension in syncSubscription():

const price = await stripe.prices.retrieve(priceId, {
  expand: ['product'],
});

const product = price.product as Stripe.Product;
const planKey = product.metadata?.planKey ?? price.lookup_key ?? null;
const maxProjects = product.metadata?.maxProjects ?? '0';

await prisma.user.upsert({
  where: { id: clerkUserId },
  update: {
    subscriptionStatus: subscription.status,
    subscriptionCurrentPeriodEnd: getSubscriptionPeriodEnd(subscription),
    cancelAtPeriodEnd: isCanceling(subscription),
    planKey,
    // maxProjects,
  },
  create: {
    id: clerkUserId,
    email,
    subscriptionStatus: subscription.status,
    subscriptionCurrentPeriodEnd: getSubscriptionPeriodEnd(subscription),
    cancelAtPeriodEnd: isCanceling(subscription),
    planKey,
    // maxProjects,
  },
});

Example created-only side effect:

export async function handleSubscriptionCreated(
  subscription: Stripe.Subscription
) {
  const res = await syncSubscription(subscription);

  if (!res.ok) {
    return res;
  }

  // Add your app logic after the subscription is synced:
  // await sendWelcomeEmail(subscription);
  // await createWorkspaceDefaults(subscription);
  // await recordBillingEvent(subscription, 'created');

  return res;
}

Example update-only side effect:

export async function handleSubscriptionUpdated(
  subscription: Stripe.Subscription
) {
  const res = await syncSubscription(subscription);

  if (!res.ok) {
    return res;
  }

  // Add your app logic after the latest plan/status is synced:
  // await notifyPlanChanged(subscription);
  // await resetMonthlyUsageIfNeeded(subscription);
  // await sendCancellationScheduledEmail(subscription);

  return res;
}

Example deleted-only side effect:

export async function handleSubscriptionDeleted(
  subscription: Stripe.Subscription
) {
  const res = await clearSubscription(subscription);

  if (!res.ok) {
    return res;
  }

  // Add your app logic after subscription fields are cleared:
  // await downgradeWorkspace(subscription);
  // await archivePaidResources(subscription);
  // await sendCancellationEmail(subscription);

  return res;
}

Access Control

Check subscription status before granting access:

export async function checkSubscriptionAccess(userId: string) {
  const user = await prisma.user.findUnique({
    where: { id: userId },
    select: {
      subscriptionStatus: true,
      subscriptionCurrentPeriodEnd: true,
    },
  });

  if (!user) return false;

  // Check if subscription is active
  if (user.subscriptionStatus !== 'active') return false;

  // Check if subscription hasn't expired
  if (user.subscriptionCurrentPeriodEnd) {
    const now = new Date();
    if (now > user.subscriptionCurrentPeriodEnd) return false;
  }

  return true;
}

Use in your app:

export default async function DashboardPage() {
  const { userId } = await auth();
  const hasAccess = await checkSubscriptionAccess(userId);

  if (!hasAccess) {
    redirect('/pricing');
  }

  return <Dashboard />;
}

Webhook Configuration

Add these events to your Stripe webhook:

1. Go to Stripe Dashboard → Developers → Webhooks
2. Add endpoint: https://yourdomain.com/api/webhooks/stripe
3. Select events:
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted

For complete webhook setup and data flow, see Stripe Webhook.

Important Notes

• User keeps access until currentPeriodEnd even if subscription is canceled
• Store product metadata (like maxProjects) in Stripe product settings
• Handle edge cases: payment failures, downgrades, upgrades
• Test thoroughly with Stripe test mode before going live

Common Issues

Subscription Not Creating

• Verify webhook endpoint is configured in Stripe Dashboard
• Check that webhook secret is set in .env
• Ensure the product has an active recurring price
• Check browser console and server logs for errors

Customer Not Charged

• Confirm the subscription is active in Stripe Dashboard
• Verify payment method is valid
• Check for failed payment events in Stripe Dashboard
• Review webhook logs for payment failures

Trial Not Working

• Ensure trial period is set on the price in Stripe Dashboard
• Verify the subscription was created with trial settings
• Check that the trial end date is correct in Stripe

Best Practices

Pricing Strategy:

• Offer both monthly and annual options
• Provide 15-20% discount for annual plans
• Consider a free trial to reduce friction

Communication:

• Send email confirmations for new subscriptions
• Notify users before trial ends
• Alert customers about failed payments

Cancellation:

• Make cancellation easy to build trust
• Offer pause or downgrade options
• Collect feedback on why users cancel

Next Steps

• Add Coupon - Create discount codes for subscriptions
• Test Payments Locally - Test subscription webhooks
• Customize Checkout - Customize the checkout experience