Deep links in the customer portal
Design streamlined customer flows with the customer portal API.
With the customer portal, you can provide subscription and payment method management to your customers without building it yourself. If you want to streamline customer actions and further customise workflows between your own app and Stripe, you can create a customer portal flow.
Customer portal flows
A flow is a customisable deep link into the customer portal. Portal flows allow you to:
- Deep link directly to the page with the specified action for your customer to complete. Navigational components to access the rest of the customer portal are hidden so the customer can focus on the single action.
- Customise the redirect behaviour after the customer completes the action – redirect them immediately to your own URL, to a hosted confirmation page, or back to the portal homepage.
- Personalise the flow with unique options like pre-filled promotion codes or custom messages.
Flow types
A flow’s type defines what single flow or action your customer will complete. Below are the currently available flow types:
| Flow type | Description | Example |
|---|---|---|
payment_method_update | Use payment_method_update to let your customer add a new payment method. The payment method is set as the customer.invoice_settings.default_payment_method. | Payment method update flow |
subscription_cancel | Use subscription_cancel to let your customer cancel a specific subscription. You can customise whether the subscription cancels immediately or at the end of the period by updating your portal configuration through the API or the Dashboard. | Subscription cancel flow |
subscription_update | Use subscription_update to let your customer select different update options such as upgrading or downgrading to another plan or updating the current plan quantity. You can customise the available plans by updating your portal configuration through the API or the Dashboard. | Subscription plan update flow |
subscription_update_confirm | Use subscription_update_confirm to let your customer confirm a specific update to their subscription. You can use this option when you have your own pricing page but want to offload the work of displaying update details such as upcoming invoice and prorations, handling payment failures, or handling 3D Secure authentication. You can also specify a coupon or promotion code to apply on the subscription update. You could use this for promotional campaigns when you offer a discount for switching to another plan. | Subscription update and confirm flow |
customer_update | Use customer_update to let your Customer update their Billing information, such as their Billing address and Tax ID. | Customer update flow |
Create a flow
Customer portal flows are an Extension to the Customer Portal API. Follow the general guide to integrate the customer portal with the API before using this guide.
To create a flow, specify flow_data when you create a portal session.
Set the type of flow you want your customer to complete. Depending on the flow type, you might need to pass in additional data such as a subscription ID.
Below are examples on how to set up each flow type.
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.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
The portal session url for the response now deep links into the flow you created. Use that URL to redirect customers to the portal flow from your site.
Customise after completion behavior
After your customer successfully completes the flow, they see a localised confirmation page that shows the details of their completed update. You can customise the confirmation message on this page, redirect to a URL of your choice, or redirect them back to the customer portal homepage where their full account details are visible.
To customise this behaviour, set after_completion on flow_data.
The following example lets your customer cancel their subscription, and redirects them back to your site afterward.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
The top level return_url is a link back to your website that the customer can click at any time (if they decide not to cancel, for example). The flow_data[after_completion][redirect][return_url] is a link back to your website after a customer successfully cancels their subscription.