Billing Setup | Client Guides

The SaaS starter kit supports dual payment providers - Stripe AND LemonSqueezy can work simultaneously. Configure one or both based on your business needs.

ℹ️

Prerequisites

Stripe account (for Stripe payments) at stripe.com
LemonSqueezy account (for LemonSqueezy payments) at lemonsqueezy.com
Basic understanding of webhooks and API keys

Overview

The billing system provides:

Dual Provider Support: Use Stripe, LemonSqueezy, or both simultaneously
Flexible Pricing: Configure any combination of monthly, yearly, or one-time payments - the system adapts automatically
Multiple Plans: Free, Pro, and Enterprise tiers (fully customizable)
User-Centric Billing: Each user has their own subscription (B2C model)
Webhook Integration: Automatic subscription status updates
Customer Portal: Users can manage their billing directly with providers

Stripe Setup

Get Stripe API Keys

Log into your Stripe Dashboard and copy your API keys:

Navigate to Developers → API Keys
Copy the "Publishable key" (starts with pk_)
Copy the "Secret key" (starts with sk_)
Add both to your .env.local

.env.local

1# Stripe Configuration
2NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
3STRIPE_SECRET_KEY="sk_test_..."

⚠️

Security

Never commit your sk_ secret key to version control. Keep it in .env.local which is gitignored.

Create Stripe Products and Prices

In the Stripe Products page:

Create a product called "Pro Plan"
Add one or more pricing options (the system adapts automatically):
- Monthly recurring: $19/month (optional)
- Yearly recurring: $190/year (optional)
- One-time payment: $299 (optional)
Copy each Price ID (starts with price_)
Repeat for "Enterprise Plan"

ℹ️

Flexible Pricing

You can create any combination of pricing options. The system automatically detects which intervals are available and shows only the relevant options on your pricing page. For example, you can have only one-time payments, or only monthly subscriptions - it all works!

Configure Stripe Price IDs

Add your Stripe Price IDs to .env.local. Only add the IDs for the pricing options you created:

.env.local

1# Stripe Price IDs (only add the ones you're using)
2STRIPE_PRICE_PRO_MONTHLY="price_..."      # Optional
3STRIPE_PRICE_PRO_YEARLY="price_..."       # Optional
4STRIPE_PRICE_PRO_ONE_TIME="price_..."     # Optional
5STRIPE_PRICE_ENTERPRISE_MONTHLY="price_..." # Optional
6STRIPE_PRICE_ENTERPRISE_YEARLY="price_..."  # Optional
7STRIPE_PRICE_ENTERPRISE_ONE_TIME="price_..." # Optional

💡

Skip Unused Options

Leave blank or omit any pricing options you don't need. For example, if you only want one-time payments, just configure the *_ONE_TIME variables and leave the rest empty.

These IDs are automatically loaded in src/lib/billing/plans.ts

Set Up Stripe Webhook

Webhooks allow Stripe to notify your app about subscription changes:

Go to Stripe Webhooks
Click "Add endpoint"
Enter your webhook URL: https://yourdomain.com/api/billing/stripe/webhook
Select events to listen to:
- checkout.session.completed
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
Copy the "Signing secret" (starts with whsec_)

.env.local

1# Stripe Webhook
2STRIPE_WEBHOOK_SECRET="whsec_..."

Test Stripe Integration

Use Stripe's test mode to verify your setup:

Visit your pricing page: /pricing
Click "Get Started" on any paid plan
Use test card: 4242 4242 4242 4242
Complete checkout and verify subscription appears in your dashboard

💡

Testing

Use Stripe test cards to simulate different scenarios (declined cards, authentication required, etc.)

LemonSqueezy Setup

Get LemonSqueezy API Key

Log into your LemonSqueezy Settings:

Navigate to Settings → API
Create a new API key
Copy the API key
Find your Store ID in Settings → Stores

.env.local

1# LemonSqueezy Configuration
2LEMONSQUEEZY_API_KEY="..."
3LEMONSQUEEZY_STORE_ID="..."

Create LemonSqueezy Products

In the LemonSqueezy Products page:

Create a product called "Pro Plan"
Add one or more variants (the system adapts automatically):
- Monthly subscription (optional)
- Yearly subscription (optional)
- One-time payment (optional)
Copy each Variant ID
Repeat for "Enterprise Plan"

ℹ️

Flexible Variants

You can create any combination of variants. The system automatically detects which billing cycles are available and adapts the pricing page accordingly. Choose only the variants that match your business model!

Configure LemonSqueezy Variant IDs

Add your LemonSqueezy Variant IDs to .env.local. Only add the IDs for the variants you created:

.env.local

1# LemonSqueezy Variant IDs (only add the ones you're using)
2LEMONSQUEEZY_VARIANT_PRO_MONTHLY="..."      # Optional
3LEMONSQUEEZY_VARIANT_PRO_YEARLY="..."       # Optional
4LEMONSQUEEZY_VARIANT_PRO_ONE_TIME="..."     # Optional
5LEMONSQUEEZY_VARIANT_ENTERPRISE_MONTHLY="..." # Optional
6LEMONSQUEEZY_VARIANT_ENTERPRISE_YEARLY="..."  # Optional
7LEMONSQUEEZY_VARIANT_ENTERPRISE_ONE_TIME="..." # Optional

💡

Skip Unused Variants

Leave blank or omit any variants you don't need. The system automatically adapts to show only the available billing cycles on your pricing page.

Set Up LemonSqueezy Webhook

Configure webhooks to receive subscription updates:

Go to Settings → Webhooks
Click "Create webhook"
Enter your webhook URL: https://yourdomain.com/api/billing/lemonsqueezy/webhook
Copy the webhook signing secret

.env.local

1# LemonSqueezy Webhook
2LEMONSQUEEZY_WEBHOOK_SECRET="..."

Understanding the Billing System

Plan Configuration

Plans are defined in src/lib/billing/plans.ts:

src/lib/billing/plans.ts

1export const PLANS = {
2  free: {
3    id: "free",
4    name: "Free",
5    description: "Perfect for trying out the platform",
6    limits: {},
7    stripePriceMonthly: null,
8    stripePriceYearly: null,
9    lemonVariantMonthly: null,
10    lemonVariantYearly: null,
11    features: ["Basic features", "Community support"],
12    isDefault: true,
13  },
14  pro: {
15    id: "pro",
16    name: "Pro",
17    description: "For power users and professionals",
18    limits: {},
19    stripePriceMonthly: process.env.STRIPE_PRICE_PRO_MONTHLY || null,
20    stripePriceYearly: process.env.STRIPE_PRICE_PRO_YEARLY || null,
21    lemonVariantMonthly: process.env.LEMONSQUEEZY_VARIANT_PRO_MONTHLY || null,
22    lemonVariantYearly: process.env.LEMONSQUEEZY_VARIANT_PRO_YEARLY || null,
23    priceOneTime: 299,
24    features: [
25      "All basic features",
26      "Priority support",
27      "Advanced analytics",
28      "Custom integrations",
29    ],
30    highlighted: true,
31  },
32  // ... enterprise plan
33};

Subscription Database Schema

prisma/schema.prisma

1model Subscription {
2  id                  String             @id @default(cuid())
3  userId              String             @unique
4 
5  // Provider info
6  provider            PaymentProvider    // stripe | lemonsqueezy
7  customerId          String
8  subscriptionId      String?
9 
10  // Plan info
11  planId              String             // free | pro | enterprise
12  status              SubscriptionStatus // active | canceled | past_due | etc.
13 
14  // Billing period
15  currentPeriodStart  DateTime?
16  currentPeriodEnd    DateTime?
17  cancelAtPeriodEnd   Boolean            @default(false)
18 
19  user                User               @relation(fields: [userId], references: [id])
20 
21  createdAt           DateTime           @default(now())
22  updatedAt           DateTime           @updatedAt
23}

Webhook Handling

Webhooks are processed by API routes that update the database:

src/app/api/billing/stripe/webhook/route.ts - Handles Stripe events
src/app/api/billing/lemonsqueezy/webhook/route.ts - Handles LemonSqueezy events

When a subscription is created, updated, or canceled, the webhook automatically updates the user's subscription record in the database.

User Flow

User clicks "Get Started" on pricing page
System creates/retrieves customer in payment provider
User is redirected to checkout page (Stripe Checkout or LemonSqueezy)
User completes payment
Webhook receives event and creates subscription in database
User is redirected back to app with active subscription

Troubleshooting

Checkout Not Working

Verify all API keys are correctly set in .env.local
Check that Price IDs / Variant IDs match your provider dashboard
Ensure NEXT_PUBLIC_APP_URL is set for redirect URLs
Check browser console for errors

Webhook Not Receiving Events

Verify webhook URL is publicly accessible (not localhost)
Use ngrok for local development testing
Check webhook signing secret matches environment variable
Review webhook logs in provider dashboard

Subscription Not Showing After Payment

Check webhook was successfully processed (check API logs)
Verify database was updated (check Prisma Studio)
Ensure user is logged in with the same account used for payment

Customization

Add New Plans

To add a new plan, update src/lib/billing/plans.ts:

src/lib/billing/plans.ts

1export const PLANS = {
2  // ... existing plans
3  custom: {
4    id: "custom",
5    name: "Custom",
6    description: "For special needs",
7    limits: {},
8    stripePriceMonthly: process.env.STRIPE_PRICE_CUSTOM_MONTHLY || null,
9    lemonVariantMonthly: process.env.LEMONSQUEEZY_VARIANT_CUSTOM_MONTHLY || null,
10    features: ["Custom features"],
11  },
12};

Customize Plan Features

Edit the features array to change what's displayed on the pricing page.

Add Usage Limits

Extend the PlanLimits interface to add custom limits:

src/lib/billing/plans.ts

1export interface PlanLimits {
2  maxStorage?: number;        // in GB
3  maxApiCalls?: number;       // per month
4  maxUsers?: number;          // for team plans
5}

Related Guides

Database Schema

Understand the database structure and relationships in your SaaS application

Admin Dashboard

Learn how to manage admin access and view system statistics

Production Deployment

Deploy your SaaS application to production with comprehensive setup and documentation removal instructions

💡

Next Steps

Now that you understand billing, you might want to:

Learn about Database Schema to understand the data structure
Explore Admin Dashboard to track revenue
Review Production Deployment for going live

The SaaS starter kit supports dual payment providers - Stripe AND LemonSqueezy can work simultaneously. Configure one or both based on your business needs.

ℹ️

Prerequisites

Stripe account (for Stripe payments) at stripe.com
LemonSqueezy account (for LemonSqueezy payments) at lemonsqueezy.com
Basic understanding of webhooks and API keys

Overview

The billing system provides:

Dual Provider Support: Use Stripe, LemonSqueezy, or both simultaneously
Flexible Pricing: Configure any combination of monthly, yearly, or one-time payments - the system adapts automatically
Multiple Plans: Free, Pro, and Enterprise tiers (fully customizable)
User-Centric Billing: Each user has their own subscription (B2C model)
Webhook Integration: Automatic subscription status updates
Customer Portal: Users can manage their billing directly with providers

Stripe Setup

Get Stripe API Keys

Log into your Stripe Dashboard and copy your API keys:

Navigate to Developers → API Keys
Copy the "Publishable key" (starts with pk_)
Copy the "Secret key" (starts with sk_)
Add both to your .env.local

.env.local

1# Stripe Configuration
2NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
3STRIPE_SECRET_KEY="sk_test_..."

⚠️

Security

Never commit your sk_ secret key to version control. Keep it in .env.local which is gitignored.

Create Stripe Products and Prices

In the Stripe Products page:

Create a product called "Pro Plan"
Add one or more pricing options (the system adapts automatically):
- Monthly recurring: $19/month (optional)
- Yearly recurring: $190/year (optional)
- One-time payment: $299 (optional)
Copy each Price ID (starts with price_)
Repeat for "Enterprise Plan"

ℹ️

Flexible Pricing

Configure Stripe Price IDs

Add your Stripe Price IDs to .env.local. Only add the IDs for the pricing options you created:

.env.local

1# Stripe Price IDs (only add the ones you're using)
2STRIPE_PRICE_PRO_MONTHLY="price_..."      # Optional
3STRIPE_PRICE_PRO_YEARLY="price_..."       # Optional
4STRIPE_PRICE_PRO_ONE_TIME="price_..."     # Optional
5STRIPE_PRICE_ENTERPRISE_MONTHLY="price_..." # Optional
6STRIPE_PRICE_ENTERPRISE_YEARLY="price_..."  # Optional
7STRIPE_PRICE_ENTERPRISE_ONE_TIME="price_..." # Optional

💡

Skip Unused Options

Leave blank or omit any pricing options you don't need. For example, if you only want one-time payments, just configure the *_ONE_TIME variables and leave the rest empty.

These IDs are automatically loaded in src/lib/billing/plans.ts

Set Up Stripe Webhook

Webhooks allow Stripe to notify your app about subscription changes:

Go to Stripe Webhooks
Click "Add endpoint"
Enter your webhook URL: https://yourdomain.com/api/billing/stripe/webhook
Select events to listen to:
- checkout.session.completed
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
Copy the "Signing secret" (starts with whsec_)

.env.local

1# Stripe Webhook
2STRIPE_WEBHOOK_SECRET="whsec_..."

Test Stripe Integration

Use Stripe's test mode to verify your setup:

Visit your pricing page: /pricing
Click "Get Started" on any paid plan
Use test card: 4242 4242 4242 4242
Complete checkout and verify subscription appears in your dashboard

💡

Testing

Use Stripe test cards to simulate different scenarios (declined cards, authentication required, etc.)

LemonSqueezy Setup

Get LemonSqueezy API Key

Log into your LemonSqueezy Settings:

Navigate to Settings → API
Create a new API key
Copy the API key
Find your Store ID in Settings → Stores

.env.local

1# LemonSqueezy Configuration
2LEMONSQUEEZY_API_KEY="..."
3LEMONSQUEEZY_STORE_ID="..."

Create LemonSqueezy Products

In the LemonSqueezy Products page:

Create a product called "Pro Plan"
Add one or more variants (the system adapts automatically):
- Monthly subscription (optional)
- Yearly subscription (optional)
- One-time payment (optional)
Copy each Variant ID
Repeat for "Enterprise Plan"

ℹ️

Flexible Variants

Configure LemonSqueezy Variant IDs

Add your LemonSqueezy Variant IDs to .env.local. Only add the IDs for the variants you created:

.env.local

1# LemonSqueezy Variant IDs (only add the ones you're using)
2LEMONSQUEEZY_VARIANT_PRO_MONTHLY="..."      # Optional
3LEMONSQUEEZY_VARIANT_PRO_YEARLY="..."       # Optional
4LEMONSQUEEZY_VARIANT_PRO_ONE_TIME="..."     # Optional
5LEMONSQUEEZY_VARIANT_ENTERPRISE_MONTHLY="..." # Optional
6LEMONSQUEEZY_VARIANT_ENTERPRISE_YEARLY="..."  # Optional
7LEMONSQUEEZY_VARIANT_ENTERPRISE_ONE_TIME="..." # Optional

💡

Skip Unused Variants

Leave blank or omit any variants you don't need. The system automatically adapts to show only the available billing cycles on your pricing page.

Set Up LemonSqueezy Webhook

Configure webhooks to receive subscription updates:

Go to Settings → Webhooks
Click "Create webhook"
Enter your webhook URL: https://yourdomain.com/api/billing/lemonsqueezy/webhook
Copy the webhook signing secret

.env.local

1# LemonSqueezy Webhook
2LEMONSQUEEZY_WEBHOOK_SECRET="..."

Understanding the Billing System

Plan Configuration

Plans are defined in src/lib/billing/plans.ts:

src/lib/billing/plans.ts

1export const PLANS = {
2  free: {
3    id: "free",
4    name: "Free",
5    description: "Perfect for trying out the platform",
6    limits: {},
7    stripePriceMonthly: null,
8    stripePriceYearly: null,
9    lemonVariantMonthly: null,
10    lemonVariantYearly: null,
11    features: ["Basic features", "Community support"],
12    isDefault: true,
13  },
14  pro: {
15    id: "pro",
16    name: "Pro",
17    description: "For power users and professionals",
18    limits: {},
19    stripePriceMonthly: process.env.STRIPE_PRICE_PRO_MONTHLY || null,
20    stripePriceYearly: process.env.STRIPE_PRICE_PRO_YEARLY || null,
21    lemonVariantMonthly: process.env.LEMONSQUEEZY_VARIANT_PRO_MONTHLY || null,
22    lemonVariantYearly: process.env.LEMONSQUEEZY_VARIANT_PRO_YEARLY || null,
23    priceOneTime: 299,
24    features: [
25      "All basic features",
26      "Priority support",
27      "Advanced analytics",
28      "Custom integrations",
29    ],
30    highlighted: true,
31  },
32  // ... enterprise plan
33};

Subscription Database Schema

prisma/schema.prisma

1model Subscription {
2  id                  String             @id @default(cuid())
3  userId              String             @unique
4 
5  // Provider info
6  provider            PaymentProvider    // stripe | lemonsqueezy
7  customerId          String
8  subscriptionId      String?
9 
10  // Plan info
11  planId              String             // free | pro | enterprise
12  status              SubscriptionStatus // active | canceled | past_due | etc.
13 
14  // Billing period
15  currentPeriodStart  DateTime?
16  currentPeriodEnd    DateTime?
17  cancelAtPeriodEnd   Boolean            @default(false)
18 
19  user                User               @relation(fields: [userId], references: [id])
20 
21  createdAt           DateTime           @default(now())
22  updatedAt           DateTime           @updatedAt
23}

Webhook Handling

Webhooks are processed by API routes that update the database:

src/app/api/billing/stripe/webhook/route.ts - Handles Stripe events
src/app/api/billing/lemonsqueezy/webhook/route.ts - Handles LemonSqueezy events

When a subscription is created, updated, or canceled, the webhook automatically updates the user's subscription record in the database.

User Flow

User clicks "Get Started" on pricing page
System creates/retrieves customer in payment provider
User is redirected to checkout page (Stripe Checkout or LemonSqueezy)
User completes payment
Webhook receives event and creates subscription in database
User is redirected back to app with active subscription

Troubleshooting

Checkout Not Working

Verify all API keys are correctly set in .env.local
Check that Price IDs / Variant IDs match your provider dashboard
Ensure NEXT_PUBLIC_APP_URL is set for redirect URLs
Check browser console for errors

Webhook Not Receiving Events

Verify webhook URL is publicly accessible (not localhost)
Use ngrok for local development testing
Check webhook signing secret matches environment variable
Review webhook logs in provider dashboard

Subscription Not Showing After Payment

Check webhook was successfully processed (check API logs)
Verify database was updated (check Prisma Studio)
Ensure user is logged in with the same account used for payment

Customization

Add New Plans

To add a new plan, update src/lib/billing/plans.ts:

src/lib/billing/plans.ts

1export const PLANS = {
2  // ... existing plans
3  custom: {
4    id: "custom",
5    name: "Custom",
6    description: "For special needs",
7    limits: {},
8    stripePriceMonthly: process.env.STRIPE_PRICE_CUSTOM_MONTHLY || null,
9    lemonVariantMonthly: process.env.LEMONSQUEEZY_VARIANT_CUSTOM_MONTHLY || null,
10    features: ["Custom features"],
11  },
12};

Customize Plan Features

Edit the features array to change what's displayed on the pricing page.

Add Usage Limits

Extend the PlanLimits interface to add custom limits:

src/lib/billing/plans.ts

1export interface PlanLimits {
2  maxStorage?: number;        // in GB
3  maxApiCalls?: number;       // per month
4  maxUsers?: number;          // for team plans
5}

Next Steps

Now that you understand billing, you might want to:

Learn about Database Schema to understand the data structure
Explore Admin Dashboard to track revenue
Review Production Deployment for going live