# Deep links in the customer portal Design streamlined customer flows with the customer portal API. If your Connect platform uses [customer-configured Accounts](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), use our [guide](https://docs.stripe.com/connect/use-accounts-as-customers.md) to replace `Customer` and event references in your code with the equivalent Accounts v2 API references. With the [customer portal](https://docs.stripe.com/customer-management.md), 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](https://docs.stripe.com/api/customer_portal/sessions/object.md#portal_session_object-flow). ## Customer portal flows A *flow* is a customisable deep link into the customer portal. Portal flows allow you to: 1. 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. 1. 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. 1. Personalise the flow with unique options like pre-filled promotion codes or custom messages. ### Flow types A flow’s [type](https://docs.stripe.com/api/customer_portal/sessions/create.md#create_portal_session-flow_data-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`. | ![Example of payment method update flow](https://b.stripecdn.com/docs-statics-srv/assets/payment_method_update.6f92b4642ce28020952f263360c83014.png) 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](https://docs.stripe.com/api/customer_portal/configurations/object.md#portal_configuration_object-features-subscription_cancel-mode) or the [Dashboard](https://dashboard.stripe.com/test/settings/billing/portal). | ![Example of subscription cancel flow](https://b.stripecdn.com/docs-statics-srv/assets/subscription_cancel.6943958d0358b97241a1f4d2703d3bfb.png) 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](https://docs.stripe.com/api/customer_portal/configurations/object.md#portal_configuration_object-features-subscription_update-products) or the [Dashboard](https://dashboard.stripe.com/test/settings/billing/portal). | ![Example of subscription update flow](https://b.stripecdn.com/docs-statics-srv/assets/subscription_update.8426206cdf98ba10d04680b782644b67.png) Subscription 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](https://docs.stripe.com/payments/3d-secure.md). 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. | ![Example of subscription update confirm flow](https://b.stripecdn.com/docs-statics-srv/assets/subscription_update_confirm.5a06b658cc8a15971fdfae54fc7708da.png) Subscription update confirm flow | ## Create a flow > Customer portal flows are an extension to the [customer portal API](https://docs.stripe.com/api/customer_portal/sessions/create.md). First follow the general guide to [integrate the customer portal with the API](https://docs.stripe.com/customer-management/integrate-customer-portal.md) before using this guide. To create a flow, specify [flow_data](https://docs.stripe.com/api/customer_portal/sessions/create.md#create_portal_session-flow_data) when you create a portal session. Set the [type](https://docs.stripe.com/api/customer_portal/sessions/create.md#create_portal_session-flow_data-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. #### Payment method update ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ --data-urlencode return_url="https://example.com/account/overview" \ -d "flow_data[type]"=payment_method_update ``` #### Subscription cancel Pass in the `subscription` to cancel in `subscription_cancel[subscription]`. ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ --data-urlencode return_url="https://example.com/account/overview" \ -d "flow_data[type]"=subscription_cancel \ -d "flow_data[subscription_cancel][subscription]"="{{SUBSCRIPTION_ID}}" ``` #### Subscription update Pass in the `subscription` to update in `subscription_update[subscription]`. [Set up your portal configuration](https://docs.stripe.com/customer-management/integrate-customer-portal.md#configure) to configure what products and prices are shown on the page as possible update options. ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ --data-urlencode return_url="https://example.com/account/overview" \ -d "flow_data[type]"=subscription_update \ -d "flow_data[subscription_update][subscription]"="{{SUBSCRIPTION_ID}}" ``` #### Subscription update confirm Pass in the `subscription` to update in `subscription_update_confirm[subscription]`. You must also specify what to update on the subscription’s items by passing in an array of `items` to `subscription_update_confirm[items]`. First, retrieve the current subscription’s `items` by fetching the `subscription` object and checking [items.data](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-items-data). Then, get the `id` of the subscription item to update and pass it into the `subscription_update_confirm[items]` array. You can then specify a new `price` or `quantity` on the item for your customer to confirm. Currently, only one item can be specified and subscriptions with multiple items can’t be updated. ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ --data-urlencode return_url="https://example.com/account/overview" \ -d "flow_data[type]"=subscription_update_confirm \ -d "flow_data[subscription_update_confirm][subscription]"="{{SUBSCRIPTION_ID}}" \ -d "flow_data[subscription_update_confirm][items][0][id]"="{{SUBSCRIPTIONITEM_ID}}" \ -d "flow_data[subscription_update_confirm][items][0][quantity]"=1 \ -d "flow_data[subscription_update_confirm][items][0][price]"="{{PRICE_ID}}" \ -d "flow_data[subscription_update_confirm][discounts][0][coupon]"="{{COUPON_ID}}" ``` 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](https://docs.stripe.com/api/customer_portal/sessions/create.md#create_portal_session-flow_data-after_completion) on `flow_data`. The following example lets your customer cancel their subscription, and redirect back to your own site afterwards: ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ --data-urlencode return_url="https://example.com/account/overview" \ -d "flow_data[type]"=subscription_cancel \ -d "flow_data[subscription_cancel][subscription]"="{{SUBSCRIPTION_ID}}" \ -d "flow_data[after_completion][type]"=redirect \ --data-urlencode "flow_data[after_completion][redirect][return_url]"="https://example.com/account/subscription_canceled" ``` > 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.