Build a subscriptions integration
Customize logo, images, and colors.
Use prebuilt hosted forms to collect payments and manage subscriptions.
Clone a sample integration from GitHub.
For an immersive version of this guide, see the Billing integration quickstart.
View the demo to see a hosted example.
What you’ll build
This guide describes how to sell fixed-price monthly subscriptions using Stripe Checkout.
By following this guide, you’ll
- Model your business by building a product catalog.
- Add a Checkout session to your site, including a button and success and cancellation pages.
- Monitor subscription events and provision access to your service.
- Set up the customer portal.
- Add a customer portal session to your site, including a button and redirect.
- Let customers manage their subscription through the portal.
After you complete the integration, you can extend it to:
- Display taxes
- Apply discounts
- Offer customers a free trial period
- Add more payment methods
- Integrate the hosted invoice page
- Use Checkout in setup mode
- Set up metered billing, pricing tiers, and usage-based pricing
- Manage prorations
- Allow customers to subscribe to multiple products
Set up Stripe
Install the Stripe client of your choice:
Install the Stripe CLI (optional). The CLI provides webhook testing, and you can run it to create your products and prices.
To run the Stripe CLI, you must also pair it with your Stripe account. Run stripe login
and follow the prompts. For more information, see the Stripe CLI documentation page.
Create the pricing modelDashboard or Stripe CLI
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.
If you offer multiple billing intervals, use Checkout to upsell customers on longer billing intervals and collect more revenue upfront.
For other pricing models, see Billing examples.
Create a Checkout SessionClient and Server
Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session.
<html> <head> <title>Checkout</title> </head> <body> <form action="/create-checkout-session" method="POST"> <!-- Note: If using PHP set the action to /create-checkout-session.php --> <input type="hidden" name="priceId" value="price_G0FvDp6vZvdwRZ" /> <button type="submit">Checkout</button> </form> </body> </html>
On the backend of your application, define an endpoint that creates the session for your frontend to call. You need these values:
- The price ID of the subscription the customer is signing up for—your frontend passes this value
- Your
success_url
, a page on your website that Checkout returns your customer to after they complete the payment - Your
cancel_url
, a page on your website that Checkout returns your customer to if they cancel the payment process
If you created a one-time price in step two, pass that price ID as well. After creating a Checkout Session, redirect your customer to the URL returned in the response.
This example customizes the success_url
by appending the Session ID. For more information about this approach, see the documentation on how to Customize your success page.
From your Dashboard, enable the payment methods you want to accept from your customers. Checkout supports several payment methods.
Provision and monitor subscriptionsServer
After the subscription signup succeeds, the customer returns to your website at the success_url
, which initiates a checkout.session.completed
webhooks. When you receive a checkout.session.completed
event, you can provision the subscription. Continue to provision each month (if billing monthly) as you receive invoice.paid
events. If you receive an invoice.payment_failed
event, notify your customer and send them to the customer portal to update their payment method.
For testing purposes, you can monitor events in the Dashboard. For production, set up a webhook endpoint and subscribe to appropriate event types. If you don’t know your STRIPE_WEBHOOK_SECRET
key, click on the webhook in the Dashboard to view it.
The minimum event types to monitor:
Event name | Description |
---|---|
checkout.session.completed | Sent when a customer clicks the Pay or Subscribe button in Checkout, informing you of a new purchase. |
invoice.paid | Sent each billing interval when a payment succeeds. |
invoice.payment_failed | Sent each billing interval if there is an issue with your customer’s payment method. |
For even more events to monitor, see Subscription webhooks.
Configure the customer portalDashboard
The customer portal lets your customers directly manage their existing subscriptions and invoices.
Use the Dashboard to configure the portal. At a minimum, make sure to configure it so that customers can update their payment methods. See Integrating the customer portal for information about other settings you can configure.
Create a portal SessionServer
Define an endpoint that creates the customer portal session for your frontend to call. Here CUSTOMER_ID
refers to the customer ID created by a Checkout Session that you saved while processing the checkout.session.completed
webhook. You can also set a default redirect link for the portal in the Dashboard.
You can also create the Stripe Customer object separately and pass the customer ID to the initial call to the Checkout Session endpoint and subsequent calls to the customer portal endpoint.
You can also pass an optional return_url
value for the page on your site to redirect your customer to after they finish managing their subscription:
Send customers to the customer portalClient
On your frontend, add a button to the page at the success_url
that provides a link to the customer portal:
<html> <head> <title>Manage Billing</title> </head> <body> <form action="/customer-portal" method="POST"> <!-- Note: If using PHP set the action to /customer-portal.php --> <button type="submit">Manage Billing</button> </form> </body> </html>
After exiting the customer portal, the Customer returns to your website at the return_url
. Continue to monitor webhooks to track the state of the Customer’s subscription.
If you configure the customer portal to allow actions such as canceling a subscription, see Integrating the customer portal for additional events to monitor.