Stripe & Billing Setup

Admin

PATHS uses a custom Stripe SDK integration for subscription billing. When users subscribe to a paid tier, Stripe handles payment processing and notifies PATHS via webhooks to update the user's membership tier automatically.

How Billing Works

The billing flow follows this sequence:

A user selects a membership tier and clicks "Subscribe" on the frontend.

PATHS creates a Stripe Checkout Session via POST /api/billing/checkout and redirects the user to Stripe's hosted payment page.

The user completes payment on Stripe's checkout page.

Stripe sends a webhook event to PATHS confirming the subscription.

PATHS processes the webhook and updates the user's membership tier to match their subscription.

Stripe Dashboard Setup

Stripe dashboard showing PATHS products with monthly and yearly prices — Create products and prices in Stripe, then link them to PATHS membership tiers.

Before billing works, configure these items in your Stripe dashboard:

Create Products — One product per membership tier (e.g., "PATHS Regular", "PATHS Premium").
Create Prices — Two prices per product: one monthly recurring, one yearly recurring.
Copy Price IDs — Each price has an ID starting with price_. You will paste these into PATHS.
Configure Webhook — Create a webhook endpoint pointing to https://your-domain/api/billing/webhook.

Webhook events

The webhook endpoint must receive at minimum: checkout.session.completed, customer.subscription.updated, and customer.subscription.deleted events.

Linking Prices to Tiers

After creating Stripe prices, link them to PATHS membership tiers:

Navigate to Membership Tiers in the admin panel.
Open each tier and paste the corresponding monthly and yearly Stripe price IDs.
Save each tier.

Without valid price IDs, the checkout endpoint returns a 400 error.

Required environment variables

Variable	Purpose
`STRIPE_SECRET_KEY`	Server-side API key for creating checkout sessions and managing subscriptions
`STRIPE_WEBHOOK_SECRET`	Webhook signing secret (`whsec_...`) for verifying webhook authenticity

Both must be set in your Render environment variables. The STRIPE_WEBHOOK_SECRET must match the signing secret shown in your Stripe webhook endpoint configuration.

Webhook endpoint configuration

Create a webhook endpoint in Stripe pointing to https://your-domain/api/billing/webhook. The endpoint must receive at minimum these events: checkout.session.completed, customer.subscription.updated, and customer.subscription.deleted.

Testing webhooks locally

Install the Stripe CLI.
Run stripe listen --forward-to localhost:3000/api/billing/webhook.
The CLI will provide a temporary webhook secret — use it as STRIPE_WEBHOOK_SECRET.
Trigger test events with stripe trigger checkout.session.completed.

Stripe webhook endpoint configuration page — Configure the webhook endpoint URL and select the required events.

Customer Portal

Users can manage their subscriptions (upgrade, downgrade, cancel) through the Stripe Customer Portal. PATHS redirects users to the portal via POST /api/billing/portal. Ensure the Customer Portal is configured in your Stripe dashboard under Settings > Customer Portal.

Subscription cancellation

When a subscription is canceled or expires, the webhook automatically downgrades the user to the Free tier. No manual intervention is needed.

Next Steps

Learn how to populate the platform with sample data in Seeding Content.