Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
How subscriptions work
How to model subscriptions
Get started
Quickstart
Integrate a SaaS business
Embed a pricing table
Design an integration
Build a subscriptions integration
Integrate the customer portal
Migrate subscriptions to Stripe
Billing resources
Coupons
Customers
Subscriptions
Subscription invoices
Manage subscriptions
Change subscriptions
Usage-based billing
Use trial periods
Set payment methods
Subscriptions with multiple products
Set subscription quantities
Subscription webhooks
Schedule subscriptions
Tax
Integrate with Salesforce
Manage recurring revenue
Revenue recognition
Revenue recovery
Subscription metrics
Testing
Test your integration
Test clocks
Strong Customer Authentication (SCA)
Invoices API updates
Testing
No-code options
Billing
·
HomePaymentsSubscriptions

Integrate the customer portal

Learn how to integrate the customer portal.

The customer portal is a Stripe-hosted solution for customer self-serve management. If you’re a Subscriptions user, the portal lets your customers manage their subscriptions (update, cancel, pause, and so on). Invoicing-only users can use the portal to pay an invoice, add a payment method, and more.

Preview the customer portal

Features

When you use the customer portal, you get the following features.

FeatureDescription
Customer managementOffer your customers a self-serve experience to:
  • Update billing information, including their tax IDs
  • Update payment methods
  • Update, cancel, pause, resume, and view subscriptions
  • Pay, download, and view current and past invoices
InteroperabilityUse the portal with other Stripe products:
  • Checkout
  • Connect
  • Invoices
  • Billing
  • Stripe Tax
Localization supportAutomatically localize the portal based on your customers’ preferred language. To view a localized version of the portal, set your browser’s default language to the language you want to preview. See the full list of supported languages.
Customized brandingConfigure the portal to match your branding, including your icon, logo, colors, and business information.
Payment methodsManage payment methods to make it convenient for your customers to pay you. See the full list of supported payment methods. Read the payment methods guide to learn more.

Supported languages

Supported payment methods

Portal sessions

Portal sessions are temporary. New portal sessions expire after a 5 minute period. If a customer uses it within that time period, the session expires within 1 hour of the most recent activity. Each portal session can last up to 2 hours before expiring.

Limitations

The customer portal has the following limitations:

  • If subscriptions use any of the following, customers can only cancel them in the portal (they can’t update such subscriptions):

    • Multiple products
    • Usage-based billing
    • Sending invoices for collection. Read more about the collection_method parameter. If you use the Dashboard to create the subscription, you make this selection in the Payment method section.
    • Unsupported payment methods
  • Customers can’t update or cancel subscriptions that are attached to schedules.

  • Customers that have active subscriptions and have enabled Stripe Tax can’t update their billing or shipping addresses to an unrecognized location—they must provide a valid address.

  • Customers can’t modify a subscription if the new modified price has a different tax behavior than the initial price. Learn more about the tax_behavior parameter and how it relates to subscriptions.

  • The portal doesn’t display the payment method section if the portal doesn’t support the customer’s default payment method.

Set up the portal

First, you need a Stripe account. Register now.

For developers

Get started

With the customer portal, you can provide subscription, billing, and invoicing management to your customers without building it yourself. After you configure and integrate the portal, customers redirect to a co-branded dashboard where they can manage their account based on the functionality you configured.

Follow these steps to integrate your application with the customer portal:

  1. Configure the portal’s features and user interface (UI). You can do this in the Dashboard.
  2. Implement a redirect to integrate the portal with your application.
  3. Listen to webhooks to receive updates to customers’ subscriptions and payment methods.
  4. Go live to use the portal in your production environment.

You can optionally customize portal sessions to enable different features for different customers.

Configure the portal

Before you integrate the customer portal, you must configure its functionality and branding in the Dashboard or API. These settings determine what your users can do with the portal. Its features depend on your product and price catalog, so there are different settings for live and test modes.

If you’re using the customer portal with Stripe Connect, make sure you configure the customer portal for the platform, not a connected account.

Go to the Customer portal settings to create the default configuration. The portal uses this configuration unless you override it when creating a session.

Set a product catalog

If you’re using the customer portal only for invoicing, you don’t need to set a product catalog.

If you allow customers to upgrade, downgrade, or change the quantities of their subscriptions, you must also set a product catalog. This includes the products and prices that your customers can upgrade or downgrade to, as well as the subscriptions they can update quantities on. The portal displays the following attributes of your product catalog:

  • Product name and description—these attributes are editable in the Dashboard and API.
  • Quantity restrictions per product—these attributes are editable in the Dashboard.
  • Price amount, currency, and billing interval—these attributes are immutable and you can only set them when you create them in the Dashboard and API.

Enable tax ID collection

If you use Stripe Tax to automatically collect taxes for subscriptions or invoices, you can let customers set and update their tax IDs in the customer portal. Stripe Billing adds the tax IDs to the customers’ invoices. To enable this, go to the Customer portal settings and toggle on Tax ID. For more information, see how customer tax IDs work with subscriptions and invoices.

Learn how to set up Stripe Tax, collect taxes for recurring payments, and set tax rates for line items and invoices.

Preview and test

As you configure your settings, you can preview the portal by clicking Preview. This launches a read-only version of the portal that lets you see how your customers could manage their subscriptions and billing details.

After saving your settings, you can launch the portal and test it by using a customer in test mode. Navigate to a customer in the Dashboard, click Actions, and then select Open customer portal.

Previewing the portal as a read-only version is only available when your Dashboard is in test mode. If you’re unable to preview and test the portal, check your settings to make sure that your configuration is saved in test mode. For previewing and testing to work, you also need to have edit permissions in the Dashboard.

Implement a redirect on your site
Client-side
Server-side

A portal session is the entry point into the customer portal. It provides a unique, temporary link to the portal. When a customer wants to manage their billing or invoicing, create a new portal session and redirect them to the session’s url.

On your site, add a button that customers can click to enter the portal. Use a POST request to create a portal session:

<form method="POST" action="/create-customer-portal-session"> <button type="submit">Manage billing</button> </form>

No code option

Generate a customer portal login link that you can add to your site or send directly to your customers. They can log in directly to their customer portal with their email address and a one-time passcode. If you’re interested in this feature, reach out to customer-portal-beta@stripe.com.

Next, add an endpoint that creates a portal session and redirects your customers. Make sure to authenticate customers on your site before creating sessions for them. To create a session, you need the customer’s ID and a return_url, which is required if a default return URL isn’t set in the Dashboard configuration.

When you create a portal session, Stripe returns the portal session object, which contains the session’s short-lived URL that your customers use to access the customer portal.

Terminal
curl https://api.stripe.com/v1/billing_portal/sessions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d "customer"="{{CUSTOMER_ID}}" \ -d "return_url"="https://example.com/account"

Listen to webhooks
Server-side

When subscriptions are upgraded, downgraded, or canceled, you need to make sure that customers receive only the products or services they’re actively subscribed to. Stripe sends notifications of these changes to your integration using webhooks. In the Event object, look at the ID for the subscription or the customer to determine which customer the event applies to.

Stripe also sends notifications if an invoice is paid to your integration using webhooks. In the Event object, look at the ID for the invoice or the customer to determine which customer the event applies to.

If you haven’t set up a webhook endpoint with Stripe before, you can use Stripe’s webhooks documentation to get started, and then listen for the events described below.

EventDescription

customer.subscription.updated

Listen to this to monitor subscription upgrades and downgrades. For upgrades, check the subscription.items.data[0].price attribute in the subscription object to find the price the customer is subscribed to. Then, grant access to the new product. For downgrades, check the same attribute and adjust or revoke access as needed.

When a customer uses the portal to upgrade or downgrade a subscription with a trial, the subscription’s trial ends immediately when switching to the new price.

customer.subscription.updatedListen to this to monitor updates to the subscription quantity. When you receive this event, check the subscription.items.data[0].quantity attribute to find the quantity the customer is subscribed to. Then, grant access to the new quantity.

customer.subscription.deleted

Listen to this to monitor subscription cancellations. When you receive this event, revoke the customer’s access to the product. If you configure the portal to cancel subscriptions at the end of a billing period, listen to the customer.subscription.updated event to be notified of cancellations before they occur. If cancel_at_period_end is true, the subscription is canceled at the end of its billing period.

If a customer changes their mind, they can reactivate their subscription prior to the end of the billing period. When they do this, a customer.subscription.updated event is sent. Check that cancel_at_period_end is false to confirm that they reactivated their subscription.

customer.subscription.updatedListen to this for subscriptions that have paused collections. If subscription.pause_collection is empty, it means that the subscription has resumed. Otherwise, the subscription collection is paused and subscription.pause_collection.resumes_at indicates when the subscription is scheduled to resume. subscription.pause_collection.behavior must always be 'void' if the customer paused their subscription in the customer portal.
payment_method.attachedOccurs when a customer adds a payment method.
payment_method.detachedOccurs when a customer removes a payment method.
customer.updatedCheck the invoice_settings.default_payment_method attribute to find the payment method that a customer selected as the new default. If you have subscriptions that override the customer-level default payment method, customers can remove this override. Check the subscription’s default_payment_method attribute when you receive this event to see if the override was removed. Use this webhook to update any relevant information in your database. All updates must be treated as billing information changes only. Don’t use the customer billing email address as a login credential.
customer.tax_id.createdOccurs when customers manage their tax IDs. Stripe can validate some types of tax IDs. Learn more in the tax IDs guide.
customer.tax_id.deletedOccurs when customers manage their tax IDs. Stripe can validate some types of tax IDs. Learn more in the tax IDs guide.
customer.tax_id.updatedListen to this to get validation updates about customer tax IDs. Learn more in the tax IDs guide.
billing_portal.configuration.createdOccurs when a configuration is created.
billing_portal.configuration.updatedOccurs when a configuration is updated.
billing_portal.session.createdOccurs when a portal session is created.

Go live

Make sure to test the portal before enabling it in production. When you’re ready to go live:

When you create a portal session, Stripe returns the portal session object, which contains the session’s short-lived URL that your customers must use to access the customer portal.

  • Turn off View test data in the Dashboard.
  • Configure the portal in live mode.
  • Add your webhooks in live mode.

Stripe maintains two distinct sets of portal configurations: one for live mode and one for test mode. To help you validate your integration, making changes in one mode does not affect your configuration in the other.

OptionalCustomize a portal session
Server-side

Was this page helpful?
Questions? Contact us.
View developer tutorials on YouTube.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Features
Set up the portal
Get started
Configure the portal
Implement a redirect on your site
Listen to webhooks
Go live
Customize a portal session
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to Stripe docs and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$