Build a subscriptions integration

Create and manage subscriptions to accept recurring payments.

Web

iOS

Android

React Native

Fixed-price subscription page with the Payment Element

Low code

Use this guide to learn how to sell fixed-price subscriptions. You’ll use the Payment Element with Checkout Sessions API to create a custom payment form that you embed in your application.

If you don’t want to build a custom payment form, you can integrate with hosted checkout. For an immersive version of that end-to-end integration guide, see the Billing quickstart.

If you aren’t ready to code an integration, you can set up basic subscriptions manually in the Dashboard. You can also use Payment Links to set up subscriptions without writing any code. Learn more about designing an integration to understand the decisions you need to make and the resources you need.

What you’ll build

This guide shows you how to:

Model your business by building a product catalog.
Build a registration process that creates a customer.
Create subscriptions and collect payment information.
Test and monitor payment and subscription status.
Let customers change their plan or cancel the subscription.

API object definitions

Set up Stripe

Install the Stripe client of your choice:

And then install the Stripe CLI. The CLI provides webhook testing and you can run it to make API calls to Stripe. This guide shows how to use the CLI to set up a pricing model in a later section.

Command Line
Select a languagehomebrew
Install from source
 No results
# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe

# Connect the CLI to your dashboard
stripe login

For additional install options, see Get started with the Stripe CLI.

Create the pricing model
Stripe CLI or Dashboard

Create your products and their prices in the Dashboard or with the Stripe CLI.

This example uses a fixed-price service with two different service-level options: Basic and Premium. For each service-level option, you need to create a product and a recurring price. (If you want to add a one-time charge for something like a setup fee, create a third product with a one-time price. To keep things simple, this example doesn’t include a one-time charge.)

In this example, each product bills at monthly intervals. The price for the Basic product is 5 USD. The price for the Premium product is 15 USD.

Go to the Add a product page and create two products. Add one price for each product, each with a monthly recurring billing period:

Premium product: Premium service with extra features
- Price: Flat rate | 15 USD
Basic product: Basic service with minimum features
- Price: Flat rate | 5 USD

After you create the prices, record the price IDs so you can use them in other steps. Price IDs look like this: price_G0FvDp6vZvdwRZ.

When you’re ready, use the Copy to live mode button at the top right of the page to clone your product from a sandbox to live mode.

Create the Customer
Client and Server

Stripe needs a Customer for each subscription. In your application front end, collect any necessary information from your users and pass it to the back end.

If you need to collect address details, the Address Element enables you to collect a shipping or billing address for your customers. For more information on the Address Element, see the Address Element page.

register.html
<form id="signup-form">
  <label>
    Email
    <input id="email" type="email" placeholder="Email address" value="test@example.com" required />
  </label>

  <button type="submit">
    Register
  </button>
</form>

register.js
const emailInput = document.querySelector('#email');

fetch('/create-customer', {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: emailInput.value,
  }),
}).then(r => r.json());

On the server, create the Stripe Customer object.

Note

Make sure you store the Customer ID to use in the Checkout Session

Create a Checkout Session
Server

On the back end of your application, define an endpoint that creates the session for your front end to call. You’ll need the price ID of the subscription the customer is signing up for—your front end passes this value.

If you created a one-time price in step 2, pass that price ID also. After creating a Checkout Session, make sure you pass the client secret back to the client in the response.

Note

You can use lookup_keys to fetch prices rather than Price IDs. See the sample application for an example.

From your Dashboard, enable the payment methods you want to accept from your customers. Checkout supports several payment methods.

Initialize Checkout
Client

Create a fetchClientSecret function. This function retrieves the client secret from your server and returns a promise that resolves with the client secret. Call initCheckout, passing in fetchClientSecret. initCheckout returns a promise that resolves to a checkout instance.

The checkout object acts as the foundation of your checkout page, and contains data from the Checkout Session and methods to update the Session.

The object returned by checkout.session() contains your pricing information. We recommend reading and displaying the total, and lineItems from the session in your UI.

This lets you turn on new features with minimal code changes. For example, adding manual currency prices requires no UI changes if you display the total.

checkout.js
const fetchClientSecret = () => {
  return fetch('/create-checkout-session', {method: 'POST'})
    .then((response) => response.json())
    .then((json) => json.checkoutSessionClientSecret);
};
stripe.initCheckout({fetchClientSecret})
  .then((checkout) => {
    const checkoutContainer = document.getElementById('checkout-container');
    checkoutContainer.append(JSON.stringify(checkout.lineItems, null, 2));
    checkoutContainer.append(document.createElement('br'));
    checkoutContainer.append(`Total: ${checkout.session().total.total.amount}`);
  });

index.html
<div id="checkout-container"></div>

Collect payment information
Client

Collect payment details on the client with the Payment Element. The Payment Element is a prebuilt UI component that simplifies collecting payment details for a variety of payment methods.

First, create a container DOM element to mount the Payment Element. Then create an instance of the Payment Element using checkout.createPaymentElement and mount it by calling element.mount, providing either a CSS selector or the container DOM element.

index.html
<div id="payment-element"></div>

checkout.js
const paymentElement = checkout.createPaymentElement();
paymentElement.mount('#payment-element');

See the Stripe.js docs to view the supported options.

You can customize the appearance of all Elements by passing elementsOptions.appearance when initializing Checkout on the front end.

Submit the payment
Client-side

Render a Pay button that calls confirm from the checkout instance to submit the payment.

index.html
<button id="pay-button">Pay</button>
<div id="confirm-errors"></div>

checkout.js
stripe.initCheckout({fetchClientSecret}).then((checkout) => {
  const button = document.getElementById('pay-button');
  const errors = document.getElementById('confirm-errors');
  button.addEventListener('click', () => {
    // Clear any validation errors
    errors.textContent = '';

    checkout.confirm().then((result) => {
      if (result.type === 'error') {
        errors.textContent = result.error.message;
      }
    });
  });
});

Listen for webhooks
Server

To complete the integration, you need to process webhooks sent by Stripe. These are events triggered whenever state inside of Stripe changes, such as subscriptions creating new invoices. In your application, set up an HTTP handler to accept a POST request containing the webhook event, and verify the signature of the event:

During development, use the Stripe CLI to observe webhooks and forward them to your application. Run the following in a new terminal while your development app is running:

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

For production, set up a webhook endpoint URL in the Dashboard, or use the Webhook Endpoints API.

You need to listen to a few events to complete the remaining steps in this guide. See Subscription events for more details about subscription-specific webhooks.

Provision access to your service
Client and Server

Now that the subscription is active, give your user access to your service. To do this, listen to the customer.subscription.created, customer.subscription.updated, and customer.subscription.deleted events. These events pass a subscription object that contains a status field indicating whether the subscription is active, past due, or canceled. See the subscription lifecycle for a complete list of statuses.

In your webhook handler:

Verify the subscription status. If it’s active then your user has paid for your product.
Check the product the customer subscribed to and grant access to your service. Checking the product instead of the price gives you more flexibility if you need to change the pricing or billing interval.
Store the product.id, subscription.id and subscription.status in your database along with the customer.id you already saved. Check this record when determining which features to enable for the user in your application.

The state of a subscription might change at any point during its lifetime, even if your application doesn’t directly make any calls to Stripe. For example, a renewal might fail because of an expired credit card, which puts the subscription into a past due state. Or, if you implement the customer portal, a user might cancel their subscription without directly visiting your application. Implementing your handler correctly keeps your application state in sync with Stripe.

Cancel the subscription
Client and Server

It’s common to allow customers to cancel their subscriptions. This example adds a cancellation option to the account settings page.

Sample subscription cancelation interface.

Account settings with the ability to cancel the subscription

script.js
function cancelSubscription(subscriptionId) {
  return fetch('/cancel-subscription', {
    method: 'post',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then(cancelSubscriptionResponse => {
      // Display to the user that the subscription has been canceled.
    });
}

On the back end, define the endpoint for your front end to call.

Your application receives a customer.subscription.deleted event.

After the subscription cancels, update your database to remove the Stripe subscription ID you previously stored, and limit access to your service.

When a subscription cancels, you can’t reactivate it. Instead, collect updated billing information from your customer, update their default payment method, and create a new subscription with their existing customer record.

Test your integration

Test payment methods

Use the following table to test different payment methods and scenarios.

Payment method	Scenario	How to test
BECS Direct Debit	Your customer successfully pays with BECS Direct Debit.	Fill out the form using the account number `900123456` and BSB `000-000`. The confirmed PaymentIntent initially transitions to `processing`, then transitions to the `succeeded` status three minutes later.
BECS Direct Debit	Your customer’s payment fails with an `account_closed` error code.	Fill out the form using the account number `111111113` and BSB `000-000`.
Credit card	The card payment succeeds and doesn’t require authentication.	Fill out the credit card form using the credit card number `4242 4242 4242 4242` with any expiration, CVC, and postal code.
Credit card	The card payment requires authentication.	Fill out the credit card form using the credit card number `4000 0025 0000 3155` with any expiration, CVC, and postal code.
Credit card	The card is declined with a decline code like `insufficient_funds`.	Fill out the credit card form using the credit card number `4000 0000 0000 9995` with any expiration, CVC, and postal code.
SEPA Direct Debit	Your customer successfully pays with SEPA Direct Debit.	Fill out the form using the account number `AT321904300235473204`. The confirmed PaymentIntent initially transitions to processing, then transitions to the succeeded status three minutes later.
SEPA Direct Debit	Your customer’s PaymentIntent status transitions from `processing` to `requires_payment_method`.	Fill out the form using the account number `AT861904300235473202`.

Monitor events

Set up webhooks to listen to subscription change events, such as upgrades and cancellations. Learn more about subscription webhooks. You can view events in the Dashboard or with the Stripe CLI.

For more details, see testing your Billing integration.

OptionalLet customers change their plans
Client and Server

OptionalPreview a price change
Client and Server

OptionalDisplay the customer payment method
Client and Server

Disclose Stripe to your customers

Stripe collects information on customer interactions with Elements to provide services to you, prevent fraud, and improve its services. This includes using cookies and IP addresses to identify which Elements a customer saw during a single checkout session. You’re responsible for disclosing and obtaining all rights and consents necessary for Stripe to use data in these ways. For more information, visit our privacy center.

Build a subscriptions integration

Create and manage subscriptions to accept recurring payments.

What you’ll build

API object definitions

Set up Stripe

Create the pricing modelStripe CLI or Dashboard

Create the CustomerClient and Server

Note

Create a Checkout SessionServer

Note

Initialize CheckoutClient

Collect payment informationClient

Submit the paymentClient-side

Listen for webhooksServer

Provision access to your serviceClient and Server

Cancel the subscriptionClient and Server

Test your integration

Test payment methods

Monitor events

OptionalLet customers change their plansClient and Server

OptionalPreview a price changeClient and Server

OptionalDisplay the customer payment methodClient and Server

Disclose Stripe to your customers

Create the pricing model
Stripe CLI or Dashboard

Create the Customer
Client and Server

Create a Checkout Session
Server

Initialize Checkout
Client

Collect payment information
Client

Submit the payment
Client-side

Listen for webhooks
Server

Provision access to your service
Client and Server

Cancel the subscription
Client and Server

OptionalLet customers change their plans
Client and Server

OptionalPreview a price change
Client and Server

OptionalDisplay the customer payment method
Client and Server