Stripe customer portal session will not open

What it means in plain English

The customer portal is a Stripe-hosted page where a customer updates a subscription or a card. It does not exist until you configure it. Stripe's integration guide says to define the portal's features in the Dashboard first, separately for sandboxes and for live mode, and then create a portal session from your server. The session's url is what you redirect to. A session that was never configured, or that was configured only in test mode, will not open for a live customer.

Likely causes

• The button calls Stripe from the browser, or it never calls billing_portal/sessions.
• The portal was saved in a sandbox and the live switch is still on View test data. Stripe says those configurations are separate, and a change in one mode does not change the other.
• return_url was omitted. Stripe says it is required when the Dashboard configuration has no default return URL.
• The route creates a session without checking that the signed-in person owns that Stripe customer.

How to fix it, step by step

1. In the Stripe Dashboard, configure the portal for the mode you are using. Stripe says to pick the features, save, and use Preview. Preview is read-only. To try a real session, open a customer and use Actions, then Open customer portal, while the Dashboard is in a sandbox.
2. Add a server endpoint that creates the session with your secret key, the customer id, and a return_url. Stripe's example is POST /v1/billing_portal/sessions. Authenticate the person on your site before you create the session. Redirect the browser to the returned url.
3. For production, turn off View test data, configure the portal again in live mode, and add the live webhook endpoint. Stripe lists customer.subscription.updated and customer.subscription.deleted among the events that tell you the subscription changed.
4. Redeploy the server route. Do not put the secret key in the client.

How to check it worked

• The button lands on a billing.stripe.com portal URL and returns to your return_url.
• A live customer hits the live configuration, not the sandbox one.

Sources

• https://docs.stripe.com/customer-management/integrate-customer-portal (opens in a new tab)
• https://docs.stripe.com/api/customer_portal/sessions/create (opens in a new tab)