# 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.