Skip to main content

Stripe Setup

Complete guide for configuring Stripe with SvelteBolt to handle payments and subscriptions.

Create Stripe Account​

  1. Go to stripe.com
  2. Click Start now
  3. Sign up with your email
  4. Complete account verification (required for live payments)
  5. For development, you can skip verification and use test mode

Get API Keys​

  1. In your Stripe dashboard, ensure you're in Test mode (toggle in top-left)
  2. Go to Developers → API Keys
  3. Copy these values to your .env file: 
    PUBLIC_STRIPE_KEY=pk_test_51ABC123...
    STRIPE_SECRET_KEY=sk_test_51ABC123...

Create Products and Prices​

SvelteBolt includes two subscription plans: Plus and Pro.

You are free to customize these plans or add more as needed.

Create Plus Plan​

  1. Go to Products in Stripe dashboard
  2. Click + Add product
  3. Fill in details:
    • Name: Plus
    • Description: Plus subscription plan
  4. Under Pricing:
    • Price: $9.99 (or your preferred amount)
    • Billing period: Monthly
    • Currency: USD
  5. Click Save product
  6. Copy the Price ID (starts with price_) for later

Create Pro Plan​

  1. Create another product named Pro
  2. Set pricing (e.g., $19.99 monthly)
  3. Copy the Price ID

Add Annual Options (Optional)​

For each product, add yearly pricing:

  1. Click on the product
  2. Click + Add another price
  3. Set Billing period to Yearly
  4. Apply discount (e.g., 20% off monthly rate)
Keep in mind

SvelteBolt automatically gets your products and prices from Stripe, so you don't need to hardcode them in your app. Whenever you create or update products/prices in Stripe, they will be fetched dynamically.

Pricing Component Preview​

Once your Stripe products and prices are configured, they will automatically appear in your SvelteBolt pricing component:

Light Mode Pricing

SvelteBolt Pricing Component - Light Mode

Dark Mode Pricing

SvelteBolt Pricing Component - Dark Mode

The pricing component will automatically:

  • Display your Free tier alongside your Stripe plans
  • Show monthly and yearly billing options
  • Handle the complete checkout flow
  • Update based on your Stripe configuration

Configure Webhooks​

Webhooks are essential to receive live events from Stripe as they happen. They allow your application to respond to events like subscription creation, updates, and payment success/failure and keep your app in sync with Stripe.

Create Webhook Endpoint​

  1. Go to Developers → Webhooks
  2. Click + Add endpoint
  3. Set Endpoint URL:
    • Development: https://dev.yourdomain.com/api/stripe/webhook
    • Production: https://yourdomain.com/api/stripe/webhook
  4. Select events to listen to: 
    customer.subscription.created
    customer.subscription.updated
    customer.subscription.deleted
    invoice.payment_succeeded
    invoice.payment_failed
  5. Click Add endpoint

Get Webhook Secret​

  1. Click on your newly created webhook
  2. Click Reveal signing secret
  3. Copy to your .env file: 
    STRIPE_WEBHOOK_SECRET=whsec_ABC123...

Set Up Local Testing with Stripe CLI​

For local development, use Stripe CLI to forward webhooks:

Install Stripe CLI​

Follow the instructions at Stripe CLI Installation to install the Stripe CLI on your machine.

Forward Webhooks​

  1. Login to Stripe:

    stripe login

  2. Forward webhooks to local server:

    stripe listen --forward-to localhost:5173/api/stripe/webhook

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

    STRIPE_WEBHOOK_SECRET=whsec_ABC123...

Test Payments​

Test Credit Cards​

Use Stripe's test card numbers:

Card NumberDescription
4242424242424242Visa - Success
4000000000000002Visa - Declined
4000002500003155Visa - Requires authentication
  • Expiry: Any future date (e.g., 12/34)
  • CVC: Any 3 digits (e.g., 123)
  • ZIP: Any 5 digits (e.g., 12345)

Testing Flow​

  1. Start your SvelteBolt development server
  2. Navigate to the pricing section
  3. Click on a subscription plan
  4. Use test card details
  5. Complete the checkout process
  6. Verify webhook events in Stripe dashboard
  7. Check subscription status in your app's dashboard

Customer Portal Configuration​

Enable customers to manage their subscriptions:

  1. Go to Settings → Billing → Customer portal
  2. Enable Customer portal
  3. Configure allowed actions:
    • ✅ Update payment methods
    • ✅ Download invoices
    • ✅ Cancel subscriptions
    • ✅ Update billing information
  4. Set Default return URL: https://yourdomain.com/dashboard/settings/billing

Production Setup​

Switch to Live Mode​

  1. Toggle to Live mode in Stripe dashboard
  2. Complete account verification
  3. Update your .env with live keys: 
    PUBLIC_STRIPE_KEY=pk_live_51ABC123...
    STRIPE_SECRET_KEY=sk_live_51ABC123...
  4. Create new webhook for production URL
  5. Update STRIPE_WEBHOOK_SECRET with live webhook secret

Important Production Settings​

  • Enable 3D Secure for better fraud protection
  • Set up tax collection if required
  • Configure receipt emails
  • Set up dispute monitoring

Free Trial Configuration​

SvelteBolt includes built-in support for free trials. You can configure the trial period using the PUBLIC_TRIAL_PERIOD_DAYS environment variable.

How It Works​

  • When set to a positive number (e.g., 7, 14, 30), new subscribers get that many days of free trial
  • When set to 0, the trial period is disabled and users are charged immediately
  • The trial period applies to all subscription plans (Plus and Pro)
  • Users can cancel anytime during the trial without being charged

Configuration​

Add this to your .env file:

# Trial Period Configuration
PUBLIC_TRIAL_PERIOD_DAYS=14  # 14-day free trial
# PUBLIC_TRIAL_PERIOD_DAYS=0  # Disable trial (immediate charge)

Trial Period Display​

When a trial period is configured, the pricing component automatically shows the trial information:

Free Trial Period Display

What happens during trial:

  • Stripe creates a subscription with a trial period
  • No payment is collected initially
  • Users get full access to premium features
  • Automatic billing starts after trial ends
  • Users receive email notifications before trial expiration

Environment Variables Summary​

Your complete Stripe configuration in .env:

# Stripe Configuration
PUBLIC_STRIPE_KEY=pk_test_51ABC123DEF456GHI789...
STRIPE_SECRET_KEY=sk_test_51ABC123DEF456GHI789...
STRIPE_WEBHOOK_SECRET=whsec_ABC123DEF456...

# Trial Period (optional)
PUBLIC_TRIAL_PERIOD_DAYS=14  # Set to 0 to disable trials

Troubleshooting​

Common Issues​

❌ Webhook events not received:

  • Verify webhook URL is accessible
  • Check webhook secret matches
  • Ensure correct events are selected
  • Use stripe listen for local testing

❌ Payment failures:

  • Check API keys are correct
  • Verify you're in the right mode (test/live)
  • Ensure products and prices are active
  • Check browser console for errors

❌ Subscription not updating:

  • Verify webhook endpoint is working
  • Check webhook events include subscription updates
  • Monitor webhook logs in Stripe dashboard

Testing Webhook Delivery​

  1. Go to Developers → Webhooks
  2. Click on your webhook endpoint
  3. Check Recent deliveries
  4. Look for successful 200 responses
  5. If failing, check the error messages

Monitoring​

Stripe Dashboard Sections to Monitor:

  • Payments - Transaction history
  • Subscriptions - Active subscriptions
  • Customers - Customer management
  • Developers → Logs - API call logs
  • Developers → Events - Webhook events

Next Steps​