Documentation guide for Stripe subscription setup, webhooks, and pricing tiers.

Stripe integration for Nexora SaaS billing.

Use this guide to configure Stripe products, subscription pricing tiers, checkout sessions, webhook events, and the customer billing portal for your Nexora-powered SaaS.

Buy the starter kitView Stripe page

Subscription setup

Configure Stripe before accepting real payments.

Work through the billing setup in order: products, price IDs, checkout, webhook handling, customer portal access, and subscription state testing.

Step 1

Create Stripe products

Create one product for your SaaS and add recurring prices for each tier you plan to sell.

Configuration example

Starter plan: monthly recurring price
Pro plan: monthly recurring price
Team plan: monthly recurring price

Step 2

Add Stripe keys and price IDs

Add your Stripe secret key, publishable key, webhook secret, and plan price IDs to the environment.

Configuration example

STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID_PRO=price_...

Step 3

Map pricing tiers to checkout

Connect each visible pricing tier to a Stripe price ID so checkout starts with the correct subscription plan.

Configuration example

basic: STRIPE_PRICE_ID_BASIC
pro: STRIPE_PRICE_ID_PRO
enterprise: STRIPE_PRICE_ID_ENTERPRISE

Step 4

Configure webhook endpoint

Point Stripe webhook events at your live API route so subscription changes can update your SaaS state.

Configuration example

https://your-domain.com/api/stripe/webhook

Step 5

Handle subscription lifecycle

Listen for subscription creation, updates, cancellation, and invoice/payment events that affect product access.

Configuration example

checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.payment_failed

Step 6

Test checkout and billing portal

Use Stripe test mode to verify checkout, return URLs, webhook delivery, subscription state, and customer portal access.

Configuration example

npm run build
stripe listen --forward-to localhost:3000/api/stripe/webhook

Pricing tiers

Keep tiers simple until customers force complexity.

Stripe should model the recurring price. Your app should enforce the product limits, seats, usage, and access rules that belong to each plan.

Starter

Early users or solo customers who need the core workflow.

One monthly Stripe price with a simple feature limit.

Pro

Primary plan for customers who need the full product value.

One monthly or annual Stripe price with the main feature set.

Team

Higher-value customers who need seats, collaboration, or heavier usage.

Recurring Stripe price with seat or usage logic layered into your app.

Webhooks

Events your SaaS billing flow should understand.

checkout.session.completed

Confirm checkout succeeded and connect the Stripe customer or subscription to your app user.

customer.subscription.created

Create or activate subscription access after Stripe starts the subscription.

customer.subscription.updated

Update plan, status, cancellation, trial, or renewal data when the subscription changes.

customer.subscription.deleted

Remove paid access, downgrade the account, or mark the subscription as canceled.

invoice.payment_failed

Detect failed renewal payments and decide how your app should handle grace periods or access changes.

Launch checklist

Test billing before real customers arrive.

Use test mode before switching to live Stripe keys.

Confirm every pricing tier has the correct Stripe price ID.

Verify checkout success and cancel URLs point to the correct app routes.

Confirm the webhook signing secret matches the active endpoint.

Test subscription creation, upgrade, downgrade, cancellation, and failed payment paths.

Make sure the customer portal return URL points back to your dashboard.

Troubleshooting

Common Stripe setup issues.

Checkout starts with the wrong plan

Check that the selected pricing tier maps to the expected Stripe price ID in your environment and checkout request.

Webhooks are not being received

Confirm the endpoint URL, webhook signing secret, event selection, and local forwarding command if testing locally.

Subscription status does not update

Verify your webhook handler processes subscription events and persists the Stripe customer, subscription, and status fields.

Billing portal cannot open

Confirm the user has a Stripe customer ID and the portal return URL is configured for the current environment.

Stripe questions

Answers before subscription launch.

How do I set up Stripe subscriptions in a SaaS boilerplate?

Create Stripe products and recurring prices, map price IDs to your pricing tiers, create checkout sessions, listen for webhook events, and give customers access to the billing portal.

Which Stripe webhooks does a SaaS need?

Most SaaS apps should handle checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, and invoice.payment_failed.

How should I structure SaaS pricing tiers?

Start with a simple Starter, Pro, and Team structure. Use Stripe recurring prices for each tier, then enforce plan limits inside your app.

Start billing from a SaaS-aware Stripe foundation.

Nexora gives you Stripe checkout, subscription-oriented routes, webhooks, customer portal access, auth, dashboard, and pricing pages in one starter kit.

Buy the starter kitBack to setup guide