Polar.sh is the default payments provider in the scaffold. It handles subscription management, checkout flows, customer portals, and webhook events for subscription lifecycle changes.

1. Go to polar.sh and sign up for an account
2. Complete your organization profile
3. Connect a payment method (Stripe account) - Polar uses Stripe as the payment processor
4. Navigate to your organization dashboard

1. In your Polar dashboard, go to "Products" → "New Product"
2. Create your subscription tiers (e.g., "Starter" and "Professional")
3. For each product:
   • Set the name, description, and pricing
   • Choose billing interval (monthly, yearly, etc.)
   • Copy the Product ID (you'll need this)
   • Copy the Product Slug (you'll need this too)
4. Make note of at least one product ID and slug for your starter tier

1. Go to "Settings" → "API Keys" in your Polar dashboard
2. Click "Generate API Key"
3. Name it (e.g., "Production API Key" or "Development")
4. Copy the Access Token - this is your POLAR_ACCESS_TOKEN
5. Important: Store this securely - you won't be able to see it again after closing the dialog

Webhooks notify your app when subscription events occur (created, canceled, updated, etc.).

Step 1: Generate Webhook Secret

1. Go to "Settings" → "Webhooks" in your Polar dashboard
2. Click "Add Endpoint" or edit existing endpoint
3. Set the endpoint URL:
   • Development: http://localhost:3000/api/webhooks/polar (use ngrok for local testing)
   • Production: https://yourdomain.com/api/webhooks/polar
4. Copy the Webhook Secret - this is your POLAR_WEBHOOK_SECRET
5. Select the events you want to receive (recommended: all subscription events)
6. Save the endpoint

Add these variables to your .env.local file:

# Polar.sh API
POLAR_ACCESS_TOKEN="your-polar-access-token"

# Polar.sh Webhooks
POLAR_WEBHOOK_SECRET="your-webhook-secret"

# Polar.sh Products (from step 2)
NEXT_PUBLIC_STARTER_TIER="your-product-id"
NEXT_PUBLIC_STARTER_SLUG="your-product-slug"

# Success URL (where users redirect after successful payment)
POLAR_SUCCESS_URL="success"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

Important:

• POLAR_ACCESS_TOKEN comes from "Settings" → "API Keys"
• POLAR_WEBHOOK_SECRET comes from "Settings" → "Webhooks"
• NEXT_PUBLIC_STARTER_TIER is the Product ID from your product
• NEXT_PUBLIC_STARTER_SLUG is the Product Slug from your product
• POLAR_SUCCESS_URL is the relative path where users redirect after checkout

1. Restart your dev server: npm run dev
2. Navigate to /pricing page
3. Click "Get Started" on a plan
4. Complete the checkout flow (use Stripe test cards)
5. Verify webhook events are received (check server logs)
6. Check that subscription status updates in your database

Test Cards (Stripe):

• Success: 4242 4242 4242 4242
• Decline: 4000 0000 0000 0002
• Any future expiry date, any 3-digit CVC

Testing Webhooks Locally: Use ngrok to expose your local server:

ngrok http 3000

Then use the ngrok URL in your Polar webhook endpoint configuration.