Stripe Payments & Billing

What's Included

The LaunchSaaS Stripe package handles the full billing lifecycle — from a user clicking "Buy" to managing their subscription months later:

• Stripe Checkout — hosted checkout page for one-time payments and subscriptions
• Webhook handler — idempotent processing of all relevant Stripe events
• Customer portal — Stripe-hosted portal for subscription management, payment updates, and cancellations
• Subscription management — create, upgrade, downgrade, pause, cancel
• One-time payments — single-charge mode for lifetime access or one-off products
• Failed payment handling — grace period logic and user notification emails
• Stripe Customer sync — Stripe customer ID stored against Supabase user for fast lookups

Webhook Events Handled

LaunchSaaS handles the following Stripe webhook events out of the box:

All handlers are idempotent. Stripe retries failed webhook deliveries up to 25 times over 72 hours — LaunchSaaS tracks processed event IDs to prevent duplicate side effects.

Setup Guide

Step 1: Get your Stripe API keys

In the Stripe Dashboard, go to Developers → API Keys. Copy the secret key. Use test mode keys (sk_test_...) for development, live keys (sk_live_...) for production.

Add to your environment:

STRIPE_SECRET_KEY=sk_test_...

Step 2: Create a product and price in Stripe

Go to Stripe Dashboard → Products → Add Product. Create your product and set the price. Copy the price ID (starts with price_). For a simple one-time purchase, use a one-time price. For subscriptions, use a recurring price.

Step 3: Set up the webhook endpoint

For local development, use the Stripe CLI (see testing section). For production:

1. Go to Stripe Dashboard → Developers → Webhooks → Add endpoint.
2. Set URL to https://yourdomain.com/api/webhooks.
3. Select the events listed in the table above.
4. Copy the signing secret and add it as STRIPE_WEBHOOK_SECRET.

Step 4: Configure the checkout

The checkout API route is at app/api/create-checkout/route.ts. By default it uses mode: 'payment' for one-time purchases. To switch to subscriptions, change to mode: 'subscription' and pass a recurring price ID.

Testing Locally with Stripe CLI

Install the Stripe CLI:

# macOS
brew install stripe/stripe-cli/stripe

# Other platforms: https://stripe.com/docs/stripe-cli

Authenticate and start forwarding events:

stripe login
stripe listen --forward-to localhost:3000/api/webhooks

The CLI will output a webhook signing secret starting with whsec_. Use this as your STRIPE_WEBHOOK_SECRET during local development.

Test card numbers:

• Successful payment: 4242 4242 4242 4242
• Payment declined: 4000 0000 0000 0002
• Requires 3D Secure: 4000 0025 0000 3155

Customization

Changing the price

Update the price in your Stripe Dashboard and pass the new price ID when creating a checkout session. The checkout route accepts a priceId in the request body, so you can offer multiple plans without duplicating routes.

Adding a free trial

Add subscription_data: { trial_period_days: 14 } to the Stripe Checkout session parameters in app/api/create-checkout/route.ts.

Customizing the success page

The success_url in the checkout session creation points to /success by default. Update this to any route in your application. The success page can read the Stripe session ID from the URL query parameter to display order-specific information.

Frequently Asked Questions

Does LaunchSaaS support both subscription billing and one-time payments?

Yes. LaunchSaaS includes Stripe Checkout configured for both subscription (recurring) and one-time payment modes. Switching between them is a single parameter change in the checkout session creation. Webhook handlers are included for both payment types.

Which Stripe webhook events does LaunchSaaS handle out of the box?

LaunchSaaS handles: checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.payment_succeeded, invoice.payment_failed, and customer.updated. Each event has idempotent handling to prevent duplicate processing.

How do I test Stripe payments locally without deploying?

Install the Stripe CLI and run stripe listen --forward-to localhost:3000/api/webhooks. This tunnels Stripe webhook events to your local development server. Use test card number 4242 4242 4242 4242 with any future expiry and any CVC for successful payments.

How do I change the price or add a new pricing plan in LaunchSaaS?

Create the product and price in the Stripe Dashboard first. Then pass the new price ID when creating checkout sessions. The checkout API route accepts a priceId parameter, so you can pass different IDs from different buttons without changing route code.

Does LaunchSaaS include a customer billing portal for managing subscriptions?

Yes. LaunchSaaS includes a link to the Stripe Customer Portal, which lets users upgrade, downgrade, cancel, and update their payment method without any custom UI from you. You configure which actions to allow in the Stripe Dashboard under Billing → Customer Portal.

What happens if a webhook delivery fails — does LaunchSaaS have retry handling?

Stripe automatically retries failed webhook deliveries up to 25 times over 72 hours. LaunchSaaS's webhook handlers are idempotent — each event is checked against a processed-event log before taking action to prevent duplicate database writes.