Customer Portal

The Customer Portal is Stripe's hosted self-serve page. Your customer clicks "Manage billing" → they're on stripe.com (well, billing.stripe.com), updating their card, swapping plans, downloading invoices. You wire a button and a return URL. That's it.

Step 1: Enable it

// payments.config.ts
customerPortal: { enabled: true },

Step 2: Configure what shows up

Open dashboard.stripe.com → Settings → Billing → Customer portal. Toggle which features customers can use: cancel, change plan, update payment method, download invoices, etc. The portal honors these settings — you don't write code to gate features.

Step 3: Drop in the button

import { CustomerPortalButton } from "@/components/checkout/CustomerPortalButton";

<CustomerPortalButton
  customerId="cus_xxx"           // the Stripe Customer ID
  returnPath="/dashboard"        // where to land after closing the portal
  variant="outline"
>
  Manage Subscription
</CustomerPortalButton>

Where does the Customer ID come from?

Stripe creates a Customer the first time a user checks out. The ID arrives on the session object — you persist it in your own DB linked to your user. Subsequent portal calls look it up from there. This template doesn't include a DB layer (intentional — bring your own), but the bridge point is the webhook handler.

// In your onCheckoutSessionCompleted handler:
const customerId = getCustomerId(session.customer); // "cus_xxx"
await db.users.update(userId, { stripeCustomerId: customerId });

// Later, when rendering a settings page:
<CustomerPortalButton customerId={user.stripeCustomerId!} />

Return path — and the open-redirect plug

returnPath is the URL the portal sends users back to. Our schema in src/lib/validation.ts requires it to start with / and match a strict regex. You can't pass a full URL — that prevents an attacker from rewriting the button's returnPath to redirect off-domain.