Stripe customer portal: self-serve billing without building it

Stripe customer portal: the billing settings page you do not build

Every subscription product needs a "manage my subscription" page. Building it yourself means rebuilding plan changes, payment method updates, and cancellation flows with all their edge cases. The customer portal is Stripe's hosted version. Use it.

The basics

1. Create a portal session: POST /v1/billing_portal/sessions with the customer ID and a return_url pointing back to your app. The response url is a one-time link; redirect the customer to it.
2. Sessions are short-lived and single-customer. Create one per visit, server-side, for the logged-in customer. Never expose one customer's session URL to another.
3. Configure what customers can do in the Dashboard's portal settings (or pass a configuration ID): allow plan changes, payment method updates, cancellation with reasons, invoice history.

Deep links

• Pass flow_data when creating the session to drop the customer directly into a specific flow, for example subscription update or cancellation, instead of the portal homepage.
• Use deep links from your app's UI where the intent is already known ("Change plan" goes straight to the plan-change flow).

Rules

• The portal handles the Stripe side; your app still needs to react to the resulting webhooks (customer.subscription.updated, customer.subscription.deleted). The portal does not call your code.
• Test the cancellation flow end to end. The most common bug is the app not handling customer.subscription.deleted because "we tested upgrades, not cancels."
• Do not build a custom billing settings page until the portal demonstrably cannot do what you need. It covers the 90 percent case.

Stripe's API reference documents POST /v1/billingportal/sessions with customer, returnurl, optional configuration, and flow_data for deep links. The portal deep-links doc describes dropping customers directly into specific flows. Verified against live docs 2026-09-26.