Skip to Content
StackBlaze Templates — operator documentation
AI SaaS KitGetting StartedYour first run

Your first run

You have the app booting and an account created. Here’s how to light up the two headline features — AI chat and billing — for the first time.

Try the AI chat

Add an AI key

Set your provider’s key in .env.local. For the default OpenAI provider:

AI_PROVIDER="openai"
AI_MODEL="gpt-4.1-mini"
OPENAI_API_KEY="sk-..."

Restart the dev server after editing env vars.

Open the chat

Go to /chat, type a message, and watch it stream back. Each call records token usage against your workspace’s monthly total.

See AI providers to switch models or providers.

Try billing (Stripe)

Plan upgrades are webhook-driven — the plan in your database only changes when Stripe events reach /api/billing/webhook. Locally, you forward those with the Stripe CLI.

Add your Stripe keys

BILLING_PROVIDER=stripe
NEXT_PUBLIC_BILLING_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PRICE_PRO=price_...
STRIPE_PRICE_TEAM=price_...

Forward webhooks

stripe listen --api-key "$STRIPE_SECRET_KEY" \
  --forward-to localhost:3000/api/billing/webhook

Copy the whsec_… it prints into STRIPE_WEBHOOK_SECRET, then restart the dev server.

Always pass --api-key "$STRIPE_SECRET_KEY". If your Stripe CLI is logged into more than one account, a bare stripe listen forwards from the CLI’s default account. When that differs from your app’s key, checkouts complete and Stripe creates the subscription, but the webhook never reaches your app — so the plan silently never updates. stripe trigger also fires on the default account, so it can look like it “works” while real checkout is broken.

Upgrade from the app

Go to /upgrade (or settings → billing), pick a plan, and complete Stripe’s test checkout (card 4242 4242 4242 4242). The webhook flips your plan, and your limits update immediately.

Switching plans as an existing subscriber needs the Stripe customer portal’s subscription-update feature enabled. New (free → paid) checkouts work without it. See Stripe in production for the one-time portal config.

Where to go next

Local setupEnvironment variables