Stripe

Stripe handles payment processing, subscription management, and invoicing.

Create a Stripe Account

1. Go to stripe.com and create an account
2. Complete the onboarding to enable payments

Get Your API Keys

Navigate to Developers → API Keys in your Stripe dashboard:

Billing Modes

VelocityKit supports multiple billing models out of the box:

How It Works

The billing mode is determined automatically based on your Stripe price configuration:

• Recurring prices → Subscription mode (access while subscription active)
• One-time prices → Payment mode (access for grant_months duration)

For one-time purchases, set the grant_months metadata on your Stripe product:

Create Products and Prices

VelocityKit fetches products and prices directly from Stripe using product metadata. No price IDs need to be configured in environment variables.

Option 1: Setup Wizard (Recommended)

The pnpm onboard wizard can create products automatically:

pnpm onboard

It will:

1. Ask for your product name and pricing
2. Create the product in Stripe via API
3. Set up monthly and yearly prices with correct metadata

Option 2: Stripe Dashboard

1. Go to Products → Add Product
2. Create your product with metadata:
   • plan_type: free or paid
   • highlighted: true for the recommended plan
   • cta_label: Button text (e.g., "Get Started")
   • sort_order: Display order (0, 1, 2...)
   • grant_months: For one-time prices, access duration (12, 24, 9999 for lifetime)
3. Add features using Marketing features (up to 15)
4. Add pricing (monthly, yearly, one-time, etc.)

Set Up Webhooks

Webhooks sync subscription status from Stripe to your database.

Production Webhooks

1. Go to Developers → Webhooks in Stripe
2. Click Add endpoint
3. Enter your URL: https://your-domain.com/api/webhooks/stripe
4. Select these events:
   • checkout.session.completed
   • customer.subscription.updated
   • customer.subscription.deleted
5. Copy the Signing secret to STRIPE_WEBHOOK_SECRET

Local Development

Use the Stripe CLI to forward webhooks locally:

# Install Stripe CLI (if not already)
brew install stripe/stripe-cli/stripe

# Login to Stripe
stripe login

# Forward webhooks to your local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe

Copy the webhook signing secret from the CLI output to your .env.local.

Billing Flow

Here's how billing works in VelocityKit:

1. User clicks Upgrade → Creates a Stripe Checkout session
2. Stripe processes payment → Sends checkout.session.completed webhook
3. Webhook handler → Updates profiles.subscription_status in Supabase
4. User returns → Sees Pro features unlocked

Customer Portal

Users can manage their subscription through Stripe's Customer Portal:

• Update payment method
• Cancel subscription
• View invoices
• Download receipts

The portal is accessible from the account settings page.

Testing Payments

Use Stripe's test cards during development:

Use any future expiration date and any 3-digit CVC.