Stripe

Get API keys

After you have created your account for Stripe, you will need to get the API key. You can do this by going to the API page in the dashboard. Here you will find the Secret key and the Publishable key. You will need the Secret key for the integration to work.

For local development, make sure to use Test Mode to not mess with the real transactions.

Set environment variables

You need to set the following environment variables:

STRIPE_SECRET_KEY="" # Your Stripe secret key
STRIPE_WEBHOOK_SECRET="" # The secret key of the webhook you created (see below)

Please do not add the secret keys to the .env file in production. During development, you can place them in .env.local as it's not committed to the repository. In production, you can set them in the environment variables of your hosting provider.

Create products

For your users to choose from the available subscription plans, you need to create those Products first on the Products page. You can create as many products as you want.

Create one product per plan you want to offer. You can add multiple prices within this product to offer multiple models or different billing intervals.

Create a webhook

To sync the current subscription status or checkout conclusion and other information to your database, you need to set up a webhook.

The webhook code comes ready to use with TurboStarter, you just have to create the webhook in the Stripe dashboard and insert the URL for your project.

To configure a new webhook, go to the Webhooks page in the Stripe settings and click the Add endpoint button.

Select the following events:

• For subscriptions:
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
• For one-off payments:
  • checkout.session.completed

To get the URL for the webhook, you can either use a local development URL or the URL of your deployed app:

Local development

There are two ways to test the webhook during local development:

stripe login

STRIPE_WEBHOOK_SECRET=*your-secret-key*

stripe listen --forward-to localhost:3000/api/webhooks/billing

stripe trigger customer.subscription.created

Production deployment

When going to production, you will need to set the webhook URL and the events you want to listen to in Stripe.

The webhook path is /api/webhooks/billing. If your app is hosted at https://myapp.com then you need to enter https://myapp.com/api/webhooks/billing as the URL.

All the relevant events are automatically handled by TurboStarter, so you don't need to do anything else. If you want to handle more events please check Webhooks for more information.

Configure Stripe Customer Portal

Stripe requires you to set up the Customer Portal so that users can manage their billing information, invoices and plan settings from there.

You can do it under the following link.

1. Please make sure to enable the setting that lets users switch plans
2. Configure the behavior of the cancellation according to your needs

Create coupon

First, you'd need to create a coupon on the Coupons page.

You can set there a details of discount such as prices that it should apply to, amount off, duration, max redemptions and more.

Add promotion code

To enable using code during checkout you need to get a promotion code. You can define it on the same page as the coupon and give some user-friendly name to it.

This code will be auto-applied at new checkout sessions.

Configure discount

You need to add also the discount code and details to TurboStarter billing configuration to enable displaying it in the UI, creating checkout sessions with it and calculate prices.

See discounts configuration for more details.