Get NextJet
PaymentsStripe

Stripe

Learn how to configure subscription based Stripe payments for local development.

Getting started

Create an account

Create an account and login on Stripe.

Activate test mode

Activate test mode at the top right corner of the dashboard.

Get the API keys

Click on the Developers tab and then click on the API keys tab.

Copy the Publishable key and paste it beside the STRIPE_PUBLISHABLE_KEY in the .env.

Copy the Secret key and paste it beside the STRIPE_SECRET_KEY in the .env.

Install the Stripe CLI

Follow the instructions on the Stripe CLI page to install the Stripe CLI.

The Stripe CLI is needed to test the stripe webhooks locally. Stripe sends events to the webhook listener whenever there is a change in the subscription. Since we are running the app locally, we need a way to receive these events. That's where the webhook listener comes in.

Run the following command on the root of the project to start the webhook listener:

pnpm stripe

In the terminal output, you will see a webhook signing secret. Copy this secret and paste it beside the STRIPE_WEBHOOKS_SECRET in the .env.

Make sure to keep the webhook listener running while developing locally.

Create the Subscription Plans

I have pre-configured three plans in the project:

  • Basic
  • Pro
  • Premium

with the following lookup keys:

  • BASIC_MONTHLY and BASIC_YEARLY
  • PRO_MONTHLY and PRO_YEARLY
  • PREMIUM_MONTHLY and PREMIUM_YEARLY

You can customize everything as you see fit, reducing or increasing the number of plans, and even changing the names.

You can find the subscription plan configuration object in the packages/utils/src/constants/subscriptionPlans.ts file.

Create a product

Click on Product catalog on the left sidebar and then click on Add product.

Fill in the product details

  • Fill in the name (e.g. Basic, Pro, Premium)
  • Provide a description
  • Upload an image
  • Select recurring
  • Enter the amount and currency
  • Choose monthly as the billing period

Add lookup keys

Click on More pricing options.

The lookup key is used to identify the plan in the codebase. You can use any key you want, but remember to update the subscriptionPlans.ts configuration object with the new lookup key.

In my case I will use BASIC_MONTHLY.

Click on Next.

Click on Add another price.

Change the billing period to Yearly and enter the new pricing amount.

In the lookup key, I will use BASIC_YEARLY.

Click on Next and then Add product.

If you decide to use another lookup key, make sure to update the subscriptionPlans.ts configuration object with the new lookup key.

Repeat the same process for the other plans

If you want to add more plans, repeat the same process for the other plans.

Add the plans to the configuration object

Open the packages/utils/src/constants/subscriptionPlans.ts file.

Update every plan with your desired name, tagline, price, lookup keys, features and color to match the plans you created in the Stripe dashboard.

This will update the pricing plan on the marketing site as well as the billing page in the app, and allow users to subscribe to the plans you created.

packages/utils/src/constants/subscriptionPlans.ts
export const SUBSCRIPTION_PLANS: SubscriptionPlan[] = [
  {
    name: SubscriptionPlanName.BASIC,,
    tagline: "For hobby & side projects",
    price: { monthly: 9, yearly: 7 },
    lookupKeys: {
      monthly: "BASIC_MONTHLY",
      yearly: "BASIC_YEARLY",
    },
    features: [
      { name: "Feature 1", included: true },
      { name: "Feature 2", included: true },
      { name: "Feature 3", included: true },
      { name: "Feature 4", included: false },
      { name: "Feature 5", included: false },
      { name: "Feature 6", included: false },
    ],
    color: "bg-primary",
    buttonClassName: "w-full font-bold",
  },
  {
    name: SubscriptionPlanName.PRO,
    tagline: "For startups & small businesses",
    price: { monthly: 24, yearly: 19 },
    lookupKeys: {
      monthly: "PRO_MONTHLY",
      yearly: "PRO_YEARLY",
    },
    features: [
      { name: "Feature 1", included: true },
      { name: "Feature 2", included: true },
      { name: "Feature 3", included: true },
      { name: "Feature 4", included: true },
      { name: "Feature 5", included: true },
      { name: "Feature 6", included: false },
    ],
    color: "bg-purple-400",
    buttonClassName: "w-full bg-purple-400 font-bold hover:bg-purple-400/75",
  },
  {
    name: SubscriptionPlanName.PREMIUM,
    tagline: "For larger teams with increased usage",
    price: { monthly: 49, yearly: 39 },
    lookupKeys: {
      monthly: "PREMIUM_MONTHLY",
      yearly: "PREMIUM_YEARLY",
    },
    features: [
      { name: "Feature 1", included: true },
      { name: "Feature 2", included: true },
      { name: "Feature 3", included: true },
      { name: "Feature 4", included: true },
      { name: "Feature 5", included: true },
      { name: "Feature 6", included: true },
    ],
    color: "bg-blue-400",
    buttonClassName: "w-full bg-blue-400 font-bold hover:bg-blue-400/75",
  },
] as const

Configure the Customer Portal

The customers portal allows your customers to manage their subscriptions and can be accessed through the billing page in your app. However, we need to activate it first in the Stripe dashboard.

Setup the customer portal

Click on the settings icon in the top right corner, then click on Settings.

Click on Billing and then click on Customer portal.

Click on the Activate test link button.

Go to Cancellations and make sure Cancel subscriptions is checked.

Go to Subscriptions and check customers can switch plans. Add all the products/plans you have created.

Fill in the rest of the options as you see fit and click on Save changes.

Limit customers to one subscription

Go back to the Settings page again.

Click on Payments and then check the Limit customers to 1 subscription.

Click on Save.

Test the integration

You can now test the integration by subscribing to a plan and checking if the subscription is created in the Stripe dashboard.

Run the app

In the root of your project, run the following commands:

pnpm dev

and run the stripe CLI webhook listener in another terminal:

pnpm stripe

Navigate to http://localhost:3000 in your browser and login using any provider.

Subscribe to a plan

Complete the onboarding flow, choose a plan and it will create a free trial subscription in the Stripe dashboard.

Check the Stripe dashboard

Go to the Stripe dashboard and click on Billing and then Subscriptions.

You should see the subscription you just created.

Check the customer portal

Go to the billing page in the app and click on the Manage subscription button.

You should see the customer portal where you can manage your subscription.

If you want to cancel/upgrade/downgrade your plan, you can do so here.

You can use the test card number 4242 4242 4242 4242 with any future expiration date and any CVC code to test the payment functionality.

Production Configuration

In the Stripe deployment section, I will walk you through the steps to configure Stripe for production.

Last updated on