Integrating the customer portal

Learn how to configure the customer portal and make it available to your customers.

Follow these steps to integrate your application with the customer portal to enable your customers to manage their subscriptions and billing details:

Configure the portal’s features and UI.
Implement a redirect to integrate the portal with your application.
Listen to webhooks to receive updates to customers’ subscriptions and payment methods.
Go live to use the portal in your production environment.

Optional Customize portal sessions to enable different features for different customers.

Configure the portal
Dashboard

Prior to integrating the customer portal, you must configure its functionality and branding in the Stripe Dashboard or API. These settings determine the actions that your users can take using the portal. Its features depend on your product and price catalog, so there are different settings for live mode and test mode.

Configure through the Dashboard

Navigate to the portal settings to create the default configuration. This configuration will be used by the portal unless you override it when creating a session.

Setting	Description
Update subscription pricing plans	Allow customers to upgrade and downgrade their subscriptions (customers can preview the changes before confirming them). You can also enable prorations when changes are made.
Update subscription quantities	Allow customers to change their subscription quantities when the subscription’s product is in the product catalog. You can also set minimum and maximum quantity restrictions, disable quantity updates for certain products, and enable prorations when changes are made.
Cancel subscriptions	Allow customers to cancel their subscriptions, immediately or at the end of a billing period. The latter allows customers to reactivate their subscriptions before the end of the period.
Update payment methods	Allow customers to manage their payment methods like adding and removing cards, and setting a new default payment method.
View invoice history	Allow customers to view their invoice history and download invoices.
Update billing information	Allow customers to update their billing information, including email address, phone number, billing address, shipping address, and tax ids.
Apply promotion codes	Allow customers to apply promotion codes when updating a subscription.

Configure through the API Optional

If you’d like to create multiple portal configurations for different sets of customers, or if you are a Connect platform and would like to manage configurations for your connected accounts, you can do so via the API.

Terminal

curl https://api.stripe.com/v1/billing_portal/configurations \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "business_profile[privacy_policy_url]"="https://example.com/privacy" \
  -d "business_profile[terms_of_service_url]"="https://example.com/terms" \
  -d "features[invoice_history][enabled]"=true

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 on which they can update quantities. 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 can only be set on creation in the Dashboard and API.

Limitations

Updating subscriptions in the portal is only supported for charge_automatically subscriptions with a single licensed price. Subscriptions that use any of the following cannot be updated in the portal, but can still be canceled:

Multiple products
Metered billing
Non-card payment methods

Subscriptions attached to schedules cannot be updated or canceled.

Payment method management functionality only supports cards. This section only displays cards, and it is hidden if the customer’s default payment method is not a card.

Previewing and testing

As you configure the settings, you can preview the portal by clicking the Preview button. This launches a read-only version of the portal so you can see how customers would use it to manage subscriptions and billing details.

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

Launching the portal this way is available only in test mode. See the next section for how to integrate the portal into your application.

If previewing and testing in the Dashboard doesn’t work, check your settings and make sure your configuration is saved in test mode and that your customer is also in test mode. Your Dashboard role must also have edit permissions.

The portal is automatically localized for a set of languages. To view a localized version of the portal, set your browser’s default language to the language you’d like to preview.

Which languages are supported by the portal?

Implement a redirect
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, 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>

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.

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 ensure that customers receive only the products or services they are 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.

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

Subscription upgrades and downgrades

Listen for the customer.subscription.updated event and check the subscription.items.data[0].price attribute to find the price the customer is subscribed to. Then, grant access to the new product.

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.

Subscription quantity updates

Listen for the customer.subscription.updated event and check the subscription.items.data[0].quantity attribute to find the quantity the customer is subscribed to. Then, grant access to the new quantity.

Subscription cancellation

Listen to the customer.subscription.deleted event and then remove 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 will be 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.

Payment method updates

Customers can use the portal to add and remove payment methods, and select a new default payment method.

payment_method.attached — Occurs when a customer adds a payment method.
payment_method.detached — Occurs when a customer removes a payment method.
customer.updated — Check 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. Listen to the customer.subscription.updated event and check the subscription’s default_payment_method attribute when this occurs.

Billing information updates

The customer.updated event is sent when customers update their billing information. Use this webhook to update any relevant information in your database. All updates should be treated as billing information changes only. Don’t use the customer billing email address as a login credential.

Listen to the customer.tax_id.created and customer.tax_id.deleted events to receive updates when customers manage their tax IDs. Stripe can validate some types of tax IDs. Listen to the customer.tax_id.updated event to get notified of validation updates. Learn more in the tax IDs guide.

Configuration creations and updates

The billing_portal.configuration.created and the billing_portal.configuration.updated events are sent when a configuration is created or updated. Listen for these webhooks to respond to changes.

Go live

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

Toggle the View test data button off in the Stripe 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.