Integrate the customer portal with the API
Learn how to integrate the customer portal using the Stripe API.
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.
To integrate your application with the customer portal:
- Configure the portal’s features and user interface (UI). You can do this in the Dashboard.
- Implement a redirect to integrate the portal with your application.
- Listen to webhooks to receive updates to customers’ subscriptions and payment methods.
- Launch the portal in your production environment.
You can optionally customize portal sessions to enable different features for different customers.
Use the Accounts v2 API to represent customers
The Accounts v2 API is generally available for Connect users, and in public preview for other Stripe users. If you’re part of the Accounts v2 preview, you need to specify a preview version in your code.
To join the Accounts v2 preview, go to Account previews and features in your Dashboard and enable Reusable payment methods for Global Payouts.
For most use cases, we recommend modelling your customers as customer-configured Account objects instead of using Customer objects.
Configure the portal
First, you need to register for a Stripe account.
Before you integrate the customer portal, use the Dashboard to define what your users can do with the portal. Choose your settings for sandboxes and live mode, based on your product and price catalog.
Common mistake
If you’re using the customer portal with Stripe Connect, make sure you configure the customer portal for the platform, not a connected account.
If you want to create multiple portal configurations for different sets of customers (or if you’re a Connect platform and want to manage configurations for your connected accounts), you can do so using the API:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Set a product catalogue
If you allow customers to upgrade, downgrade, or change the quantities of their subscriptions, you must also set a product catalogue. This includes the products and prices that your customers can upgrade or downgrade to, and the subscriptions they can update quantities on. See how to create a product for more details about creating products and prices. If you’re using the customer portal for invoicing only, you don’t need to set a product catalogue.
The portal displays the following attributes of your product catalogue:
- 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 fixed, 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 allow customers to set their tax IDs, 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, collect taxes in your custom payment flows and set tax rates for line items and invoices.
Preview and test
As you configure your settings, click Preview to preview the portal. This launches a read-only version of the portal that lets you see how your customers might manage their subscriptions and billing details.
After saving your settings, you can launch the portal and test it by using a customer in a sandbox. Go to a customer in the Dashboard, click Actions and then select Open customer portal.
You can only preview the portal as a read-only version when your Dashboard is in a sandbox. If you can’t preview and test the portal, check your settings to make sure that your configuration is saved in a sandbox. 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>
Next, add an endpoint that creates a portal session and redirects your customers. Be 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.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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.
When your customers update their billing information in the customer portal, it’s important to update your customer records. Listen for changes using the customer.updated or v2.core.account[configuration.customer].updated webhook.
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.
| Event | Description |
|---|---|
| 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.updated | Listen 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. For flexible billing mode subscriptions, if cancel_at is not null, the subscription is cancelled at the end of its billing period. For classic billing mode subscriptions, check that cancel_at_period_end is true. 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. For flexible billing mode subscriptions, check that cancel_at is null to confirm reactivation. For classic billing mode, check that cancel_at_period_end is false. |
| payment_method.attached | Occurs when a customer adds a payment method. |
| payment_method.detached | Occurs when a customer removes a payment method. |
| customer.updated | Occurs when a Customer object is updated. Check the invoice_settings.default_payment_method attribute to find the payment method that the 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. |
| v2.core.account[configuration.customer].updated | Occurs when a customer-configured Account ’s customer configuration is updated. Check the configuration.customer.billing.default_payment_method attribute to find the payment method that the 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.created | Occurs when customers manage their tax IDs. Stripe can validate some types of tax IDs. Learn more in the tax IDs guide. |
| customer.tax_id.deleted | Occurs when customers manage their tax IDs. Stripe can validate some types of tax IDs. Learn more in the tax IDs guide. |
| customer.tax_id.updated | Listen to this to get validation updates about customer tax IDs. Learn more in the tax IDs guide. |
| billing_portal.configuration.created | Occurs when a configuration is created. |
| billing_portal.configuration.updated | Occurs when a configuration is updated. |
| billing_portal.session.created | Occurs when a portal session is created. |
Launch the portal
Make sure to test the portal before enabling it in production.
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. You can also create one shareable link for each configuration of the portal with the login_page parameter.
- Turn off View test data in the Dashboard.
- Configure the portal in live mode.
- Add your webhooks in live mode.
Stripe maintains multiple distinct sets of portal configurations: one for live mode and one for each sandbox. To help you validate your integration, making changes in one mode doesn’t affect your configuration in the other.