Set up subscriptions with Stripe Billing

This sample shows how to create a customer and subscribe them to a plan with Stripe Billing. For the official documentation for Stripe billing checkout the overview.

	Checkout	Fixed-price-subscriptions with Elements	Usage-based-subscriptions with Elements
Demo	checkout.stripe.dev
Define prices in: CLI, Dashboard, or API Create a price with the Stripe: CLI, Dashboard, or API.	✅	✅	✅
Charge users a fixed price on a recurring basis Create a subscription with a fixed price recurring monthly/yearly/etc.	✅	✅
Charge customers based on their usage. Create a metered subscriptions so you can charge customers based on their usage.	✅		✅
Apple Pay & Google Pay support	✅ Built in, no extra code needed
Coupon support for subscriptions	✅	✅	✅

The hosted demos linked above are running in test mode -- use 4242424242424242 as a test card number with any CVC + future expiration date.

Use the 4000002500003155 test card number to trigger a 3D Secure challenge flow.

Read more about test cards on Stripe at https://stripe.com/docs/testing.

Run the sample locally

This sample can be installed two ways -- Stripe CLI or git clone. The .env configuration will vary depending on which way you install.

Requirements

• A Stripe account: You can sign up for a Stripe account here: https://dashboard.stripe.com/register
• Stripe API Keys: Available in your Stripe dashboard here: https://dashboard.stripe.com/test/apikeys
• 2 Prices: This sample demonstrates two tiers of pricing. You'll need two Price objects on your Stripe account with lookup_key set to sample_basic and sample_premium. See How to create Prices below for more information.

Installing the sample

The Stripe CLI is the fastest way to clone and configure a sample to run locally and is the recommended approach as it will only download the code required for the server language you select. Alternatively, you can download and run directly with this repository.

Option 1: Installing with Stripe CLI

1. If you haven't already installed the CLI, follow the installation steps. The CLI is useful for cloning samples and locally testing webhooks and Stripe integrations.

2. Ensure the CLI is linked to your Stripe account by running:

stripe login

3. Start the sample installer and follow the prompts with:

stripe samples create subscription-use-cases

The CLI will walk you through picking your integration type, server and client languages, and partially configuring your .env file with your Stripe API keys.

4. Move into the server directory:

cd subscription-use-cases/server

5. Open server/.env. The STATIC_DIR value should be ../client when installed using the Stripe CLI.

# Stripe keys
STRIPE_PUBLISHABLE_KEY=pk_12345
STRIPE_SECRET_KEY=sk_12345
STRIPE_WEBHOOK_SECRET=whsec_1234

# Stripe key for React front end
VITE_STRIPE_PUBLISHABLE_KEY=pk_12345

# Environment variables
STATIC_DIR=../client

6. Follow the instructions in server/README.md for how to build and/or run the server.

7. View in the browser: localhost:4242 and test with 4242424242424242.

8. [Optional] Forward webhook events

You can use the Stripe CLI to forward webhook events to your server running locally.

stripe listen --forward-to localhost:4242/webhook

You should see events logged in the console where the CLI is running.

When you are ready to create a live webhook endpoint, follow our guide in the docs on configuring a webhook endpoint in the dashboard.

Option 2: Installing manually

If you do not want to use the Stripe CLI, you can manually clone and configure the sample:

1. Clone the repository

git clone [email protected]:stripe-samples/subscription-use-cases.git
cd subscription-use-cases

2. Configure .env

The .env file contains the API keys and some settings to enable the sample to run with data for your Stripe account.

Copy the .env.example file from the root of the project into a file named .env in the folder of the server language you want to use. For example with node:

cp .env.example fixed-price-subscriptions/server/node/.env
cd fixed-price-subscriptions/server/node

For example with ruby:

cp .env.example fixed-price-subscriptions/server/ruby/.env
cd fixed-price-subscriptions/server/ruby

3. Edit the copied .env and populate all of the variables. For more information see: .env config

# Stripe keys
STRIPE_PUBLISHABLE_KEY=pk_12345
STRIPE_SECRET_KEY=sk_12345
STRIPE_WEBHOOK_SECRET=whsec_1234

# Stripe key for React front end
VITE_STRIPE_PUBLISHABLE_KEY=pk_12345

# Billing variables
BASIC=price_12345...
PREMIUM=price_7890...

# Environment variables
STATIC_DIR=../../client/vanillajs

4. Follow the server instructions on how to run:

Pick the server language you want and follow the instructions in the server folder README on how to run.

cd fixed-price-subscriptions/server/node # there's a README in this folder with instructions
npm install
npm start

5. [Optional] Forward webhook events

You can use the Stripe CLI to forward webhook events to your server running locally.

If you haven't already, install the CLI and link your Stripe account.

stripe listen --forward-to localhost:4242/webhook

You should see events logged in the console where the CLI is running.

When you are ready to create a live webhook endpoint, follow our guide in the docs on configuring a webhook endpoint in the dashboard.

How to create Prices

With Stripe Tax

Stripe Tax lets you calculate and collect sales tax, VAT, and GST with one line of code. This is particularly useful for subscriptions as it automatically calculates tax on recurring invoices.

Implementation details

Before creating a price, make sure you have Stripe Tax set up in the dashboard: Docs - Set up Stripe Tax.

Option 1: With Stripe CLI API calls

Stripe needs to know what kind of product you are selling to calculate the taxes. For this example we will submit a tax code describing what kind of product is used: txcd_10103000 which is 'Software as a service (SaaS) - personal use'. You can find a list of all tax codes here: Available tax codes. If you leave the tax code empty, Stripe will use the default one from your Tax settings.

stripe products create \
 --name="basic" \
 --tax-code="txcd_10103000"

stripe products create \
 --name="premium" \
 --tax-code="txcd_10103000"

From the response, copy the resulting ids of the products, then create a price with tax behavior. Here, tax behavior can be either inclusive (tax is included in the price amount) or exclusive (tax is calculated and added on top of the price). For this example, we are using exclusive.

stripe prices create \
  --unit-amount=500 \
  --currency=usd \
  --tax-behavior=exclusive \
  --product=prod_xxxxx \
  -d "recurring[interval]=month" \
  --lookup-key sample_basic_with_tax

stripe prices create \
  --unit-amount=900 \
  --currency=usd \
  --tax-behavior=exclusive \
  --product=prod_xxxxx \
  -d "recurring[interval]=month" \
  --lookup-key sample_premium_with_tax

Option 2: With cURL

Replace sk_test_xxx with your secret API key:

curl https://api.stripe.com/v1/prices \
  -u sk_test_xxx: \
  -d "unit_amount"=500 \
  -d "currency"=usd \
  -d "tax_behavior"=exclusive \
  -d "recurring[interval]"=month \
  -d "product_data[name]"=basic \
  -d "product_data[tax_code]"=txcd_10103000 \
  -d "lookup_key"=sample_basic_with_tax

curl https://api.stripe.com/v1/prices \
  -u sk_test_xxx: \
  -d "unit_amount"=900 \
  -d "currency"=usd \
  -d "tax_behavior"=exclusive \
  -d "recurring[interval]"=month \
  -d "product_data[name]"=premium \
  -d "product_data[tax_code]"=txcd_10103000 \
  -d "lookup_key"=sample_premium_with_tax

More Information: Docs - Collect taxes for recurring payments

Without Stripe Tax

Option 1: With Stripe CLI Fixtures

Use the seed.json fixture file:

stripe fixtures seed.json

Option 2: With Stripe CLI API calls

Or run the following commands and copy the resulting IDs.

stripe prices create --unit-amount 500 --currency usd -d "recurring[interval]=month" -d "product_data[name]=basic" --lookup-key sample_basic

stripe prices create --unit-amount 900 --currency usd -d "recurring[interval]=month" -d "product_data[name]=premium" --lookup-key sample_premium

Option 3: With cURL

Replace sk_test_xxx with your secret API key:

curl https://api.stripe.com/v1/prices \
  -u sk_test_xxx: \
  -d "unit_amount"=500 \
  -d "currency"=usd \
  -d "recurring[interval]"=month \
  -d "product_data[name]"=basic \
  -d "lookup_key"=sample_basic \

curl https://api.stripe.com/v1/prices \
  -u sk_test_xxx: \
  -d "unit_amount"=900 \
  -d "currency"=usd \
  -d "recurring[interval]"=month \
  -d "product_data[name]"=premium \
  -d "lookup_key"=sample_premium \

.env config

Example configuration file .env.example

• STRIPE_PUBLISHABLE_KEY: Found in the dashboard here: https://dashboard.stripe.com/test/apikeys
• STRIPE_SECRET_KEY: Found in the dashboard here: https://dashboard.stripe.com/test/apikeys
• STRIPE_WEBHOOK_SECRET: If using the Stripe CLI (recommended) run stripe listen --print-secret, otherwise you can find the signing secret for the webhook endpoint in the dashboard by viewing the details of the endpoint here: https://dashboard.stripe.com/test/webhooks.
• STATIC_DIR: The path to the directory containing the client side code. For vanillajs on the client, this will be ../../client/vanillajs.

FAQ

Q: Why did you pick these frameworks?

A: We chose the most minimal framework to convey the key Stripe calls and concepts you need to understand. These demos are meant as an educational tool that helps you roadmap how to integrate Stripe within your own system independent of the framework.

Get support

If you found a bug or want to suggest a new [feature/use case/sample], please file an issue.

If you have questions, comments, or need help with code, we're here to help:

• on Discord
• on Twitter at @StripeDev
• on Stack Overflow at the stripe-payments tag
• by email

Sign up to stay updated with developer news.

Author(s)

• @ctrudeau-stripe
• @suz-stripe
• @dawn-stripe
• @cjavilla-stripe

Contributors

Made with contrib.rocks.