From 88bbd119be917909e94acc41c9cbb82588330b16 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Wed, 5 Aug 2026 22:30:33 -0400
Subject: [PATCH 01/13] feat: add pymthouse plans list + subscribe checkout on
 Usage

Wire BFF routes and PlansPanel through builder-sdk createBillingCheckout
so dashboard can exercise end-user checkout against pymthouse before NaaP.
---
 .env.example                           |   2 +-
 app/api/pymthouse/plans/route.ts       |  22 +++++
 app/api/pymthouse/subscribe/route.ts   |  54 ++++++++++++
 components/dashboard/PlansPanel.tsx    | 114 +++++++++++++++++++++++++
 components/dashboard/UsageView.tsx     |   3 +
 lib/dashboard/pymthouse-billing-bff.ts |  72 ++++++++++++++++
 lib/dashboard/useBillingPlans.ts       |  76 +++++++++++++++++
 package.json                           |   7 +-
 pnpm-lock.yaml                         |  11 +--
 9 files changed, 354 insertions(+), 7 deletions(-)
 create mode 100644 app/api/pymthouse/plans/route.ts
 create mode 100644 app/api/pymthouse/subscribe/route.ts
 create mode 100644 components/dashboard/PlansPanel.tsx
 create mode 100644 lib/dashboard/pymthouse-billing-bff.ts
 create mode 100644 lib/dashboard/useBillingPlans.ts

diff --git a/.env.example b/.env.example
index 920b0b8..83bf232 100644
--- a/.env.example
+++ b/.env.example
@@ -6,7 +6,7 @@ THEGRAPH_API_KEY=
 # Aliases: DISCOVERY_URL, LIVEPEER_DISCOVERY_SERVICE_URL
 DISCOVERY_SERVICE_URL=https://discovery-service-production-8955.up.railway.app/v1/discovery/raw
 
-# PymtHouse (usage + API keys + signer sessions)
+# PymtHouse (usage + API keys + signer sessions + plans/subscribe)
 # Production:
 PYMTHOUSE_ISSUER_URL=https://pymthouse.com/api/v1/oidc
 # Local pymthouse: http://localhost:3001/api/v1/oidc
diff --git a/app/api/pymthouse/plans/route.ts b/app/api/pymthouse/plans/route.ts
new file mode 100644
index 0000000..dcfd803
--- /dev/null
+++ b/app/api/pymthouse/plans/route.ts
@@ -0,0 +1,22 @@
+import { NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+import { listDashboardBillingPlans } from "@/lib/dashboard/pymthouse-billing-bff";
+
+export const runtime = "nodejs";
+
+export async function GET() {
+  try {
+    const plans = await listDashboardBillingPlans();
+    return NextResponse.json({ plans });
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status },
+      );
+    }
+    const message =
+      error instanceof Error ? error.message : "Failed to list billing plans";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
diff --git a/app/api/pymthouse/subscribe/route.ts b/app/api/pymthouse/subscribe/route.ts
new file mode 100644
index 0000000..2eacea1
--- /dev/null
+++ b/app/api/pymthouse/subscribe/route.ts
@@ -0,0 +1,54 @@
+import { NextRequest, NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+import { startDashboardBillingCheckout } from "@/lib/dashboard/pymthouse-billing-bff";
+
+export const runtime = "nodejs";
+
+export async function POST(request: NextRequest) {
+  let body: {
+    planId?: string;
+    externalUserId?: string;
+    successUrl?: string;
+    cancelUrl?: string;
+  };
+  try {
+    body = (await request.json()) as typeof body;
+  } catch {
+    return NextResponse.json({ error: "invalid_json" }, { status: 400 });
+  }
+
+  const planId = body.planId?.trim();
+  const externalUserId = body.externalUserId?.trim();
+  if (!planId || !externalUserId) {
+    return NextResponse.json(
+      { error: "planId and externalUserId are required" },
+      { status: 400 },
+    );
+  }
+
+  const origin = request.nextUrl.origin;
+  const successUrl =
+    body.successUrl?.trim() || `${origin}/usage?checkout=success`;
+  const cancelUrl =
+    body.cancelUrl?.trim() || `${origin}/usage?checkout=cancel`;
+
+  try {
+    const result = await startDashboardBillingCheckout({
+      planId,
+      externalUserId,
+      successUrl,
+      cancelUrl,
+    });
+    return NextResponse.json(result);
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status },
+      );
+    }
+    const message =
+      error instanceof Error ? error.message : "Failed to start checkout";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
diff --git a/components/dashboard/PlansPanel.tsx b/components/dashboard/PlansPanel.tsx
new file mode 100644
index 0000000..6834997
--- /dev/null
+++ b/components/dashboard/PlansPanel.tsx
@@ -0,0 +1,114 @@
+"use client";
+
+import { useState } from "react";
+import Button from "@/components/design-system/Button";
+import { useBillingPlans } from "@/lib/dashboard/useBillingPlans";
+
+function formatPrice(amount: string, currency: string, cycle: string | null): string {
+  const n = Number(amount);
+  const money = Number.isFinite(n)
+    ? new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency: currency || "USD",
+      }).format(n)
+    : amount;
+  if (!cycle) return money;
+  const c = cycle.toLowerCase();
+  if (c === "monthly" || c === "month") return `${money}/mo`;
+  if (c === "yearly" || c === "year" || c === "annual") return `${money}/yr`;
+  return `${money} · ${cycle}`;
+}
+
+export default function PlansPanel({
+  externalUserId,
+}: {
+  externalUserId: string | undefined;
+}) {
+  const { state, reload, subscribe } = useBillingPlans();
+  const [busyPlanId, setBusyPlanId] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  async function onSubscribe(planId: string) {
+    if (!externalUserId?.trim()) {
+      setError("Sign in to subscribe.");
+      return;
+    }
+    setError(null);
+    setBusyPlanId(planId);
+    try {
+      const { checkoutUrl } = await subscribe({
+        planId,
+        externalUserId: externalUserId.trim(),
+      });
+      window.location.assign(checkoutUrl);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Checkout failed");
+      setBusyPlanId(null);
+    }
+  }
+
+  if (state.status === "loading" || state.status === "idle") {
+    return (
+      <div className="mt-4 animate-pulse rounded-md border border-hairline bg-dark-lighter px-4 py-6">
+        <div className="h-4 w-40 rounded bg-white/5" />
+        <div className="mt-3 h-16 rounded bg-white/5" />
+      </div>
+    );
+  }
+
+  if (state.status === "error") {
+    return (
+      <div className="mt-4 rounded-md border border-hairline bg-dark-lighter px-4 py-4">
+        <p className="text-sm text-fg-muted">Could not load plans.</p>
+        <p className="mt-1 font-mono text-xs text-fg-faint">{state.message}</p>
+        <Button className="mt-3" variant="secondary" size="sm" onClick={() => void reload()}>
+          Retry
+        </Button>
+      </div>
+    );
+  }
+
+  if (state.plans.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="mt-4 overflow-hidden rounded-md border border-hairline bg-dark-lighter shadow-card">
+      <div className="border-b border-hairline px-4 py-3.5">
+        <p className="text-[17px] font-bold text-fg">Plans</p>
+        <p className="mt-0.5 text-[12px] text-fg-muted">
+          Subscribe via PymtHouse → Stripe Checkout
+        </p>
+      </div>
+      <ul className="divide-y divide-hairline">
+        {state.plans.map((plan) => (
+          <li
+            key={plan.id}
+            className="flex flex-wrap items-center justify-between gap-3 px-4 py-3"
+          >
+            <div>
+              <p className="text-sm font-semibold text-fg">{plan.name || plan.id}</p>
+              <p className="mt-0.5 font-mono text-[11px] text-fg-faint">
+                {formatPrice(plan.priceAmount, plan.priceCurrency, plan.billingCycle)}
+                {plan.capabilityCount > 0
+                  ? ` · ${plan.capabilityCount} capabilities`
+                  : ""}
+              </p>
+            </div>
+            <Button
+              variant="primary"
+              size="sm"
+              disabled={!externalUserId || busyPlanId === plan.id}
+              onClick={() => void onSubscribe(plan.id)}
+            >
+              {busyPlanId === plan.id ? "Redirecting…" : "Subscribe"}
+            </Button>
+          </li>
+        ))}
+      </ul>
+      {error ? (
+        <p className="border-t border-hairline px-4 py-2 text-xs text-rose-400">{error}</p>
+      ) : null}
+    </div>
+  );
+}
diff --git a/components/dashboard/UsageView.tsx b/components/dashboard/UsageView.tsx
index 182a04d..aab3b9c 100644
--- a/components/dashboard/UsageView.tsx
+++ b/components/dashboard/UsageView.tsx
@@ -14,6 +14,7 @@ import {
   type UsageCapabilityRow,
 } from "@/lib/dashboard/usage-capability-display";
 import DashboardPageSkeleton from "@/components/dashboard/DashboardPageSkeleton";
+import PlansPanel from "@/components/dashboard/PlansPanel";
 
 const PERIOD_DAYS = 30;
 
@@ -288,6 +289,8 @@ export default function UsageView() {
         resetsAt={resetsAt}
       />
 
+      <PlansPanel externalUserId={externalUserId} />
+
       <div className="mt-4 overflow-hidden rounded-md border border-hairline bg-dark-lighter shadow-card">
         <div className="flex flex-wrap items-start justify-between gap-3 border-b border-hairline px-4 py-3.5">
           <div>
diff --git a/lib/dashboard/pymthouse-billing-bff.ts b/lib/dashboard/pymthouse-billing-bff.ts
new file mode 100644
index 0000000..fa4ae87
--- /dev/null
+++ b/lib/dashboard/pymthouse-billing-bff.ts
@@ -0,0 +1,72 @@
+import {
+  PmtHouseError,
+  type BillingProduct,
+  type CreateBillingCheckoutResult,
+} from "@pymthouse/builder-sdk";
+import { createPmtHouseClientForPublicApp } from "@/lib/dashboard/pymthouse-bff";
+
+function readPublicClientId(): string {
+  const id =
+    process.env.PYMTHOUSE_PUBLIC_CLIENT_ID?.trim() ||
+    process.env.DASHBOARD_DEVICE_PUBLIC_CLIENT_ID?.trim();
+  if (!id) {
+    throw new PmtHouseError(
+      "PYMTHOUSE_PUBLIC_CLIENT_ID (or DASHBOARD_DEVICE_PUBLIC_CLIENT_ID) is required",
+      { status: 503, code: "pymthouse_required" },
+    );
+  }
+  return id;
+}
+
+export type DashboardBillingPlan = {
+  id: string;
+  name: string;
+  type: string;
+  status: string;
+  priceAmount: string;
+  priceCurrency: string;
+  billingCycle: string | null;
+  capabilityCount: number;
+};
+
+function mapProduct(product: BillingProduct): DashboardBillingPlan {
+  return {
+    id: product.id,
+    name: product.name,
+    type: product.type,
+    status: product.status,
+    priceAmount: product.priceAmount,
+    priceCurrency: product.priceCurrency,
+    billingCycle: product.allowance?.billingCycle ?? null,
+    capabilityCount: product.capabilities?.length ?? 0,
+  };
+}
+
+/** Active (non-starter / non-network-default) products available for subscribe. */
+export async function listDashboardBillingPlans(): Promise<DashboardBillingPlan[]> {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  const { products } = await client.listBillingProducts();
+  return (products ?? [])
+    .filter(
+      (p) =>
+        p.status === "active" &&
+        !p.isNetworkDefault &&
+        !p.isStarterDefault,
+    )
+    .map(mapProduct);
+}
+
+export async function startDashboardBillingCheckout(input: {
+  planId: string;
+  externalUserId: string;
+  successUrl?: string;
+  cancelUrl?: string;
+}): Promise<CreateBillingCheckoutResult> {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  return client.createBillingCheckout({
+    planId: input.planId,
+    externalUserId: input.externalUserId,
+    ...(input.successUrl ? { successUrl: input.successUrl } : {}),
+    ...(input.cancelUrl ? { cancelUrl: input.cancelUrl } : {}),
+  });
+}
diff --git a/lib/dashboard/useBillingPlans.ts b/lib/dashboard/useBillingPlans.ts
new file mode 100644
index 0000000..37c1b62
--- /dev/null
+++ b/lib/dashboard/useBillingPlans.ts
@@ -0,0 +1,76 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import type { DashboardBillingPlan } from "@/lib/dashboard/pymthouse-billing-bff";
+
+export type BillingPlansState =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "ready"; plans: DashboardBillingPlan[] }
+  | { status: "error"; message: string };
+
+async function readResponseJson<T>(response: Response): Promise<T> {
+  const text = await response.text();
+  if (!text.trim()) {
+    throw new Error(`Empty response (${response.status})`);
+  }
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(`Invalid JSON (${response.status})`);
+  }
+}
+
+export function useBillingPlans() {
+  const [state, setState] = useState<BillingPlansState>({ status: "idle" });
+
+  const load = useCallback(async () => {
+    setState({ status: "loading" });
+    try {
+      const response = await fetch("/api/pymthouse/plans");
+      const body = await readResponseJson<{
+        plans?: DashboardBillingPlan[];
+        error?: string;
+      }>(response);
+      if (!response.ok) {
+        throw new Error(body.error ?? `Plans fetch failed (${response.status})`);
+      }
+      setState({ status: "ready", plans: body.plans ?? [] });
+    } catch (error) {
+      setState({
+        status: "error",
+        message:
+          error instanceof Error ? error.message : "Failed to load plans",
+      });
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const subscribe = useCallback(
+    async (input: { planId: string; externalUserId: string }) => {
+      const response = await fetch("/api/pymthouse/subscribe", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+      });
+      const body = await readResponseJson<{
+        checkoutUrl?: string;
+        subscriptionId?: string;
+        error?: string;
+      }>(response);
+      if (!response.ok || !body.checkoutUrl) {
+        throw new Error(body.error ?? `Subscribe failed (${response.status})`);
+      }
+      return {
+        checkoutUrl: body.checkoutUrl,
+        subscriptionId: body.subscriptionId,
+      };
+    },
+    [],
+  );
+
+  return { state, reload: load, subscribe };
+}
diff --git a/package.json b/package.json
index 259bc7a..fff5293 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,7 @@
     "format:check": "prettier . --check"
   },
   "dependencies": {
-    "@pymthouse/builder-sdk": "0.6.1",
+    "@pymthouse/builder-sdk": "github:pymthouse/builder-sdk#feat/create-billing-checkout",
     "framer-motion": "^11.15.0",
     "geist": "^1.7.0",
     "jmuxer": "^2.1.0",
@@ -39,5 +39,10 @@
     "prettier": "^3.8.1",
     "tailwindcss": "^4.0.0",
     "typescript": "^5.7.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@pymthouse/builder-sdk"
+    ]
   }
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 579e677..c14d885 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -9,8 +9,8 @@ importers:
   .:
     dependencies:
       '@pymthouse/builder-sdk':
-        specifier: 0.6.1
-        version: 0.6.1
+        specifier: github:pymthouse/builder-sdk#feat/create-billing-checkout
+        version: https://codeload.github.com/pymthouse/builder-sdk/tar.gz/08f3f4afdf90aa6d641a26b4f93b2fd8c0ced605
       framer-motion:
         specifier: ^11.15.0
         version: 11.18.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -401,8 +401,9 @@ packages:
     resolution: {integrity: sha512-nn5ozdjYQpUCZlWGuxcJY/KpxkWQs4DcbMCmKojjyrYDEAGy4Ce19NN4v5MduafTwJlbKc99UA8YhSVqq9yPZA==}
     engines: {node: '>=12.4.0'}
 
-  '@pymthouse/builder-sdk@0.6.1':
-    resolution: {integrity: sha512-ALGluRpNAdnoK0Qk1ugP7TVcTrEPtnkipeIsSx6UX6hD1MN8mtOrgZAi+dhB2VZGEM7OBdWz1YhK6V1yskialw==}
+  '@pymthouse/builder-sdk@https://codeload.github.com/pymthouse/builder-sdk/tar.gz/08f3f4afdf90aa6d641a26b4f93b2fd8c0ced605':
+    resolution: {tarball: https://codeload.github.com/pymthouse/builder-sdk/tar.gz/08f3f4afdf90aa6d641a26b4f93b2fd8c0ced605}
+    version: 0.6.2
     engines: {node: '>=20'}
 
   '@reduxjs/toolkit@2.11.2':
@@ -2331,7 +2332,7 @@ snapshots:
 
   '@nolyfill/is-core-module@1.0.39': {}
 
-  '@pymthouse/builder-sdk@0.6.1':
+  '@pymthouse/builder-sdk@https://codeload.github.com/pymthouse/builder-sdk/tar.gz/08f3f4afdf90aa6d641a26b4f93b2fd8c0ced605':
     dependencies:
       oauth4webapi: 3.8.6
 

From 98a446e5f6791297e1cc27ffa75c85e6c5144c17 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Wed, 5 Aug 2026 22:46:53 -0400
Subject: [PATCH 02/13] chore(deps): pin @pymthouse/builder-sdk to published
 0.6.2

builder-sdk#50 merged and published; drop the git branch pin and the
onlyBuiltDependencies workaround needed for prepare-on-install.
---
 package.json   |  7 +------
 pnpm-lock.yaml | 11 +++++------
 2 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/package.json b/package.json
index fff5293..54d8986 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,7 @@
     "format:check": "prettier . --check"
   },
   "dependencies": {
-    "@pymthouse/builder-sdk": "github:pymthouse/builder-sdk#feat/create-billing-checkout",
+    "@pymthouse/builder-sdk": "0.6.2",
     "framer-motion": "^11.15.0",
     "geist": "^1.7.0",
     "jmuxer": "^2.1.0",
@@ -39,10 +39,5 @@
     "prettier": "^3.8.1",
     "tailwindcss": "^4.0.0",
     "typescript": "^5.7.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "@pymthouse/builder-sdk"
-    ]
   }
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c14d885..5596f9e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -9,8 +9,8 @@ importers:
   .:
     dependencies:
       '@pymthouse/builder-sdk':
-        specifier: github:pymthouse/builder-sdk#feat/create-billing-checkout
-        version: https://codeload.github.com/pymthouse/builder-sdk/tar.gz/08f3f4afdf90aa6d641a26b4f93b2fd8c0ced605
+        specifier: 0.6.2
+        version: 0.6.2
       framer-motion:
         specifier: ^11.15.0
         version: 11.18.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -401,9 +401,8 @@ packages:
     resolution: {integrity: sha512-nn5ozdjYQpUCZlWGuxcJY/KpxkWQs4DcbMCmKojjyrYDEAGy4Ce19NN4v5MduafTwJlbKc99UA8YhSVqq9yPZA==}
     engines: {node: '>=12.4.0'}
 
-  '@pymthouse/builder-sdk@https://codeload.github.com/pymthouse/builder-sdk/tar.gz/08f3f4afdf90aa6d641a26b4f93b2fd8c0ced605':
-    resolution: {tarball: https://codeload.github.com/pymthouse/builder-sdk/tar.gz/08f3f4afdf90aa6d641a26b4f93b2fd8c0ced605}
-    version: 0.6.2
+  '@pymthouse/builder-sdk@0.6.2':
+    resolution: {integrity: sha512-IXxgOyAqRcnkU+TipBFMpEeL0epMzUCrDWt8jwsftZpnc60y3ZZlPrxb0IbP+DxKIan9HXrJtQJsfz00yV7E9w==}
     engines: {node: '>=20'}
 
   '@reduxjs/toolkit@2.11.2':
@@ -2332,7 +2331,7 @@ snapshots:
 
   '@nolyfill/is-core-module@1.0.39': {}
 
-  '@pymthouse/builder-sdk@https://codeload.github.com/pymthouse/builder-sdk/tar.gz/08f3f4afdf90aa6d641a26b4f93b2fd8c0ced605':
+  '@pymthouse/builder-sdk@0.6.2':
     dependencies:
       oauth4webapi: 3.8.6
 

From 6ec9fc571d45116fc1455c20eaa3f2e5f210d174 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Thu, 6 Aug 2026 22:10:20 -0400
Subject: [PATCH 03/13] Wire dashboard payment methods and Connect invoices

Add merchant card controls and invoice links through the billing BFF so users
can manage their payment method and access Connect-hosted invoices.
---
 .../invoices/[invoiceId]/hosted-url/route.ts  |  46 +++++
 app/api/pymthouse/invoices/route.ts           |  40 ++++
 app/api/pymthouse/payment-methods/route.ts    | 181 ++++++++++++++++++
 lib/dashboard/pymthouse-billing-bff.ts        |  88 +++++++++
 lib/dashboard/useBillingAccount.ts            | 179 +++++++++++++++++
 package.json                                  |   3 +-
 pnpm-lock.yaml                                |  10 +-
 7 files changed, 541 insertions(+), 6 deletions(-)
 create mode 100644 app/api/pymthouse/invoices/[invoiceId]/hosted-url/route.ts
 create mode 100644 app/api/pymthouse/invoices/route.ts
 create mode 100644 app/api/pymthouse/payment-methods/route.ts
 create mode 100644 lib/dashboard/useBillingAccount.ts

diff --git a/app/api/pymthouse/invoices/[invoiceId]/hosted-url/route.ts b/app/api/pymthouse/invoices/[invoiceId]/hosted-url/route.ts
new file mode 100644
index 0000000..6b9f568
--- /dev/null
+++ b/app/api/pymthouse/invoices/[invoiceId]/hosted-url/route.ts
@@ -0,0 +1,46 @@
+import { NextRequest, NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+import { getDashboardUserInvoiceHostedUrl } from "@/lib/dashboard/pymthouse-billing-bff";
+
+export const runtime = "nodejs";
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ invoiceId: string }> },
+) {
+  const externalUserId =
+    request.nextUrl.searchParams.get("externalUserId")?.trim() || "";
+  const { invoiceId: rawInvoiceId } = await params;
+  const invoiceId = decodeURIComponent(rawInvoiceId).trim();
+
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 },
+    );
+  }
+  if (!invoiceId) {
+    return NextResponse.json(
+      { error: "invoiceId is required" },
+      { status: 400 },
+    );
+  }
+
+  try {
+    const links = await getDashboardUserInvoiceHostedUrl(
+      externalUserId,
+      invoiceId,
+    );
+    return NextResponse.json(links);
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status },
+      );
+    }
+    const message =
+      error instanceof Error ? error.message : "Failed to resolve invoice link";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
diff --git a/app/api/pymthouse/invoices/route.ts b/app/api/pymthouse/invoices/route.ts
new file mode 100644
index 0000000..683dda7
--- /dev/null
+++ b/app/api/pymthouse/invoices/route.ts
@@ -0,0 +1,40 @@
+import { NextRequest, NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+import { listDashboardUserInvoices } from "@/lib/dashboard/pymthouse-billing-bff";
+
+export const runtime = "nodejs";
+
+export async function GET(request: NextRequest) {
+  const externalUserId =
+    request.nextUrl.searchParams.get("externalUserId")?.trim() || "";
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 },
+    );
+  }
+
+  const pageRaw = Number(request.nextUrl.searchParams.get("page") || "1");
+  const pageSizeRaw = Number(
+    request.nextUrl.searchParams.get("pageSize") || "20",
+  );
+
+  try {
+    const result = await listDashboardUserInvoices(externalUserId, {
+      page: Number.isFinite(pageRaw) && pageRaw > 0 ? pageRaw : 1,
+      pageSize:
+        Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 20,
+    });
+    return NextResponse.json(result);
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status },
+      );
+    }
+    const message =
+      error instanceof Error ? error.message : "Failed to load invoices";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
diff --git a/app/api/pymthouse/payment-methods/route.ts b/app/api/pymthouse/payment-methods/route.ts
new file mode 100644
index 0000000..dfd9663
--- /dev/null
+++ b/app/api/pymthouse/payment-methods/route.ts
@@ -0,0 +1,181 @@
+import { NextRequest, NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+import {
+  listDashboardUserPaymentMethods,
+  removeDashboardUserPaymentMethod,
+  setDashboardUserDefaultPaymentMethod,
+  startDashboardPaymentMethodCheckout,
+} from "@/lib/dashboard/pymthouse-billing-bff";
+
+export const runtime = "nodejs";
+
+function checkoutReturnOrigin(request: NextRequest): string {
+  const configuredOrigin = (
+    process.env.DASHBOARD_PUBLIC_URL ||
+    process.env.NEXT_PUBLIC_APP_URL ||
+    ""
+  )
+    .trim()
+    .replace(/\/$/, "");
+  let origin = configuredOrigin || request.nextUrl.origin;
+  try {
+    const parsed = new URL(origin);
+    if (
+      parsed.protocol === "http:" &&
+      parsed.hostname !== "localhost" &&
+      parsed.hostname !== "127.0.0.1"
+    ) {
+      parsed.protocol = "https:";
+      origin = parsed.origin;
+    } else {
+      origin = parsed.origin;
+    }
+  } catch {
+    origin = request.nextUrl.origin;
+  }
+  return origin;
+}
+
+export async function GET(request: NextRequest) {
+  const externalUserId =
+    request.nextUrl.searchParams.get("externalUserId")?.trim() || "";
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 },
+    );
+  }
+
+  try {
+    const paymentMethods =
+      await listDashboardUserPaymentMethods(externalUserId);
+    return NextResponse.json({ paymentMethods });
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status },
+      );
+    }
+    const message =
+      error instanceof Error ? error.message : "Failed to load payment methods";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
+
+export async function POST(request: NextRequest) {
+  let body: {
+    externalUserId?: string;
+    successUrl?: string;
+    cancelUrl?: string;
+  };
+  try {
+    body = (await request.json()) as typeof body;
+  } catch {
+    return NextResponse.json({ error: "invalid_json" }, { status: 400 });
+  }
+
+  const externalUserId = body.externalUserId?.trim();
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 },
+    );
+  }
+
+  const origin = checkoutReturnOrigin(request);
+  const successUrl =
+    body.successUrl?.trim() ||
+    `${origin}/settings?tab=billing&checkout=success`;
+  const cancelUrl =
+    body.cancelUrl?.trim() || `${origin}/settings?tab=billing&checkout=cancel`;
+
+  try {
+    const result = await startDashboardPaymentMethodCheckout({
+      externalUserId,
+      successUrl,
+      cancelUrl,
+    });
+    return NextResponse.json(result);
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status },
+      );
+    }
+    const message =
+      error instanceof Error
+        ? error.message
+        : "Failed to start payment method checkout";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
+
+async function readPaymentMethodMutation(request: NextRequest): Promise<
+  | { externalUserId: string; paymentMethodId: string }
+  | NextResponse
+> {
+  let body: { externalUserId?: string; paymentMethodId?: string };
+  try {
+    body = (await request.json()) as typeof body;
+  } catch {
+    return NextResponse.json({ error: "invalid_json" }, { status: 400 });
+  }
+  const externalUserId = body.externalUserId?.trim();
+  const paymentMethodId = body.paymentMethodId?.trim();
+  if (!externalUserId || !paymentMethodId) {
+    return NextResponse.json(
+      { error: "externalUserId and paymentMethodId are required" },
+      { status: 400 },
+    );
+  }
+  return { externalUserId, paymentMethodId };
+}
+
+export async function PATCH(request: NextRequest) {
+  const input = await readPaymentMethodMutation(request);
+  if (input instanceof NextResponse) {
+    return input;
+  }
+  try {
+    return NextResponse.json(
+      await setDashboardUserDefaultPaymentMethod(
+        input.externalUserId,
+        input.paymentMethodId,
+      ),
+    );
+  } catch (error) {
+    return billingErrorResponse(error, "Failed to set default payment method");
+  }
+}
+
+export async function DELETE(request: NextRequest) {
+  const input = await readPaymentMethodMutation(request);
+  if (input instanceof NextResponse) {
+    return input;
+  }
+  try {
+    return NextResponse.json(
+      await removeDashboardUserPaymentMethod(
+        input.externalUserId,
+        input.paymentMethodId,
+      ),
+    );
+  } catch (error) {
+    return billingErrorResponse(error, "Failed to remove payment method");
+  }
+}
+
+function billingErrorResponse(error: unknown, fallback: string): NextResponse {
+  if (error instanceof PmtHouseError) {
+    return NextResponse.json(
+      { error: error.message, code: error.code },
+      { status: error.status },
+    );
+  }
+  return NextResponse.json(
+    { error: error instanceof Error ? error.message : fallback },
+    { status: 502 },
+  );
+}
diff --git a/lib/dashboard/pymthouse-billing-bff.ts b/lib/dashboard/pymthouse-billing-bff.ts
index fa4ae87..41a06b1 100644
--- a/lib/dashboard/pymthouse-billing-bff.ts
+++ b/lib/dashboard/pymthouse-billing-bff.ts
@@ -1,7 +1,12 @@
 import {
   PmtHouseError,
+  type AppUserInvoice,
+  type AppUserInvoiceHostedUrlResult,
+  type AppUserPaymentMethod,
   type BillingProduct,
+  type CreateAppUserPaymentMethodCheckoutResult,
   type CreateBillingCheckoutResult,
+  type UserSubscriptionResponse,
 } from "@pymthouse/builder-sdk";
 import { createPmtHouseClientForPublicApp } from "@/lib/dashboard/pymthouse-bff";
 
@@ -70,3 +75,86 @@ export async function startDashboardBillingCheckout(input: {
     ...(input.cancelUrl ? { cancelUrl: input.cancelUrl } : {}),
   });
 }
+
+export type DashboardUserSubscription = {
+  planId: string | null;
+  planName: string | null;
+  status: string | null;
+  subscriptionId: string | null;
+};
+
+export async function getDashboardUserSubscription(
+  externalUserId: string,
+): Promise<DashboardUserSubscription> {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  const result: UserSubscriptionResponse =
+    await client.getUserSubscription(externalUserId);
+  const sub = result.subscription;
+  return {
+    planId: sub?.planId?.trim() || null,
+    planName: sub?.planName?.trim() || null,
+    status: sub?.status?.trim() || null,
+    subscriptionId: sub?.id?.trim() || null,
+  };
+}
+
+export type DashboardInvoice = AppUserInvoice;
+export type DashboardPaymentMethod = AppUserPaymentMethod;
+
+export async function listDashboardUserInvoices(
+  externalUserId: string,
+  opts?: { page?: number; pageSize?: number },
+): Promise<{
+  items: DashboardInvoice[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}> {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  return client.listUserInvoices(externalUserId, opts);
+}
+
+export async function getDashboardUserInvoiceHostedUrl(
+  externalUserId: string,
+  invoiceId: string,
+): Promise<AppUserInvoiceHostedUrlResult> {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  return client.getUserInvoiceHostedUrl(externalUserId, invoiceId);
+}
+
+export async function listDashboardUserPaymentMethods(
+  externalUserId: string,
+): Promise<DashboardPaymentMethod[]> {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  const result = await client.listUserPaymentMethods(externalUserId);
+  return result.paymentMethods ?? [];
+}
+
+export async function startDashboardPaymentMethodCheckout(input: {
+  externalUserId: string;
+  successUrl?: string;
+  cancelUrl?: string;
+}): Promise<CreateAppUserPaymentMethodCheckoutResult> {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  return client.createUserPaymentMethodCheckout({
+    externalUserId: input.externalUserId,
+    ...(input.successUrl ? { successUrl: input.successUrl } : {}),
+    ...(input.cancelUrl ? { cancelUrl: input.cancelUrl } : {}),
+  });
+}
+
+export async function setDashboardUserDefaultPaymentMethod(
+  externalUserId: string,
+  paymentMethodId: string,
+) {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  return client.setUserDefaultPaymentMethod(externalUserId, paymentMethodId);
+}
+
+export async function removeDashboardUserPaymentMethod(
+  externalUserId: string,
+  paymentMethodId: string,
+) {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  return client.unlinkUserPaymentMethod(externalUserId, paymentMethodId);
+}
diff --git a/lib/dashboard/useBillingAccount.ts b/lib/dashboard/useBillingAccount.ts
new file mode 100644
index 0000000..0fc47da
--- /dev/null
+++ b/lib/dashboard/useBillingAccount.ts
@@ -0,0 +1,179 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import type {
+  DashboardInvoice,
+  DashboardPaymentMethod,
+} from "@/lib/dashboard/pymthouse-billing-bff";
+
+async function readResponseJson<T>(response: Response): Promise<T> {
+  const text = await response.text();
+  if (!text.trim()) {
+    throw new Error(`Empty response (${response.status})`);
+  }
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(`Invalid JSON (${response.status})`);
+  }
+}
+
+export type BillingAccountState =
+  | { status: "idle" }
+  | { status: "loading" }
+  | {
+      status: "ready";
+      paymentMethods: DashboardPaymentMethod[];
+      invoices: DashboardInvoice[];
+    }
+  | { status: "error"; message: string };
+
+export function useBillingAccount(externalUserId: string | undefined) {
+  const [state, setState] = useState<BillingAccountState>({ status: "idle" });
+
+  const load = useCallback(async () => {
+    const trimmed = externalUserId?.trim();
+    if (!trimmed) {
+      setState({
+        status: "ready",
+        paymentMethods: [],
+        invoices: [],
+      });
+      return;
+    }
+
+    setState({ status: "loading" });
+    try {
+      const q = encodeURIComponent(trimmed);
+      const [pmResponse, invResponse] = await Promise.all([
+        fetch(`/api/pymthouse/payment-methods?externalUserId=${q}`),
+        fetch(`/api/pymthouse/invoices?externalUserId=${q}&pageSize=20`),
+      ]);
+
+      const pmBody = await readResponseJson<{
+        paymentMethods?: DashboardPaymentMethod[];
+        error?: string;
+      }>(pmResponse);
+      if (!pmResponse.ok) {
+        throw new Error(
+          pmBody.error ?? `Payment methods failed (${pmResponse.status})`,
+        );
+      }
+
+      const invBody = await readResponseJson<{
+        items?: DashboardInvoice[];
+        error?: string;
+      }>(invResponse);
+      if (!invResponse.ok) {
+        throw new Error(
+          invBody.error ?? `Invoices failed (${invResponse.status})`,
+        );
+      }
+
+      setState({
+        status: "ready",
+        paymentMethods: pmBody.paymentMethods ?? [],
+        invoices: invBody.items ?? [],
+      });
+    } catch (error) {
+      setState({
+        status: "error",
+        message:
+          error instanceof Error ? error.message : "Failed to load billing",
+      });
+    }
+  }, [externalUserId]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const startPaymentMethodCheckout = useCallback(
+    async (input: { externalUserId: string }) => {
+      const response = await fetch("/api/pymthouse/payment-methods", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ externalUserId: input.externalUserId }),
+      });
+      const body = await readResponseJson<{
+        checkoutUrl?: string;
+        error?: string;
+      }>(response);
+      if (!response.ok || !body.checkoutUrl) {
+        throw new Error(
+          body.error ?? `Payment method checkout failed (${response.status})`,
+        );
+      }
+      return { checkoutUrl: body.checkoutUrl };
+    },
+    [],
+  );
+
+  const openInvoice = useCallback(
+    async (input: { externalUserId: string; invoiceId: string }) => {
+      const response = await fetch(
+        `/api/pymthouse/invoices/${encodeURIComponent(input.invoiceId)}/hosted-url?externalUserId=${encodeURIComponent(input.externalUserId)}`,
+      );
+      const body = await readResponseJson<{
+        hostedInvoiceUrl?: string | null;
+        invoicePdf?: string | null;
+        error?: string;
+      }>(response);
+      if (!response.ok) {
+        throw new Error(
+          body.error ?? `Invoice link failed (${response.status})`,
+        );
+      }
+      return {
+        hostedInvoiceUrl: body.hostedInvoiceUrl ?? null,
+        invoicePdf: body.invoicePdf ?? null,
+      };
+    },
+    [],
+  );
+
+  const setDefaultPaymentMethod = useCallback(
+    async (input: { externalUserId: string; paymentMethodId: string }) => {
+      const response = await fetch("/api/pymthouse/payment-methods", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+      });
+      const body = await readResponseJson<{ error?: string }>(response);
+      if (!response.ok) {
+        throw new Error(
+          body.error ?? `Set default payment method failed (${response.status})`,
+        );
+      }
+      await load();
+    },
+    [load],
+  );
+
+  const removePaymentMethod = useCallback(
+    async (input: { externalUserId: string; paymentMethodId: string }) => {
+      const response = await fetch("/api/pymthouse/payment-methods", {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+      });
+      const body = await readResponseJson<{ error?: string }>(response);
+      if (!response.ok) {
+        throw new Error(
+          body.error ?? `Remove payment method failed (${response.status})`,
+        );
+      }
+      await load();
+    },
+    [load],
+  );
+
+  return {
+    state,
+    reload: load,
+    startPaymentMethodCheckout,
+    openInvoice,
+    setDefaultPaymentMethod,
+    removePaymentMethod,
+  };
+}
diff --git a/package.json b/package.json
index 75fe678..f9bf759 100644
--- a/package.json
+++ b/package.json
@@ -5,6 +5,7 @@
   "packageManager": "pnpm@10.33.0",
   "scripts": {
     "dev": "next dev",
+    "dev:https": "next dev --experimental-https",
     "build": "next build",
     "start": "next start",
     "lint": "eslint . --max-warnings 0",
@@ -13,7 +14,7 @@
     "format:check": "prettier . --check"
   },
   "dependencies": {
-    "@pymthouse/builder-sdk": "0.6.3",
+    "@pymthouse/builder-sdk": "file:../builder-sdk",
     "framer-motion": "^11.15.0",
     "geist": "^1.7.0",
     "jmuxer": "^2.1.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3c3d2cd..f92ba5d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -9,8 +9,8 @@ importers:
   .:
     dependencies:
       '@pymthouse/builder-sdk':
-        specifier: 0.6.3
-        version: 0.6.3
+        specifier: file:../builder-sdk
+        version: file:../builder-sdk
       framer-motion:
         specifier: ^11.15.0
         version: 11.18.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -401,8 +401,8 @@ packages:
     resolution: {integrity: sha512-nn5ozdjYQpUCZlWGuxcJY/KpxkWQs4DcbMCmKojjyrYDEAGy4Ce19NN4v5MduafTwJlbKc99UA8YhSVqq9yPZA==}
     engines: {node: '>=12.4.0'}
 
-  '@pymthouse/builder-sdk@0.6.3':
-    resolution: {integrity: sha512-ex+qcGknv6gs+FqvmgoQgR5Trwy/yQ7UIO91jlGVPpgwSccFqTunP/Lmi+ABY9Gz1F0xN+U9C6AYOhkFSb/Nsw==}
+  '@pymthouse/builder-sdk@file:../builder-sdk':
+    resolution: {directory: ../builder-sdk, type: directory}
     engines: {node: '>=20'}
 
   '@reduxjs/toolkit@2.11.2':
@@ -2331,7 +2331,7 @@ snapshots:
 
   '@nolyfill/is-core-module@1.0.39': {}
 
-  '@pymthouse/builder-sdk@0.6.3':
+  '@pymthouse/builder-sdk@file:../builder-sdk':
     dependencies:
       oauth4webapi: 3.8.6
 

From f09522d53c9f944b258b30084940360fcf0bfc68 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Thu, 6 Aug 2026 22:15:49 -0400
Subject: [PATCH 04/13] Add billing payment-method row actions and Connect
 invoice copy.

Wire useBillingAccount into BillingSection: live payment method list
with Set-as-default and Remove (confirm) row actions, live invoice
table with View/PDF links resolved via the Stripe hosted-url endpoint,
and updated copy ("Stripe invoices for this account"). Removes static
blur/WIP overlay and fake billing-details block; plan section stays
static pending subscribe-flow work.
---
 .../dashboard/settings/BillingSection.tsx     | 428 +++++++++++-------
 1 file changed, 275 insertions(+), 153 deletions(-)

diff --git a/components/dashboard/settings/BillingSection.tsx b/components/dashboard/settings/BillingSection.tsx
index d46eb20..265e271 100644
--- a/components/dashboard/settings/BillingSection.tsx
+++ b/components/dashboard/settings/BillingSection.tsx
@@ -1,36 +1,140 @@
 "use client";
 
-import { ArrowRight, Box, Check, Download, Plus } from "lucide-react";
+import { useState } from "react";
+import { ArrowRight, Box, Check, CreditCard, Download, Plus, Trash2 } from "lucide-react";
+import { useAuth } from "@/components/dashboard/AuthContext";
 import {
   IconButton,
   SettingsCard,
-  SettingsField,
   SettingsHeader,
-  SettingsInput,
-  SettingsTextarea,
   ST_COLS_5,
   ST_HEAD_CLASS,
 } from "./SettingsPrimitives";
+import { useBillingAccount } from "@/lib/dashboard/useBillingAccount";
+
+function formatInvoiceAmount(totalAmount: string, currency: string): string {
+  const n = Number(totalAmount);
+  if (!Number.isFinite(n)) return `${totalAmount} ${currency}`;
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: currency || "USD",
+  }).format(n);
+}
+
+function formatInvoiceDate(iso: string | undefined): string {
+  if (!iso) return "—";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  return d.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  });
+}
 
 /**
  * Organization · Billing — `?tab=billing` per the v7 prototype.
  *
- * Four blocks:
- *  1. Plan — three plan cards side by side (Free, Pro, Scale)
- *  2. Payment method — empty state ("No payment method · Add a card…")
- *  3. Billing details — company / email / tax ID / address fields
- *  4. Invoices — table of historical invoices
+ * Plan block is static (subscribe flow is a separate WIP).
+ * Payment method and invoices are live, wired to useBillingAccount.
  */
 export default function BillingSection() {
-  // Billing view is rendered behind a blur with a "Work in progress" notice
-  // on top — reviewers can see the surface area without mistaking it for a
-  // finalized flow. Real treatment is still being designed.
+  const { user } = useAuth();
+  const externalUserId = user?.id?.trim();
+
+  const {
+    state: accountState,
+    reload: reloadAccount,
+    startPaymentMethodCheckout,
+    openInvoice,
+    setDefaultPaymentMethod,
+    removePaymentMethod,
+  } = useBillingAccount(externalUserId);
+
+  const [pmBusy, setPmBusy] = useState(false);
+  const [paymentMethodActionId, setPaymentMethodActionId] = useState<string | null>(null);
+  const [invoiceBusyId, setInvoiceBusyId] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  async function onAddCard() {
+    if (!externalUserId) {
+      setError("Sign in to add a payment method.");
+      return;
+    }
+    setError(null);
+    setPmBusy(true);
+    try {
+      const { checkoutUrl } = await startPaymentMethodCheckout({ externalUserId });
+      window.location.assign(checkoutUrl);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Payment method checkout failed");
+      setPmBusy(false);
+    }
+  }
+
+  async function onOpenInvoice(invoiceId: string, prefer: "hosted" | "pdf") {
+    if (!externalUserId) return;
+    setError(null);
+    setInvoiceBusyId(invoiceId);
+    try {
+      const links = await openInvoice({ externalUserId, invoiceId });
+      const url =
+        prefer === "pdf"
+          ? links.invoicePdf || links.hostedInvoiceUrl
+          : links.hostedInvoiceUrl || links.invoicePdf;
+      if (!url) {
+        throw new Error("No Stripe invoice page for this invoice yet.");
+      }
+      window.open(url, "_blank", "noopener,noreferrer");
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Could not open invoice");
+    } finally {
+      setInvoiceBusyId(null);
+    }
+  }
+
+  async function onSetDefaultPaymentMethod(paymentMethodId: string) {
+    if (!externalUserId) return;
+    setError(null);
+    setPaymentMethodActionId(paymentMethodId);
+    try {
+      await setDefaultPaymentMethod({ externalUserId, paymentMethodId });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Could not set default payment method");
+    } finally {
+      setPaymentMethodActionId(null);
+    }
+  }
+
+  async function onRemovePaymentMethod(paymentMethodId: string) {
+    if (!externalUserId) return;
+    if (!window.confirm("Remove this payment method?")) return;
+    setError(null);
+    setPaymentMethodActionId(paymentMethodId);
+    try {
+      await removePaymentMethod({ externalUserId, paymentMethodId });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Could not remove payment method");
+    } finally {
+      setPaymentMethodActionId(null);
+    }
+  }
+
+  const accountLoading =
+    accountState.status === "loading" || accountState.status === "idle";
+  const paymentMethods =
+    accountState.status === "ready" ? accountState.paymentMethods : [];
+  const invoices =
+    accountState.status === "ready" ? accountState.invoices : [];
+
   return (
-    <div className="relative">
-      <div
-        className="pointer-events-none select-none blur-sm"
-        aria-hidden="true"
-      >
+    <div>
+      {error ? (
+        <p className="mb-4 text-[13px] text-red-400" role="alert">
+          {error}
+        </p>
+      ) : null}
+
       <SettingsHeader
         title="Plan"
         sub="You're on the free tier · 10,000 jobs/month"
@@ -38,11 +142,7 @@ export default function BillingSection() {
 
       <SettingsCard>
         <div className="grid grid-cols-1 md:grid-cols-3">
-          {/* Free — current plan: 2px accent rail on the left + a vertical
-              `rgba(64,191,134,0.06) → transparent` wash, per the v7
-              prototype's `.plan-active` rule. The gradient subtly tints the
-              top of the card so the "current plan" reads at a glance even
-              before the eyebrow is parsed. */}
+          {/* Free — current plan */}
           <div
             className="relative border-b border-hairline p-[18px] md:border-b-0 md:border-r"
             style={{
@@ -85,7 +185,6 @@ export default function BillingSection() {
             </ul>
           </div>
 
-          {/* Pro — upgrade option */}
           <PlanCard
             name="Pro"
             price="$29"
@@ -99,7 +198,6 @@ export default function BillingSection() {
             cta="Upgrade to Pro"
           />
 
-          {/* Scale — enterprise */}
           <PlanCard
             name="Scale"
             price="Custom"
@@ -119,146 +217,170 @@ export default function BillingSection() {
 
       <SettingsHeader
         title="Payment method"
-        sub="Card on file for usage above the free tier"
+        sub="Card on file for subscription and usage charges"
         action={
-          <IconButton primary>
+          <IconButton primary onClick={() => void onAddCard()} disabled={pmBusy || !externalUserId}>
             <Plus className="h-3 w-3" aria-hidden="true" />
-            Add card
+            {pmBusy ? "Starting…" : "Add card"}
           </IconButton>
         }
       />
       <SettingsCard>
-        <div className="px-5 py-9 text-center">
-          <Box
-            className="mx-auto h-[22px] w-[22px] text-fg-disabled"
-            strokeWidth={1.5}
-            aria-hidden="true"
-          />
-          <p className="mt-2 text-[13.5px] font-medium text-fg">
-            No payment method
-          </p>
-          <p className="mt-1 text-[12.5px] text-fg-faint">
-            Add a card to keep capabilities running past the free quota.
-          </p>
-        </div>
-      </SettingsCard>
-
-      <SettingsHeader
-        title="Billing details"
-        sub="Used on invoices and receipts"
-      />
-      <SettingsCard>
-        <SettingsField
-          label="Company name"
-          hint="Optional — appears on invoices."
-        >
-          <SettingsInput defaultValue="Flipbook, Inc." />
-        </SettingsField>
-        <SettingsField label="Billing email">
-          <SettingsInput defaultValue="billing@flipbook.page" />
-        </SettingsField>
-        <SettingsField
-          label="Tax ID"
-          hint="VAT, GST, ABN — formatting depends on country."
-        >
-          <SettingsInput placeholder="Add tax ID" />
-        </SettingsField>
-        <SettingsField
-          label="Billing address"
-          hint="Used for tax calculation."
-        >
-          <SettingsTextarea
-            rows={3}
-            defaultValue={"2261 Market St #4090\nSan Francisco, CA 94114\nUnited States"}
-          />
-        </SettingsField>
+        {accountLoading ? (
+          <div className="animate-pulse px-5 py-9">
+            <div className="mx-auto h-5 w-40 rounded bg-white/5" />
+          </div>
+        ) : accountState.status === "error" ? (
+          <div className="px-5 py-6 text-center">
+            <p className="text-[13px] text-fg-muted">
+              Could not load payment methods.
+            </p>
+            <button
+              type="button"
+              className="mt-2 text-[12.5px] text-fg-strong underline"
+              onClick={() => void reloadAccount()}
+            >
+              Retry
+            </button>
+          </div>
+        ) : paymentMethods.length === 0 ? (
+          <div className="px-5 py-9 text-center">
+            <Box
+              className="mx-auto h-[22px] w-[22px] text-fg-disabled"
+              strokeWidth={1.5}
+              aria-hidden="true"
+            />
+            <p className="mt-2 text-[13.5px] font-medium text-fg">
+              No payment method
+            </p>
+            <p className="mt-1 text-[12.5px] text-fg-faint">
+              Add a card via Stripe Checkout. Completing Checkout updates your
+              card on file even if you do not return to this page.
+            </p>
+          </div>
+        ) : (
+          <ul className="divide-y divide-hairline">
+            {paymentMethods.map((pm) => {
+              const isBusy = paymentMethodActionId === pm.id;
+              return (
+                <li
+                  key={pm.id}
+                  className="flex items-center gap-3 px-5 py-3.5"
+                >
+                  <CreditCard
+                    className="h-4 w-4 shrink-0 text-fg-faint"
+                    aria-hidden="true"
+                  />
+                  <div className="min-w-0 flex-1">
+                    <p className="text-[13.5px] font-medium text-fg">
+                      {(pm.brand || pm.type || "Card").toUpperCase()}
+                      {pm.last4 ? ` ···· ${pm.last4}` : ""}
+                    </p>
+                    <p className="text-[12px] text-fg-faint">
+                      {pm.expMonth && pm.expYear
+                        ? `Expires ${String(pm.expMonth).padStart(2, "0")}/${pm.expYear}`
+                        : pm.type}
+                      {pm.isDefault ? " · Default" : ""}
+                    </p>
+                  </div>
+                  {!pm.isDefault ? (
+                    <button
+                      type="button"
+                      className="text-[12px] text-green-bright transition-colors hover:text-fg disabled:opacity-50"
+                      disabled={paymentMethodActionId !== null}
+                      onClick={() => void onSetDefaultPaymentMethod(pm.id)}
+                    >
+                      {isBusy ? "Saving…" : "Set default"}
+                    </button>
+                  ) : null}
+                  <button
+                    type="button"
+                    className="inline-flex h-7 w-7 items-center justify-center rounded text-fg-faint transition-colors hover:bg-white/5 hover:text-red-400 disabled:opacity-50"
+                    disabled={paymentMethodActionId !== null}
+                    onClick={() => void onRemovePaymentMethod(pm.id)}
+                    aria-label={`Remove ${(pm.brand || pm.type || "payment method").toLowerCase()} ending ${pm.last4 ?? ""}`}
+                    title="Remove payment method"
+                  >
+                    {isBusy ? "…" : <Trash2 className="h-3.5 w-3.5" aria-hidden="true" />}
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+        )}
       </SettingsCard>
 
-      <SettingsHeader
-        title="Invoices"
-        action={
-          <IconButton>
-            <Download className="h-3 w-3" aria-hidden="true" />
-            Download all
-          </IconButton>
-        }
-      />
+      <SettingsHeader title="Invoices" sub="Stripe invoices for this account" />
       <SettingsCard>
-        <div className={`${ST_COLS_5} ${ST_HEAD_CLASS}`}>
-          <span>Invoice</span>
-          <span>Date</span>
-          <span>Amount</span>
-          <span>Description</span>
-          <span aria-hidden="true" />
-        </div>
-        {[
-          {
-            id: "INV-2024-04",
-            date: "Apr 1, 2025",
-            amount: "$0.00",
-            desc: "Free tier · 9,127 jobs",
-          },
-          {
-            id: "INV-2024-03",
-            date: "Mar 1, 2025",
-            amount: "$0.00",
-            desc: "Free tier · 4,820 jobs",
-          },
-          {
-            id: "INV-2024-02",
-            date: "Feb 1, 2025",
-            amount: "$0.00",
-            desc: "Free tier · 1,602 jobs",
-          },
-        ].map((inv) => (
-          <div
-            key={inv.id}
-            className={`${ST_COLS_5} border-b border-hairline last:border-b-0 transition-colors hover:bg-zebra`}
-          >
-            <div className="font-mono text-[12.5px] text-fg">{inv.id}</div>
-            <div className="text-[12.5px] text-fg-faint">{inv.date}</div>
-            <div className="font-mono text-[12.5px] text-fg">{inv.amount}</div>
-            <div className="text-[12px] text-fg-faint">{inv.desc}</div>
-            <div className="flex justify-end gap-3">
-              <button
-                type="button"
-                className="text-[12px] text-fg-strong transition-colors hover:text-fg"
-              >
-                View
-              </button>
-              <button
-                type="button"
-                className="inline-flex items-center gap-1 text-[12px] text-fg-strong transition-colors hover:text-fg"
-              >
-                <Download className="h-3 w-3" aria-hidden="true" />
-                PDF
-              </button>
-            </div>
+        {accountLoading ? (
+          <div className="animate-pulse p-5">
+            <div className="h-4 w-full rounded bg-white/5" />
           </div>
-        ))}
+        ) : accountState.status === "error" ? (
+          <div className="px-5 py-6 text-center">
+            <p className="text-[13px] text-fg-muted">Could not load invoices.</p>
+            <button
+              type="button"
+              className="mt-2 text-[12.5px] text-fg-strong underline"
+              onClick={() => void reloadAccount()}
+            >
+              Retry
+            </button>
+          </div>
+        ) : invoices.length === 0 ? (
+          <div className="px-5 py-9 text-center">
+            <p className="text-[13.5px] text-fg-muted">No invoices yet.</p>
+          </div>
+        ) : (
+          <>
+            <div className={`${ST_COLS_5} ${ST_HEAD_CLASS}`}>
+              <span>Invoice</span>
+              <span>Date</span>
+              <span>Amount</span>
+              <span>Status</span>
+              <span aria-hidden="true" />
+            </div>
+            {invoices.map((inv) => (
+              <div
+                key={inv.id}
+                className={`${ST_COLS_5} border-b border-hairline last:border-b-0 transition-colors hover:bg-zebra`}
+              >
+                <div className="font-mono text-[12.5px] text-fg">
+                  {inv.number?.trim() || inv.id}
+                </div>
+                <div className="text-[12.5px] text-fg-faint">
+                  {formatInvoiceDate(inv.issuedAt || inv.periodStart)}
+                </div>
+                <div className="font-mono text-[12.5px] text-fg">
+                  {formatInvoiceAmount(inv.totalAmount, inv.currency)}
+                </div>
+                <div className="text-[12px] capitalize text-fg-faint">
+                  {inv.status}
+                </div>
+                <div className="flex justify-end gap-3">
+                  <button
+                    type="button"
+                    className="text-[12px] text-fg-strong transition-colors hover:text-fg disabled:opacity-50"
+                    disabled={invoiceBusyId === inv.id}
+                    onClick={() => void onOpenInvoice(inv.id, "hosted")}
+                  >
+                    View
+                  </button>
+                  <button
+                    type="button"
+                    className="inline-flex items-center gap-1 text-[12px] text-fg-strong transition-colors hover:text-fg disabled:opacity-50"
+                    disabled={invoiceBusyId === inv.id}
+                    onClick={() => void onOpenInvoice(inv.id, "pdf")}
+                  >
+                    <Download className="h-3 w-3" aria-hidden="true" />
+                    PDF
+                  </button>
+                </div>
+              </div>
+            ))}
+          </>
+        )}
       </SettingsCard>
-      </div>
-
-      {/* WIP overlay — sits above the blurred content. Pointer-events-none
-          on the wrapper so the blur layer below stays inert; the notice
-          itself re-enables pointer-events so it's selectable text. */}
-      <div className="pointer-events-none absolute inset-0 flex items-start justify-center pt-24">
-        <div
-          role="status"
-          className="pointer-events-auto max-w-md rounded-md border border-subtle bg-dark-lighter px-6 py-5 text-center shadow-popover"
-        >
-          <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.08em] text-fg-faint">
-            Work in progress
-          </p>
-          <p className="mt-2 text-[15px] font-semibold tracking-[-0.005em] text-fg">
-            Billing UX is not finalized
-          </p>
-          <p className="mt-1.5 text-[13px] leading-[1.5] text-fg-muted">
-            This view is still in flux while we settle on the
-            payment-provider model.
-          </p>
-        </div>
-      </div>
     </div>
   );
 }

From 19deb5703667db65db958c13eeafcedd579976a3 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Thu, 6 Aug 2026 22:37:25 -0400
Subject: [PATCH 05/13] feat(billing): route subscriptions by live state

Keep plan actions aligned with the current PymtHouse subscription so active users change plans or resume checkout instead of creating conflicting subscriptions.
---
 .../pymthouse/subscription/change/route.ts    |  48 ++
 app/api/pymthouse/subscription/route.ts       |  31 ++
 .../dashboard/settings/BillingSection.tsx     | 434 +++++++++++++-----
 .../billing-subscription-state.test.ts        |  35 ++
 lib/dashboard/billing-subscription-state.ts   |  72 +++
 lib/dashboard/pymthouse-billing-bff.ts        | 114 ++++-
 lib/dashboard/useBillingPlans.ts              |  90 +++-
 7 files changed, 685 insertions(+), 139 deletions(-)
 create mode 100644 app/api/pymthouse/subscription/change/route.ts
 create mode 100644 app/api/pymthouse/subscription/route.ts
 create mode 100644 lib/dashboard/billing-subscription-state.test.ts
 create mode 100644 lib/dashboard/billing-subscription-state.ts

diff --git a/app/api/pymthouse/subscription/change/route.ts b/app/api/pymthouse/subscription/change/route.ts
new file mode 100644
index 0000000..3aaf9e9
--- /dev/null
+++ b/app/api/pymthouse/subscription/change/route.ts
@@ -0,0 +1,48 @@
+import { NextRequest, NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+import { changeDashboardBillingSubscription } from "@/lib/dashboard/pymthouse-billing-bff";
+
+export const runtime = "nodejs";
+
+export async function POST(request: NextRequest) {
+  let body: {
+    planId?: string;
+    externalUserId?: string;
+    successUrl?: string;
+    cancelUrl?: string;
+  };
+  try {
+    body = (await request.json()) as typeof body;
+  } catch {
+    return NextResponse.json({ error: "invalid_json" }, { status: 400 });
+  }
+
+  const planId = body.planId?.trim();
+  const externalUserId = body.externalUserId?.trim();
+  if (!planId || !externalUserId) {
+    return NextResponse.json(
+      { error: "planId and externalUserId are required" },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const result = await changeDashboardBillingSubscription({
+      planId,
+      externalUserId,
+      successUrl: body.successUrl?.trim(),
+      cancelUrl: body.cancelUrl?.trim(),
+    });
+    return NextResponse.json(result);
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status }
+      );
+    }
+    const message =
+      error instanceof Error ? error.message : "Failed to change subscription";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
diff --git a/app/api/pymthouse/subscription/route.ts b/app/api/pymthouse/subscription/route.ts
new file mode 100644
index 0000000..728c5b0
--- /dev/null
+++ b/app/api/pymthouse/subscription/route.ts
@@ -0,0 +1,31 @@
+import { NextRequest, NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+import { getDashboardUserSubscription } from "@/lib/dashboard/pymthouse-billing-bff";
+
+export const runtime = "nodejs";
+
+export async function GET(request: NextRequest) {
+  const externalUserId =
+    request.nextUrl.searchParams.get("externalUserId")?.trim() || "";
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const subscription = await getDashboardUserSubscription(externalUserId);
+    return NextResponse.json({ subscription });
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status }
+      );
+    }
+    const message =
+      error instanceof Error ? error.message : "Failed to load subscription";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
diff --git a/components/dashboard/settings/BillingSection.tsx b/components/dashboard/settings/BillingSection.tsx
index 265e271..5ea5e4d 100644
--- a/components/dashboard/settings/BillingSection.tsx
+++ b/components/dashboard/settings/BillingSection.tsx
@@ -1,7 +1,15 @@
 "use client";
 
-import { useState } from "react";
-import { ArrowRight, Box, Check, CreditCard, Download, Plus, Trash2 } from "lucide-react";
+import { useEffect, useState } from "react";
+import {
+  ArrowRight,
+  Box,
+  Check,
+  CreditCard,
+  Download,
+  Plus,
+  Trash2,
+} from "lucide-react";
 import { useAuth } from "@/components/dashboard/AuthContext";
 import {
   IconButton,
@@ -10,11 +18,43 @@ import {
   ST_COLS_5,
   ST_HEAD_CLASS,
 } from "./SettingsPrimitives";
+import { useBillingPlans } from "@/lib/dashboard/useBillingPlans";
 import { useBillingAccount } from "@/lib/dashboard/useBillingAccount";
+import type { DashboardBillingPlan } from "@/lib/dashboard/pymthouse-billing-bff";
+import {
+  billingPlanActionLabel,
+  deriveBillingPlanAction,
+  deriveBillingSubscriptionUiState,
+  isActiveSubscriptionConflict,
+  type BillingPlanAction,
+} from "@/lib/dashboard/billing-subscription-state";
+
+function formatPlanPrice(
+  amount: string,
+  currency: string,
+  cycle: string | null
+): { price: string; priceSub: string } {
+  const n = Number(amount);
+  const money = Number.isFinite(n)
+    ? new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency: currency || "USD",
+        maximumFractionDigits: n % 1 === 0 ? 0 : 2,
+      }).format(n)
+    : amount;
+  const c = cycle?.toLowerCase() ?? "";
+  if (c === "monthly" || c === "month")
+    return { price: money, priceSub: " / month" };
+  if (c === "yearly" || c === "year" || c === "annual") {
+    return { price: money, priceSub: " / year" };
+  }
+  return { price: money, priceSub: cycle ? ` · ${cycle}` : "" };
+}
 
 function formatInvoiceAmount(totalAmount: string, currency: string): string {
   const n = Number(totalAmount);
   if (!Number.isFinite(n)) return `${totalAmount} ${currency}`;
+  // OpenMeter invoice totals are decimal dollar strings (e.g. "2.50").
   return new Intl.NumberFormat("en-US", {
     style: "currency",
     currency: currency || "USD",
@@ -32,16 +72,38 @@ function formatInvoiceDate(iso: string | undefined): string {
   });
 }
 
+function readCheckoutFlash(): "success" | "cancel" | null {
+  if (typeof window === "undefined") return null;
+  const value = new URLSearchParams(window.location.search).get("checkout");
+  if (value === "success" || value === "cancel") return value;
+  return null;
+}
+
+function clearCheckoutQueryParam(): void {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  if (!url.searchParams.has("checkout")) return;
+  url.searchParams.delete("checkout");
+  window.history.replaceState(
+    {},
+    "",
+    `${url.pathname}${url.search}${url.hash}`
+  );
+}
+
 /**
- * Organization · Billing — `?tab=billing` per the v7 prototype.
- *
- * Plan block is static (subscribe flow is a separate WIP).
- * Payment method and invoices are live, wired to useBillingAccount.
+ * Organization · Billing — live plan, payment method, and invoices.
+ * Fake company/tax/address “Billing details” removed (no API).
  */
 export default function BillingSection() {
   const { user } = useAuth();
   const externalUserId = user?.id?.trim();
-
+  const {
+    state: plansState,
+    reload: reloadPlans,
+    subscribe,
+    changePlan,
+  } = useBillingPlans(externalUserId);
   const {
     state: accountState,
     reload: reloadAccount,
@@ -51,10 +113,75 @@ export default function BillingSection() {
     removePaymentMethod,
   } = useBillingAccount(externalUserId);
 
+  const [busyPlanId, setBusyPlanId] = useState<string | null>(null);
   const [pmBusy, setPmBusy] = useState(false);
-  const [paymentMethodActionId, setPaymentMethodActionId] = useState<string | null>(null);
+  const [paymentMethodActionId, setPaymentMethodActionId] = useState<
+    string | null
+  >(null);
   const [invoiceBusyId, setInvoiceBusyId] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const [billingNotice, setBillingNotice] = useState<string | null>(null);
+  const [flash, setFlash] = useState<"success" | "cancel" | null>(null);
+
+  useEffect(() => {
+    const next = readCheckoutFlash();
+    if (!next) return;
+    setFlash(next);
+    clearCheckoutQueryParam();
+    if (next === "success") {
+      void reloadPlans();
+      void reloadAccount();
+    }
+  }, [reloadPlans, reloadAccount]);
+
+  async function onPlanAction(planId: string, action: BillingPlanAction) {
+    if (!externalUserId) {
+      setError("Sign in to subscribe.");
+      return;
+    }
+    if (action === "current") {
+      return;
+    }
+
+    setError(null);
+    setBillingNotice(null);
+    setBusyPlanId(planId);
+    try {
+      const input = {
+        planId:
+          action === "retry_checkout"
+            ? (subscriptionUiState.planId ?? planId)
+            : planId,
+        externalUserId,
+        successUrl: `${window.location.origin}/settings?tab=billing&checkout=success`,
+        cancelUrl: `${window.location.origin}/settings?tab=billing&checkout=cancel`,
+      };
+      const result =
+        action === "change_plan"
+          ? await changePlan(input)
+          : await subscribe(input);
+
+      if (result.checkoutUrl) {
+        window.location.assign(result.checkoutUrl);
+        return;
+      }
+
+      await reloadPlans();
+      setBillingNotice("Your plan has been updated.");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Checkout failed";
+      if (isActiveSubscriptionConflict(message)) {
+        setBillingNotice(
+          "You already have a subscription. Choose another plan to switch, or complete payment for your current plan."
+        );
+        await reloadPlans();
+      } else {
+        setError(message);
+      }
+    } finally {
+      setBusyPlanId(null);
+    }
+  }
 
   async function onAddCard() {
     if (!externalUserId) {
@@ -64,10 +191,14 @@ export default function BillingSection() {
     setError(null);
     setPmBusy(true);
     try {
-      const { checkoutUrl } = await startPaymentMethodCheckout({ externalUserId });
+      const { checkoutUrl } = await startPaymentMethodCheckout({
+        externalUserId,
+      });
       window.location.assign(checkoutUrl);
     } catch (err) {
-      setError(err instanceof Error ? err.message : "Payment method checkout failed");
+      setError(
+        err instanceof Error ? err.message : "Payment method checkout failed"
+      );
       setPmBusy(false);
     }
   }
@@ -100,7 +231,11 @@ export default function BillingSection() {
     try {
       await setDefaultPaymentMethod({ externalUserId, paymentMethodId });
     } catch (err) {
-      setError(err instanceof Error ? err.message : "Could not set default payment method");
+      setError(
+        err instanceof Error
+          ? err.message
+          : "Could not set default payment method"
+      );
     } finally {
       setPaymentMethodActionId(null);
     }
@@ -114,112 +249,141 @@ export default function BillingSection() {
     try {
       await removePaymentMethod({ externalUserId, paymentMethodId });
     } catch (err) {
-      setError(err instanceof Error ? err.message : "Could not remove payment method");
+      setError(
+        err instanceof Error ? err.message : "Could not remove payment method"
+      );
     } finally {
       setPaymentMethodActionId(null);
     }
   }
 
+  const plansLoading =
+    plansState.status === "loading" || plansState.status === "idle";
   const accountLoading =
     accountState.status === "loading" || accountState.status === "idle";
+
+  const plans = plansState.status === "ready" ? plansState.plans : [];
+  const subscription =
+    plansState.status === "ready" ? plansState.subscription : null;
+  const subscriptionUiState = deriveBillingSubscriptionUiState(subscription);
   const paymentMethods =
     accountState.status === "ready" ? accountState.paymentMethods : [];
-  const invoices =
-    accountState.status === "ready" ? accountState.invoices : [];
+  const invoices = accountState.status === "ready" ? accountState.invoices : [];
+
+  const planSub =
+    subscription?.planName?.trim() ||
+    (subscriptionUiState.kind === "pending"
+      ? "Payment needs to be completed"
+      : subscriptionUiState.kind === "active"
+        ? "Current subscription"
+        : "Choose a plan to get started");
 
   return (
     <div>
+      {flash === "success" ? (
+        <p className="mb-4 text-[13px] text-emerald-400">
+          Checkout completed — billing details refreshed.
+        </p>
+      ) : null}
+      {flash === "cancel" ? (
+        <p className="mb-4 text-[13px] text-fg-muted">Checkout canceled.</p>
+      ) : null}
+      {billingNotice ? (
+        <p className="mb-4 text-[13px] text-green-bright" role="status">
+          {billingNotice}
+        </p>
+      ) : null}
       {error ? (
         <p className="mb-4 text-[13px] text-red-400" role="alert">
           {error}
         </p>
       ) : null}
 
-      <SettingsHeader
-        title="Plan"
-        sub="You're on the free tier · 10,000 jobs/month"
-      />
-
+      <SettingsHeader title="Plan" sub={planSub} />
       <SettingsCard>
-        <div className="grid grid-cols-1 md:grid-cols-3">
-          {/* Free — current plan */}
-          <div
-            className="relative border-b border-hairline p-[18px] md:border-b-0 md:border-r"
-            style={{
-              background:
-                "linear-gradient(180deg, rgba(64, 191, 134, 0.06), transparent)",
-            }}
-          >
-            <span
-              className="absolute top-0 bottom-0 left-0 w-[2px] bg-green"
-              aria-hidden="true"
-            />
-            <p className="font-mono text-[10px] uppercase tracking-[0.08em] text-green-bright">
-              Current plan
+        {plansLoading ? (
+          <div className="animate-pulse p-[18px]">
+            <div className="h-4 w-40 rounded bg-white/5" />
+            <div className="mt-3 h-24 rounded bg-white/5" />
+          </div>
+        ) : plansState.status === "error" ? (
+          <div className="p-[18px]">
+            <p className="text-[13px] text-fg-muted">Could not load plans.</p>
+            <p className="mt-1 font-mono text-[12px] text-fg-faint">
+              {plansState.message}
             </p>
-            <p className="mt-1 text-[16px] font-medium text-fg">Free</p>
-            <p className="mt-1 text-[13px] text-fg-strong">
-              <span className="text-[22px] font-medium tracking-[-0.01em] text-fg">
-                $0
-              </span>
-              <span className="text-fg-faint"> / month</span>
+            <button
+              type="button"
+              className="mt-3 text-[12.5px] text-fg-strong underline"
+              onClick={() => void reloadPlans()}
+            >
+              Retry
+            </button>
+          </div>
+        ) : plans.length === 0 ? (
+          <div className="px-5 py-9 text-center">
+            <p className="text-[13.5px] text-fg-muted">
+              No paid plans are published for this app yet.
             </p>
-            <ul className="mt-3.5 flex flex-col gap-1.5">
-              {[
-                "10,000 jobs / month",
-                "3 concurrent streams",
-                "5 GB storage retention",
-                "Community support",
-              ].map((line) => (
-                <li
-                  key={line}
-                  className="flex items-center gap-1.5 text-[12.5px] text-fg-strong"
-                >
-                  <Check
-                    className="h-3 w-3 shrink-0 text-green-bright"
-                    aria-hidden="true"
-                  />
-                  {line}
-                </li>
-              ))}
-            </ul>
           </div>
-
-          <PlanCard
-            name="Pro"
-            price="$29"
-            priceSub=" / month + usage"
-            features={[
-              "Unlimited jobs · pay-as-you-go",
-              "25 concurrent streams",
-              "100 GB storage retention",
-              "Priority support · 24h SLA",
-            ]}
-            cta="Upgrade to Pro"
-          />
-
-          <PlanCard
-            name="Scale"
-            price="Custom"
-            priceSub=" · contact us"
-            features={[
-              "Reserved GPU pools",
-              "Dedicated solutions engineer",
-              "Single-tenant inference",
-              "99.99% SLA",
-            ]}
-            cta="Talk to sales"
-            ctaOutline
-            isLast
-          />
-        </div>
+        ) : (
+          <div className="grid grid-cols-1 md:grid-cols-3">
+            {plans.map((plan, index) => {
+              const action = deriveBillingPlanAction(
+                subscriptionUiState,
+                plan.id
+              );
+              const isCurrent = action === "current";
+              const isPending =
+                subscriptionUiState.kind === "pending" &&
+                subscriptionUiState.planId === plan.id;
+              const { price, priceSub } = formatPlanPrice(
+                plan.priceAmount,
+                plan.priceCurrency,
+                plan.billingCycle
+              );
+              const features = [
+                plan.billingCycle
+                  ? `${plan.billingCycle} billing`
+                  : "Usage-based billing",
+                plan.capabilityCount > 0
+                  ? `${plan.capabilityCount} capabilities`
+                  : "All included capabilities",
+              ];
+              return (
+                <LivePlanCard
+                  key={plan.id}
+                  plan={plan}
+                  price={price}
+                  priceSub={priceSub}
+                  features={features}
+                  isCurrent={isCurrent}
+                  isPending={isPending}
+                  isLast={index === plans.length - 1}
+                  busy={busyPlanId === plan.id}
+                  disabled={
+                    action === "current" ||
+                    !externalUserId ||
+                    busyPlanId !== null
+                  }
+                  action={action}
+                  onSelect={() => void onPlanAction(plan.id, action)}
+                />
+              );
+            })}
+          </div>
+        )}
       </SettingsCard>
 
       <SettingsHeader
         title="Payment method"
         sub="Card on file for subscription and usage charges"
         action={
-          <IconButton primary onClick={() => void onAddCard()} disabled={pmBusy || !externalUserId}>
+          <IconButton
+            primary
+            onClick={() => void onAddCard()}
+            disabled={pmBusy || !externalUserId}
+          >
             <Plus className="h-3 w-3" aria-hidden="true" />
             {pmBusy ? "Starting…" : "Add card"}
           </IconButton>
@@ -263,10 +427,7 @@ export default function BillingSection() {
             {paymentMethods.map((pm) => {
               const isBusy = paymentMethodActionId === pm.id;
               return (
-                <li
-                  key={pm.id}
-                  className="flex items-center gap-3 px-5 py-3.5"
-                >
+                <li key={pm.id} className="flex items-center gap-3 px-5 py-3.5">
                   <CreditCard
                     className="h-4 w-4 shrink-0 text-fg-faint"
                     aria-hidden="true"
@@ -301,7 +462,11 @@ export default function BillingSection() {
                     aria-label={`Remove ${(pm.brand || pm.type || "payment method").toLowerCase()} ending ${pm.last4 ?? ""}`}
                     title="Remove payment method"
                   >
-                    {isBusy ? "…" : <Trash2 className="h-3.5 w-3.5" aria-hidden="true" />}
+                    {isBusy ? (
+                      "…"
+                    ) : (
+                      <Trash2 className="h-3.5 w-3.5" aria-hidden="true" />
+                    )}
                   </button>
                 </li>
               );
@@ -318,7 +483,9 @@ export default function BillingSection() {
           </div>
         ) : accountState.status === "error" ? (
           <div className="px-5 py-6 text-center">
-            <p className="text-[13px] text-fg-muted">Could not load invoices.</p>
+            <p className="text-[13px] text-fg-muted">
+              Could not load invoices.
+            </p>
             <button
               type="button"
               className="mt-2 text-[12.5px] text-fg-strong underline"
@@ -385,30 +552,67 @@ export default function BillingSection() {
   );
 }
 
-function PlanCard({
-  name,
+function LivePlanCard({
+  plan,
   price,
   priceSub,
   features,
-  cta,
-  ctaOutline = false,
-  isLast = false,
+  isCurrent,
+  isPending,
+  isLast,
+  busy,
+  disabled,
+  action,
+  onSelect,
 }: {
-  name: string;
+  plan: DashboardBillingPlan;
   price: string;
   priceSub: string;
   features: string[];
-  cta: string;
-  ctaOutline?: boolean;
-  isLast?: boolean;
+  isCurrent: boolean;
+  isPending: boolean;
+  isLast: boolean;
+  busy: boolean;
+  disabled: boolean;
+  action: BillingPlanAction;
+  onSelect: () => void;
 }) {
+  const isHighlighted = isCurrent || isPending;
   return (
     <div
-      className={`p-[18px] ${
-        isLast ? "border-b-0" : "border-b border-hairline md:border-b-0"
-      } ${isLast ? "" : "md:border-r border-hairline"}`}
+      className={`relative p-[18px] ${
+        isLast ? "" : "border-b border-hairline md:border-b-0 md:border-r"
+      }`}
+      style={
+        isHighlighted
+          ? {
+              background:
+                "linear-gradient(180deg, rgba(64, 191, 134, 0.06), transparent)",
+            }
+          : undefined
+      }
     >
-      <p className="text-[16px] font-medium text-fg">{name}</p>
+      {isHighlighted ? (
+        <span
+          className="absolute top-0 bottom-0 left-0 w-[2px] bg-green"
+          aria-hidden="true"
+        />
+      ) : null}
+      {isCurrent ? (
+        <p className="font-mono text-[10px] uppercase tracking-[0.08em] text-green-bright">
+          Current plan
+        </p>
+      ) : null}
+      {isPending ? (
+        <p className="font-mono text-[10px] uppercase tracking-[0.08em] text-amber-300">
+          Payment pending
+        </p>
+      ) : null}
+      <p
+        className={`text-[16px] font-medium text-fg ${isHighlighted ? "mt-1" : ""}`}
+      >
+        {plan.name}
+      </p>
       <p className="mt-1 text-[13px] text-fg-strong">
         <span className="text-[22px] font-medium tracking-[-0.01em] text-fg">
           {price}
@@ -431,16 +635,18 @@ function PlanCard({
       </ul>
       <button
         type="button"
-        className={`mt-4 inline-flex h-7 items-center gap-1 rounded-[4px] border px-3 text-[12.5px] font-medium transition-colors ${
-          ctaOutline
-            ? "border-subtle bg-transparent text-fg hover:bg-hover"
+        disabled={disabled}
+        onClick={onSelect}
+        className={`mt-4 inline-flex h-7 items-center gap-1 rounded-[4px] border px-3 text-[12.5px] font-medium transition-colors disabled:opacity-50 ${
+          action === "current"
+            ? "border-subtle bg-transparent text-fg-muted"
             : "btn-primary"
         }`}
       >
-        {cta}
-        {!ctaOutline && (
+        {busy ? "Working…" : billingPlanActionLabel(action)}
+        {action !== "current" && !busy ? (
           <ArrowRight className="h-2.5 w-2.5" aria-hidden="true" />
-        )}
+        ) : null}
       </button>
     </div>
   );
diff --git a/lib/dashboard/billing-subscription-state.test.ts b/lib/dashboard/billing-subscription-state.test.ts
new file mode 100644
index 0000000..2e4bc9a
--- /dev/null
+++ b/lib/dashboard/billing-subscription-state.test.ts
@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  deriveBillingPlanAction,
+  deriveBillingSubscriptionUiState,
+} from "./billing-subscription-state";
+
+test("derives no subscription as a subscribe state", () => {
+  const state = deriveBillingSubscriptionUiState(null);
+
+  assert.deepEqual(state, { kind: "none", planId: null });
+  assert.equal(deriveBillingPlanAction(state, "pro"), "subscribe");
+});
+
+test("marks the active plan current and other plans switchable", () => {
+  const state = deriveBillingSubscriptionUiState({
+    planId: "pro",
+    status: "active",
+  });
+
+  assert.deepEqual(state, { kind: "active", planId: "pro" });
+  assert.equal(deriveBillingPlanAction(state, "pro"), "current");
+  assert.equal(deriveBillingPlanAction(state, "scale"), "change_plan");
+});
+
+test("routes pending subscriptions to checkout retry", () => {
+  const state = deriveBillingSubscriptionUiState({
+    planId: "pro",
+    status: "pending",
+  });
+
+  assert.deepEqual(state, { kind: "pending", planId: "pro" });
+  assert.equal(deriveBillingPlanAction(state, "pro"), "retry_checkout");
+  assert.equal(deriveBillingPlanAction(state, "scale"), "retry_checkout");
+});
diff --git a/lib/dashboard/billing-subscription-state.ts b/lib/dashboard/billing-subscription-state.ts
new file mode 100644
index 0000000..68a477d
--- /dev/null
+++ b/lib/dashboard/billing-subscription-state.ts
@@ -0,0 +1,72 @@
+export type BillingSubscriptionSnapshot = {
+  planId: string | null;
+  status: string | null;
+};
+
+export type BillingSubscriptionUiState =
+  | { kind: "none"; planId: null }
+  | { kind: "active"; planId: string }
+  | { kind: "pending"; planId: string };
+
+export type BillingPlanAction =
+  | "subscribe"
+  | "change_plan"
+  | "retry_checkout"
+  | "current";
+
+const ACTIVE_STATUSES = new Set(["active", "trialing", "scheduled"]);
+const PENDING_STATUSES = new Set([
+  "pending",
+  "incomplete",
+  "incomplete_expired",
+  "checkout_pending",
+]);
+
+export function deriveBillingSubscriptionUiState(
+  subscription: BillingSubscriptionSnapshot | null | undefined
+): BillingSubscriptionUiState {
+  const planId = subscription?.planId?.trim() || null;
+  if (!planId) {
+    return { kind: "none", planId: null };
+  }
+
+  const status = subscription?.status?.trim().toLowerCase() || "";
+  if (PENDING_STATUSES.has(status)) {
+    return { kind: "pending", planId };
+  }
+  if (ACTIVE_STATUSES.has(status)) {
+    return { kind: "active", planId };
+  }
+
+  return { kind: "none", planId: null };
+}
+
+export function deriveBillingPlanAction(
+  subscription: BillingSubscriptionUiState,
+  planId: string
+): BillingPlanAction {
+  if (subscription.kind === "none") {
+    return "subscribe";
+  }
+  if (subscription.kind === "pending") {
+    return "retry_checkout";
+  }
+  return subscription.planId === planId ? "current" : "change_plan";
+}
+
+export function billingPlanActionLabel(action: BillingPlanAction): string {
+  switch (action) {
+    case "current":
+      return "Current plan";
+    case "change_plan":
+      return "Switch";
+    case "retry_checkout":
+      return "Complete payment";
+    case "subscribe":
+      return "Subscribe";
+  }
+}
+
+export function isActiveSubscriptionConflict(message: string): boolean {
+  return /already has an active subscription/i.test(message);
+}
diff --git a/lib/dashboard/pymthouse-billing-bff.ts b/lib/dashboard/pymthouse-billing-bff.ts
index 41a06b1..ee4f7ad 100644
--- a/lib/dashboard/pymthouse-billing-bff.ts
+++ b/lib/dashboard/pymthouse-billing-bff.ts
@@ -17,12 +17,68 @@ function readPublicClientId(): string {
   if (!id) {
     throw new PmtHouseError(
       "PYMTHOUSE_PUBLIC_CLIENT_ID (or DASHBOARD_DEVICE_PUBLIC_CLIENT_ID) is required",
-      { status: 503, code: "pymthouse_required" },
+      { status: 503, code: "pymthouse_required" }
     );
   }
   return id;
 }
 
+function readM2mAuthHeader(): string {
+  const clientId = process.env.PYMTHOUSE_M2M_CLIENT_ID?.trim();
+  const clientSecret = process.env.PYMTHOUSE_M2M_CLIENT_SECRET?.trim();
+  if (!clientId || !clientSecret) {
+    throw new PmtHouseError(
+      "PYMTHOUSE_M2M_CLIENT_ID and PYMTHOUSE_M2M_CLIENT_SECRET are required",
+      { status: 503, code: "pymthouse_required" }
+    );
+  }
+  return `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`;
+}
+
+function pymthouseAppsOrigin(): string {
+  const issuerUrl = process.env.PYMTHOUSE_ISSUER_URL?.trim();
+  if (!issuerUrl) {
+    throw new PmtHouseError("PYMTHOUSE_ISSUER_URL is required", {
+      status: 503,
+      code: "pymthouse_required",
+    });
+  }
+  return issuerUrl.replace(/\/api\/v1\/oidc\/?$/i, "");
+}
+
+async function readPymthouseResponse<T>(response: Response): Promise<T> {
+  const text = await response.text();
+  let body: (T & { error?: string }) | null = null;
+  try {
+    body = text ? (JSON.parse(text) as T & { error?: string }) : null;
+  } catch {
+    throw new PmtHouseError(
+      `PymtHouse returned non-JSON (${response.status})`,
+      {
+        status: 502,
+        code: "invalid_json",
+      }
+    );
+  }
+  if (!response.ok) {
+    throw new PmtHouseError(
+      body?.error ?? `Request failed (${response.status})`,
+      {
+        status: response.status,
+        code: "subscription_change_failed",
+        details: body ?? undefined,
+      }
+    );
+  }
+  if (!body) {
+    throw new PmtHouseError("PymtHouse returned an empty response", {
+      status: 502,
+      code: "invalid_response",
+    });
+  }
+  return body;
+}
+
 export type DashboardBillingPlan = {
   id: string;
   name: string;
@@ -48,15 +104,14 @@ function mapProduct(product: BillingProduct): DashboardBillingPlan {
 }
 
 /** Active (non-starter / non-network-default) products available for subscribe. */
-export async function listDashboardBillingPlans(): Promise<DashboardBillingPlan[]> {
+export async function listDashboardBillingPlans(): Promise<
+  DashboardBillingPlan[]
+> {
   const client = createPmtHouseClientForPublicApp(readPublicClientId());
   const { products } = await client.listBillingProducts();
   return (products ?? [])
     .filter(
-      (p) =>
-        p.status === "active" &&
-        !p.isNetworkDefault &&
-        !p.isStarterDefault,
+      (p) => p.status === "active" && !p.isNetworkDefault && !p.isStarterDefault
     )
     .map(mapProduct);
 }
@@ -76,6 +131,41 @@ export async function startDashboardBillingCheckout(input: {
   });
 }
 
+export type DashboardSubscriptionChange = {
+  subscriptionId: string;
+  planId: string;
+  effectiveAt: string | null;
+  timing: "immediate" | "next_billing_cycle";
+  checkoutUrl?: string;
+};
+
+export async function changeDashboardBillingSubscription(input: {
+  planId: string;
+  externalUserId: string;
+  successUrl?: string;
+  cancelUrl?: string;
+}): Promise<DashboardSubscriptionChange> {
+  const publicClientId = readPublicClientId();
+  const response = await fetch(
+    `${pymthouseAppsOrigin()}/api/v1/apps/${encodeURIComponent(publicClientId)}/users/${encodeURIComponent(input.externalUserId)}/subscription/change`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: readM2mAuthHeader(),
+        Accept: "application/json",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        planId: input.planId,
+        ...(input.successUrl ? { successUrl: input.successUrl } : {}),
+        ...(input.cancelUrl ? { cancelUrl: input.cancelUrl } : {}),
+      }),
+      cache: "no-store",
+    }
+  );
+  return readPymthouseResponse<DashboardSubscriptionChange>(response);
+}
+
 export type DashboardUserSubscription = {
   planId: string | null;
   planName: string | null;
@@ -84,7 +174,7 @@ export type DashboardUserSubscription = {
 };
 
 export async function getDashboardUserSubscription(
-  externalUserId: string,
+  externalUserId: string
 ): Promise<DashboardUserSubscription> {
   const client = createPmtHouseClientForPublicApp(readPublicClientId());
   const result: UserSubscriptionResponse =
@@ -103,7 +193,7 @@ export type DashboardPaymentMethod = AppUserPaymentMethod;
 
 export async function listDashboardUserInvoices(
   externalUserId: string,
-  opts?: { page?: number; pageSize?: number },
+  opts?: { page?: number; pageSize?: number }
 ): Promise<{
   items: DashboardInvoice[];
   page: number;
@@ -116,14 +206,14 @@ export async function listDashboardUserInvoices(
 
 export async function getDashboardUserInvoiceHostedUrl(
   externalUserId: string,
-  invoiceId: string,
+  invoiceId: string
 ): Promise<AppUserInvoiceHostedUrlResult> {
   const client = createPmtHouseClientForPublicApp(readPublicClientId());
   return client.getUserInvoiceHostedUrl(externalUserId, invoiceId);
 }
 
 export async function listDashboardUserPaymentMethods(
-  externalUserId: string,
+  externalUserId: string
 ): Promise<DashboardPaymentMethod[]> {
   const client = createPmtHouseClientForPublicApp(readPublicClientId());
   const result = await client.listUserPaymentMethods(externalUserId);
@@ -145,7 +235,7 @@ export async function startDashboardPaymentMethodCheckout(input: {
 
 export async function setDashboardUserDefaultPaymentMethod(
   externalUserId: string,
-  paymentMethodId: string,
+  paymentMethodId: string
 ) {
   const client = createPmtHouseClientForPublicApp(readPublicClientId());
   return client.setUserDefaultPaymentMethod(externalUserId, paymentMethodId);
@@ -153,7 +243,7 @@ export async function setDashboardUserDefaultPaymentMethod(
 
 export async function removeDashboardUserPaymentMethod(
   externalUserId: string,
-  paymentMethodId: string,
+  paymentMethodId: string
 ) {
   const client = createPmtHouseClientForPublicApp(readPublicClientId());
   return client.unlinkUserPaymentMethod(externalUserId, paymentMethodId);
diff --git a/lib/dashboard/useBillingPlans.ts b/lib/dashboard/useBillingPlans.ts
index 37c1b62..ef54da7 100644
--- a/lib/dashboard/useBillingPlans.ts
+++ b/lib/dashboard/useBillingPlans.ts
@@ -1,12 +1,19 @@
 "use client";
 
 import { useCallback, useEffect, useState } from "react";
-import type { DashboardBillingPlan } from "@/lib/dashboard/pymthouse-billing-bff";
+import type {
+  DashboardBillingPlan,
+  DashboardUserSubscription,
+} from "@/lib/dashboard/pymthouse-billing-bff";
 
 export type BillingPlansState =
   | { status: "idle" }
   | { status: "loading" }
-  | { status: "ready"; plans: DashboardBillingPlan[] }
+  | {
+      status: "ready";
+      plans: DashboardBillingPlan[];
+      subscription: DashboardUserSubscription | null;
+    }
   | { status: "error"; message: string };
 
 async function readResponseJson<T>(response: Response): Promise<T> {
@@ -21,21 +28,43 @@ async function readResponseJson<T>(response: Response): Promise<T> {
   }
 }
 
-export function useBillingPlans() {
+export function useBillingPlans(externalUserId: string | undefined) {
   const [state, setState] = useState<BillingPlansState>({ status: "idle" });
 
   const load = useCallback(async () => {
     setState({ status: "loading" });
     try {
-      const response = await fetch("/api/pymthouse/plans");
-      const body = await readResponseJson<{
+      const plansResponse = await fetch("/api/pymthouse/plans");
+      const plansBody = await readResponseJson<{
         plans?: DashboardBillingPlan[];
         error?: string;
-      }>(response);
-      if (!response.ok) {
-        throw new Error(body.error ?? `Plans fetch failed (${response.status})`);
+      }>(plansResponse);
+      if (!plansResponse.ok) {
+        throw new Error(
+          plansBody.error ?? `Plans fetch failed (${plansResponse.status})`
+        );
       }
-      setState({ status: "ready", plans: body.plans ?? [] });
+
+      let subscription: DashboardUserSubscription | null = null;
+      const trimmedUserId = externalUserId?.trim();
+      if (trimmedUserId) {
+        const subResponse = await fetch(
+          `/api/pymthouse/subscription?externalUserId=${encodeURIComponent(trimmedUserId)}`
+        );
+        const subBody = await readResponseJson<{
+          subscription?: DashboardUserSubscription;
+          error?: string;
+        }>(subResponse);
+        if (subResponse.ok) {
+          subscription = subBody.subscription ?? null;
+        }
+      }
+
+      setState({
+        status: "ready",
+        plans: plansBody.plans ?? [],
+        subscription,
+      });
     } catch (error) {
       setState({
         status: "error",
@@ -43,14 +72,19 @@ export function useBillingPlans() {
           error instanceof Error ? error.message : "Failed to load plans",
       });
     }
-  }, []);
+  }, [externalUserId]);
 
   useEffect(() => {
     void load();
   }, [load]);
 
   const subscribe = useCallback(
-    async (input: { planId: string; externalUserId: string }) => {
+    async (input: {
+      planId: string;
+      externalUserId: string;
+      successUrl?: string;
+      cancelUrl?: string;
+    }) => {
       const response = await fetch("/api/pymthouse/subscribe", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -69,8 +103,38 @@ export function useBillingPlans() {
         subscriptionId: body.subscriptionId,
       };
     },
-    [],
+    []
+  );
+
+  const changePlan = useCallback(
+    async (input: {
+      planId: string;
+      externalUserId: string;
+      successUrl?: string;
+      cancelUrl?: string;
+    }) => {
+      const response = await fetch("/api/pymthouse/subscription/change", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+      });
+      const body = await readResponseJson<{
+        checkoutUrl?: string;
+        subscriptionId?: string;
+        error?: string;
+      }>(response);
+      if (!response.ok) {
+        throw new Error(
+          body.error ?? `Plan change failed (${response.status})`
+        );
+      }
+      return {
+        checkoutUrl: body.checkoutUrl,
+        subscriptionId: body.subscriptionId,
+      };
+    },
+    []
   );
 
-  return { state, reload: load, subscribe };
+  return { state, reload: load, subscribe, changePlan };
 }

From bbb83853339520d4a9c9478b5b13c18c2045d83a Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Sat, 8 Aug 2026 00:07:53 -0400
Subject: [PATCH 06/13] fix(usage): validate account-usage payloads instead of
 casting them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

useAccountUsage cast every 200 body straight to AccountUsagePayload, so a
malformed response became a value that lied about its type. Consumers then
dereferenced `period.end` and ran BigInt reads over `current`/`balance` and
threw during render — a broken upstream body surfaced as a crashed page
rather than as the error state the hook already has.

Responses are now shape-checked at runtime and malformed bodies route to
that existing error state. The guard covers only the fields consumers
dereference without a fallback; `clientId` and `priorPeriod` are carried by
the type but never read, so they are deliberately unchecked. Error messages
on non-OK responses are likewise read without trusting the body shape.
---
 lib/dashboard/account-usage-payload.test.ts | 117 ++++++++++++++++++++
 lib/dashboard/account-usage-payload.ts      |  89 +++++++++++++++
 lib/dashboard/useAccountUsage.ts            |  15 ++-
 3 files changed, 217 insertions(+), 4 deletions(-)
 create mode 100644 lib/dashboard/account-usage-payload.test.ts
 create mode 100644 lib/dashboard/account-usage-payload.ts

diff --git a/lib/dashboard/account-usage-payload.test.ts b/lib/dashboard/account-usage-payload.test.ts
new file mode 100644
index 0000000..4a73b46
--- /dev/null
+++ b/lib/dashboard/account-usage-payload.test.ts
@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { errorMessageFromBody, isAccountUsagePayload } from "./account-usage-payload";
+
+function validPayload(): Record<string, unknown> {
+  return {
+    clientId: "app_dashboard",
+    period: { start: "2026-07-08T00:00:00.000Z", end: "2026-08-07T00:00:00.000Z" },
+    periodDayKeys: ["2026-08-06", "2026-08-07"],
+    priorPeriod: { start: "2026-06-08T00:00:00.000Z", end: "2026-07-08T00:00:00.000Z" },
+    balance: null,
+    current: {
+      requestCount: 3,
+      networkFeeUsdMicros: "1200",
+      endUserBillableUsdMicros: "2400",
+      pipelineModels: [
+        {
+          pipeline: "text-to-image",
+          modelId: "sd-3",
+          requestCount: 3,
+          networkFeeUsdMicros: "1200",
+          endUserBillableUsdMicros: "2400",
+          dailyRequests: [1, 2],
+        },
+      ],
+      dailyByPipeline: [
+        {
+          pipeline: "text-to-image",
+          modelId: "sd-3",
+          date: "2026-08-07",
+          requestCount: 2,
+          networkFeeUsdMicros: "800",
+        },
+      ],
+    },
+    prior: { requestCount: 1, pipelineModels: [] },
+  };
+}
+
+test("accepts a well-formed payload, with or without a balance", () => {
+  assert.equal(isAccountUsagePayload(validPayload()), true);
+
+  const withBalance = validPayload();
+  withBalance.balance = {
+    externalUserId: "95c33c7d-8951-4d9f-8c7f-3a589a4e4adc",
+    balanceUsdMicros: "500000",
+    consumedUsdMicros: "500000",
+    lifetimeGrantedUsdMicros: "1000000",
+    hasAccess: true,
+  };
+  assert.equal(isAccountUsagePayload(withBalance), true);
+});
+
+test("rejects bodies that aren't a payload object at all", () => {
+  // The stub that crashed the sidebar in the browser.
+  assert.equal(isAccountUsagePayload({}), false);
+  assert.equal(isAccountUsagePayload(null), false);
+  assert.equal(isAccountUsagePayload(undefined), false);
+  assert.equal(isAccountUsagePayload([validPayload()]), false);
+  assert.equal(isAccountUsagePayload("ok"), false);
+});
+
+test("rejects a payload missing only period, or with an unusable period", () => {
+  const noPeriod = validPayload();
+  delete noPeriod.period;
+  assert.equal(isAccountUsagePayload(noPeriod), false);
+
+  const noEnd = validPayload();
+  noEnd.period = { start: "2026-07-08T00:00:00.000Z" };
+  assert.equal(isAccountUsagePayload(noEnd), false);
+
+  const nullEnd = validPayload();
+  nullEnd.period = { start: "2026-07-08T00:00:00.000Z", end: null };
+  assert.equal(isAccountUsagePayload(nullEnd), false);
+});
+
+test("rejects scopes whose BigInt/array reads would throw during render", () => {
+  const noMicros = validPayload();
+  noMicros.current = { ...(validPayload().current as object), endUserBillableUsdMicros: 2400 };
+  assert.equal(isAccountUsagePayload(noMicros), false);
+
+  const noRows = validPayload();
+  noRows.current = { ...(validPayload().current as object), pipelineModels: null };
+  assert.equal(isAccountUsagePayload(noRows), false);
+
+  const rowWithoutSeries = validPayload();
+  rowWithoutSeries.current = {
+    ...(validPayload().current as object),
+    pipelineModels: [{ pipeline: "text-to-image", modelId: "sd-3", requestCount: 3 }],
+  };
+  assert.equal(isAccountUsagePayload(rowWithoutSeries), false);
+
+  const noPrior = validPayload();
+  delete noPrior.prior;
+  assert.equal(isAccountUsagePayload(noPrior), false);
+
+  const noDayKeys = validPayload();
+  noDayKeys.periodDayKeys = undefined;
+  assert.equal(isAccountUsagePayload(noDayKeys), false);
+});
+
+test("rejects a partial balance but allows an explicit null", () => {
+  const partialBalance = validPayload();
+  partialBalance.balance = { balanceUsdMicros: "500000", hasAccess: true };
+  assert.equal(isAccountUsagePayload(partialBalance), false);
+
+  const undefinedBalance = validPayload();
+  undefinedBalance.balance = undefined;
+  assert.equal(isAccountUsagePayload(undefinedBalance), false);
+});
+
+test("errorMessageFromBody only trusts a string error field", () => {
+  assert.equal(errorMessageFromBody({ error: "upstream down" }), "upstream down");
+  assert.equal(errorMessageFromBody({ error: { code: 500 } }), null);
+  assert.equal(errorMessageFromBody("upstream down"), null);
+  assert.equal(errorMessageFromBody(null), null);
+});
diff --git a/lib/dashboard/account-usage-payload.ts b/lib/dashboard/account-usage-payload.ts
new file mode 100644
index 0000000..2c1739e
--- /dev/null
+++ b/lib/dashboard/account-usage-payload.ts
@@ -0,0 +1,89 @@
+import type { AccountUsagePayload } from "@/lib/dashboard/pymthouse-bff";
+
+/**
+ * Runtime shape check for `/api/pymthouse/account-usage` responses.
+ *
+ * A 200 with a body that doesn't match `AccountUsagePayload` used to reach the
+ * consumers as a well-typed value, so `data.period.end` (and the BigInt reads on
+ * `current`/`balance`) threw during render. Covers the fields the consumers
+ * dereference without a fallback — `clientId` and `priorPeriod` are carried by
+ * the type but nothing reads them, so they're deliberately not checked.
+ */
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isPeriodBounds(value: unknown): boolean {
+  return isRecord(value) && typeof value.start === "string" && typeof value.end === "string";
+}
+
+/** `balance` is legitimately null when the account has no prepaid grant. */
+function isBalance(value: unknown): boolean {
+  return (
+    value === null ||
+    (isRecord(value) &&
+      typeof value.balanceUsdMicros === "string" &&
+      typeof value.consumedUsdMicros === "string" &&
+      typeof value.lifetimeGrantedUsdMicros === "string" &&
+      typeof value.hasAccess === "boolean")
+  );
+}
+
+function isPipelineRow(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.pipeline === "string" &&
+    typeof value.modelId === "string" &&
+    typeof value.requestCount === "number" &&
+    Array.isArray(value.dailyRequests)
+  );
+}
+
+function isDailyPipelineRow(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.pipeline === "string" &&
+    typeof value.modelId === "string" &&
+    typeof value.date === "string" &&
+    typeof value.requestCount === "number"
+  );
+}
+
+function isCurrentScope(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.requestCount === "number" &&
+    typeof value.networkFeeUsdMicros === "string" &&
+    typeof value.endUserBillableUsdMicros === "string" &&
+    Array.isArray(value.pipelineModels) &&
+    value.pipelineModels.every(isPipelineRow) &&
+    Array.isArray(value.dailyByPipeline) &&
+    value.dailyByPipeline.every(isDailyPipelineRow)
+  );
+}
+
+function isPriorScope(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.requestCount === "number" &&
+    Array.isArray(value.pipelineModels) &&
+    value.pipelineModels.every(isPipelineRow)
+  );
+}
+
+export function isAccountUsagePayload(value: unknown): value is AccountUsagePayload {
+  return (
+    isRecord(value) &&
+    isPeriodBounds(value.period) &&
+    Array.isArray(value.periodDayKeys) &&
+    isBalance(value.balance) &&
+    isCurrentScope(value.current) &&
+    isPriorScope(value.prior)
+  );
+}
+
+/** Reads the `{ error }` field off a non-OK body without trusting its shape. */
+export function errorMessageFromBody(value: unknown): string | null {
+  return isRecord(value) && typeof value.error === "string" ? value.error : null;
+}
diff --git a/lib/dashboard/useAccountUsage.ts b/lib/dashboard/useAccountUsage.ts
index e82e30a..bc574c9 100644
--- a/lib/dashboard/useAccountUsage.ts
+++ b/lib/dashboard/useAccountUsage.ts
@@ -1,6 +1,10 @@
 "use client";
 
 import { useCallback, useEffect, useState } from "react";
+import {
+  errorMessageFromBody,
+  isAccountUsagePayload,
+} from "@/lib/dashboard/account-usage-payload";
 import type { AccountUsagePayload } from "@/lib/dashboard/pymthouse-bff";
 
 export type AccountUsageState =
@@ -56,11 +60,14 @@ export function useAccountUsage(
       const response = await fetch(`/api/pymthouse/account-usage?${params}`, {
         cache: "no-store",
       });
-      const body = (await response.json()) as AccountUsagePayload & {
-        error?: string;
-      };
+      const body: unknown = await response.json();
       if (!response.ok) {
-        throw new Error(body.error ?? `Usage fetch failed (${response.status})`);
+        throw new Error(
+          errorMessageFromBody(body) ?? `Usage fetch failed (${response.status})`,
+        );
+      }
+      if (!isAccountUsagePayload(body)) {
+        throw new Error("Usage response was malformed.");
       }
       setState({ status: "ready", data: body });
     } catch (error) {

From c4a5c1fe26a9d2b04b52882c034c0eb20c387427 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Sat, 8 Aug 2026 00:08:04 -0400
Subject: [PATCH 07/13] refactor(keys): resolve the signer URL from issuer
 routing, not dashboard env
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The dashboard kept its own copy of the signer DMZ base in
PYMTHOUSE_SIGNER_URL (plus two aliases) and used it as a fallback whenever
the issuer did not return signer_url. That made the dashboard a second
source of truth for a value the issuer already owns, so a signer move meant
redeploying the dashboard to stay reachable.

The issuer is now the only source: API-key exchange takes signer_url from
the exchange response, and signer sessions resolve it from
GET …/apps/{clientId}/signer/routing, cached for five minutes so the
routing lookup does not add a round trip per session. Locally built
python-gateway --token bundles are dropped in favour of the issuer-built
sdkToken, which already carries the routing. PYMTHOUSE_SIGNER_URL is
removed from .env.example accordingly.

Key creation also no longer reloads the list mid-flight: the caller inserts
the new row and reveals the full key in the same paint, then soft-refreshes,
so a slow list fetch cannot delay or blank the reveal.
---
 .env.example                             | 14 ++--
 app/api/pymthouse/keys/exchange/route.ts | 11 +---
 components/dashboard/KeysView.tsx        | 81 ++++++++++++++++++++----
 lib/dashboard/pymthouse-keys-bff.ts      | 35 +---------
 lib/dashboard/signer-session-bff.ts      | 60 +++++++++++++-----
 lib/dashboard/useApiKeys.ts              | 27 ++++----
 6 files changed, 140 insertions(+), 88 deletions(-)

diff --git a/.env.example b/.env.example
index 83bf232..1b4fb8e 100644
--- a/.env.example
+++ b/.env.example
@@ -9,17 +9,15 @@ DISCOVERY_SERVICE_URL=https://discovery-service-production-8955.up.railway.app/v
 # PymtHouse (usage + API keys + signer sessions + plans/subscribe)
 # Production:
 PYMTHOUSE_ISSUER_URL=https://pymthouse.com/api/v1/oidc
-# Local pymthouse: http://localhost:3001/api/v1/oidc
-# Public app client id (OAuth client_id) — used for Builder API path {clientId}
+# Local pymthouse (`npm run dev` HTTPS): https://localhost:3001/api/v1/oidc
+# (mkcert is trusted in the browser; Node fetch to localhost HTTPS usually works
+# without PYMTHOUSE_ALLOW_INSECURE_HTTP when using the system/mkcert CA.)
 PYMTHOUSE_PUBLIC_CLIENT_ID=
 PYMTHOUSE_M2M_CLIENT_ID=
 PYMTHOUSE_M2M_CLIENT_SECRET=
-# Remote signer DMZ base included as signer_url in API-key exchange responses
-# (fallback when the issuer does not return signer_url).
-# Production: https://pymthouse-production.up.railway.app
-# Local compose: http://127.0.0.1:8080
-PYMTHOUSE_SIGNER_URL=https://pymthouse-production.up.railway.app
-# Set to 1 for local dev when issuer uses http://127.0.0.1
+# Signer DMZ URL is returned by issuer exchange / GET …/apps/{id}/signer/routing
+# — do not set PYMTHOUSE_SIGNER_URL on the dashboard.
+# Set to 1 for local http issuer only (not needed for https://localhost with mkcert)
 PYMTHOUSE_ALLOW_INSECURE_HTTP=
 
 # Live-runner discovery (orchestrator /discovery endpoint).
diff --git a/app/api/pymthouse/keys/exchange/route.ts b/app/api/pymthouse/keys/exchange/route.ts
index 0352729..53a71a0 100644
--- a/app/api/pymthouse/keys/exchange/route.ts
+++ b/app/api/pymthouse/keys/exchange/route.ts
@@ -12,7 +12,6 @@ type ExchangeConfig = {
   publicClientId: string;
   m2mClientId: string;
   m2mClientSecret: string;
-  signerUrl: string | undefined;
 };
 
 /** Thin BFF; canonical issuer route is POST …/apps/{clientId}/oidc/token (RFC 8693). */
@@ -24,17 +23,11 @@ function readApiKeyExchangeConfig(): ExchangeConfig | null {
   if (!issuerUrl || !publicClientId) {
     return null;
   }
-  const signerUrl =
-    process.env.PYMTHOUSE_CLIENT_SIGNER_API_URL?.trim() ||
-    process.env.PYMTHOUSE_SIGNER_URL?.trim() ||
-    process.env.SIGNER_PUBLIC_URL?.trim() ||
-    undefined;
   return {
     issuerUrl,
     publicClientId,
     m2mClientId: process.env.PYMTHOUSE_M2M_CLIENT_ID?.trim() ?? "",
     m2mClientSecret: process.env.PYMTHOUSE_M2M_CLIENT_SECRET?.trim() ?? "",
-    signerUrl,
   };
 }
 
@@ -114,8 +107,8 @@ async function exchangeApiKeyViaOidcToken(input: {
     });
   }
 
-  const signerUrl =
-    readStringField(parsed, "signer_url") || config.signerUrl || undefined;
+  // signer_url comes from the issuer exchange response (app signer routing).
+  const signerUrl = readStringField(parsed, "signer_url");
 
   const expiresIn =
     typeof parsed.expires_in === "number" && Number.isFinite(parsed.expires_in)
diff --git a/components/dashboard/KeysView.tsx b/components/dashboard/KeysView.tsx
index f02c790..e8db12a 100644
--- a/components/dashboard/KeysView.tsx
+++ b/components/dashboard/KeysView.tsx
@@ -157,6 +157,43 @@ function RevealedCredential({
   );
 }
 
+/** Masked table token — single mono string so prefix/ellipsis/suffix never drift. */
+function MaskedToken({
+  prefix,
+  suffix,
+}: {
+  prefix: string;
+  suffix: string;
+}) {
+  const masked = `${prefix}…${suffix}`;
+  return (
+    <div
+      className="mt-1 truncate font-mono text-[11.5px] tracking-tight text-fg-faint"
+      title={masked}
+    >
+      {masked}
+    </div>
+  );
+}
+
+function KeysTableSkeletonRow() {
+  return (
+    <div
+      className="grid grid-cols-[2.4fr_1.1fr_1.2fr_36px] items-center gap-3 border-b border-hairline px-4 py-3.5"
+      aria-busy="true"
+      aria-label="Creating API key"
+    >
+      <div className="min-w-0 space-y-1.5">
+        <div className="h-3.5 w-[7.5rem] animate-pulse rounded bg-hover" />
+        <div className="h-3 w-[11rem] animate-pulse rounded bg-hover/70 font-mono" />
+      </div>
+      <div className="h-5 w-[4.25rem] animate-pulse rounded-full bg-hover" />
+      <div className="h-3.5 w-[5.5rem] animate-pulse rounded bg-hover" />
+      <div />
+    </div>
+  );
+}
+
 function formatCreatedAt(iso: string): string {
   const date = new Date(iso);
   if (Number.isNaN(date.getTime())) {
@@ -180,13 +217,14 @@ function daysSince(iso: string): number {
 export default function KeysView() {
   const { user } = useAuth();
   const externalUserId = user?.id?.trim();
-  const { state, createKey, revokeKey, reload } = useApiKeys(
+  const { state, createKey, insertKey, revokeKey, reload } = useApiKeys(
     externalUserId,
     user?.email,
   );
 
   const [revealed, setRevealed] = useState<{
     apiKey: string;
+    id: string;
     sdkToken: string | null;
   } | null>(null);
   const [openMenu, setOpenMenu] = useState<string | null>(null);
@@ -195,6 +233,7 @@ export default function KeysView() {
   const [creating, setCreating] = useState(false);
   const [actionError, setActionError] = useState<string | null>(null);
   const menuRef = useRef<HTMLDivElement>(null);
+  const revealRef = useRef<HTMLDivElement>(null);
 
   const keys: DashboardApiKeyRow[] = state.status === "ready" ? state.keys : [];
   const ROTATE_DAYS_THRESHOLD = 90;
@@ -224,13 +263,23 @@ export default function KeysView() {
     setCreating(true);
     try {
       const created = await createKey("Dashboard SDK");
-      setRevealed(created);
+      // Same paint: drop skeleton, insert row, show full-key banner.
+      insertKey(created.row);
+      setRevealed({
+        apiKey: created.apiKey,
+        id: created.id,
+        sdkToken: created.sdkToken,
+      });
+      setCreating(false);
+      void reload({ soft: true });
+      queueMicrotask(() => {
+        revealRef.current?.scrollIntoView({ behavior: "smooth", block: "nearest" });
+      });
     } catch (error) {
+      setCreating(false);
       setActionError(
         error instanceof Error ? error.message : "Could not create API key",
       );
-    } finally {
-      setCreating(false);
     }
   };
 
@@ -323,7 +372,12 @@ export default function KeysView() {
         )}
 
         {revealed && (
-          <div className="relative mb-4 flex overflow-hidden rounded-md border border-green bg-gradient-to-b from-green/[0.08] to-green/[0.02]">
+          <div
+            ref={revealRef}
+            role="status"
+            aria-live="polite"
+            className="relative mb-4 flex overflow-hidden rounded-md border border-green bg-gradient-to-b from-green/[0.08] to-green/[0.02]"
+          >
             <div
               className="pointer-events-none absolute inset-0"
               style={{
@@ -421,21 +475,28 @@ export default function KeysView() {
             </div>
           )}
 
-          {!loading && keys.length === 0 && (
+          {!loading && keys.length === 0 && !creating && (
             <div className="px-4 py-12 text-center text-[13px] text-fg-muted">
               No API keys yet. Create one to use with the SDK.
             </div>
           )}
 
+          {!loading && creating && <KeysTableSkeletonRow />}
+
           {!loading &&
             keys.map((k) => {
               const stale = daysSince(k.createdAt) >= ROTATE_DAYS_THRESHOLD;
               const isOpen = openMenu === k.id;
+              const isJustCreated = revealed?.id === k.id;
               const displayName = k.label?.trim() || "SDK key";
               return (
                 <div
                   key={k.id}
-                  className="relative grid grid-cols-[2.4fr_1.1fr_1.2fr_36px] items-center gap-3 border-b border-hairline px-4 py-3.5 last:border-b-0 hover:bg-zebra"
+                  className={`relative grid grid-cols-[2.4fr_1.1fr_1.2fr_36px] items-center gap-3 border-b border-hairline px-4 py-3.5 last:border-b-0 ${
+                    isJustCreated
+                      ? "bg-green/[0.06] ring-1 ring-inset ring-green/25"
+                      : "hover:bg-zebra"
+                  }`}
                 >
                   <div className="min-w-0">
                     <div className="text-[13.5px] font-medium text-fg">
@@ -450,11 +511,7 @@ export default function KeysView() {
                         </span>
                       )}
                     </div>
-                    <div className="mt-1 font-mono text-[11.5px] text-fg-faint">
-                      {k.prefix}
-                      <span className="px-0.5 text-fg-disabled">…</span>
-                      {k.suffix}
-                    </div>
+                    <MaskedToken prefix={k.prefix} suffix={k.suffix} />
                   </div>
 
                   <div>
diff --git a/lib/dashboard/pymthouse-keys-bff.ts b/lib/dashboard/pymthouse-keys-bff.ts
index c4f7f3e..9e3babf 100644
--- a/lib/dashboard/pymthouse-keys-bff.ts
+++ b/lib/dashboard/pymthouse-keys-bff.ts
@@ -1,6 +1,4 @@
 import { PmtHouseError } from "@pymthouse/builder-sdk";
-import { buildGatewayToken } from "@pymthouse/builder-sdk/signer/gateway";
-import { readDiscoveryRawUrl } from "@/lib/discovery/config";
 
 export type DashboardApiKeyRow = {
   id: string;
@@ -12,35 +10,6 @@ export type DashboardApiKeyRow = {
   revokedAt: string | null;
 };
 
-/** Env-driven signer URL used for python-gateway `--token` bundles. */
-function readSignerUrl(): string | undefined {
-  return (
-    process.env.PYMTHOUSE_CLIENT_SIGNER_API_URL?.trim() ||
-    process.env.PYMTHOUSE_SIGNER_URL?.trim() ||
-    process.env.SIGNER_PUBLIC_URL?.trim() ||
-    undefined
-  );
-}
-
-/**
- * Build a base64 python-gateway `--token` from a freshly minted API key.
- * Matches PymtHouse `createLivepeerPythonSdkToken` (Bearer key in signer_headers).
- */
-function buildPythonGatewayToken(apiKey: string): string | undefined {
-  const signer = readSignerUrl();
-  if (!signer) {
-    return undefined;
-  }
-  return buildGatewayToken({
-    signer,
-    discovery: readDiscoveryRawUrl(),
-    auth: {
-      kind: "signerJwt",
-      accessToken: apiKey,
-    },
-  });
-}
-
 function readPublicClientId(): string {
   const id =
     process.env.PYMTHOUSE_PUBLIC_CLIENT_ID?.trim() ||
@@ -211,11 +180,11 @@ export async function createDashboardApiKey(input: {
     createdAt: string;
   }>(response);
 
-  const fromIssuer =
+  // Issuer builds the python-gateway --token (includes signer routing).
+  const sdkToken =
     typeof body.sdkToken === "string" && body.sdkToken.trim()
       ? body.sdkToken.trim()
       : null;
-  const sdkToken = fromIssuer ?? buildPythonGatewayToken(body.apiKey) ?? null;
 
   return {
     apiKey: body.apiKey,
diff --git a/lib/dashboard/signer-session-bff.ts b/lib/dashboard/signer-session-bff.ts
index c136c13..8ade20f 100644
--- a/lib/dashboard/signer-session-bff.ts
+++ b/lib/dashboard/signer-session-bff.ts
@@ -16,6 +16,15 @@ export type SignerContext = {
   expiresAt: number;
 };
 
+const SIGNER_ROUTING_TTL_MS = 5 * 60 * 1000;
+
+type CachedSignerRouting = {
+  signerUrl: string;
+  fetchedAt: number;
+};
+
+const signerRoutingByClient = new Map<string, CachedSignerRouting>();
+
 function readPublicClientId(): string {
   const id =
     process.env.PYMTHOUSE_PUBLIC_CLIENT_ID?.trim() ||
@@ -29,15 +38,6 @@ function readPublicClientId(): string {
   return id;
 }
 
-function readSignerUrl(): string | undefined {
-  return (
-    process.env.PYMTHOUSE_CLIENT_SIGNER_API_URL?.trim() ||
-    process.env.PYMTHOUSE_SIGNER_URL?.trim() ||
-    process.env.SIGNER_PUBLIC_URL?.trim() ||
-    undefined
-  );
-}
-
 function readM2mMintConfig() {
   const issuerUrl = process.env.PYMTHOUSE_ISSUER_URL?.trim();
   const m2mClientId = process.env.PYMTHOUSE_M2M_CLIENT_ID?.trim();
@@ -57,6 +57,30 @@ function isPymthouseConfigured(): boolean {
   return readM2mMintConfig() !== null && Boolean(readPublicClientId());
 }
 
+/**
+ * Resolve the public signer DMZ URL from issuer app routing
+ * (`GET …/apps/{clientId}/signer/routing`) — not from dashboard env.
+ */
+async function resolveSignerUrl(publicClientId: string): Promise<string | undefined> {
+  const now = Date.now();
+  const cached = signerRoutingByClient.get(publicClientId);
+  if (cached && now - cached.fetchedAt < SIGNER_ROUTING_TTL_MS) {
+    return cached.signerUrl;
+  }
+
+  const client = createPmtHouseClientForPublicApp(publicClientId);
+  const routing = await client.getSignerRouting();
+  const signerUrl =
+    routing.routing?.signerApiUrl?.trim() ||
+    routing.patterns?.directDmz?.signerApiUrl?.trim() ||
+    "";
+  if (!signerUrl) {
+    return undefined;
+  }
+  signerRoutingByClient.set(publicClientId, { signerUrl, fetchedAt: now });
+  return signerUrl;
+}
+
 const tokenManager = createSignerTokenManager({
   mint: async (publicClientId, externalUserId) => {
     const config = readM2mMintConfig();
@@ -78,10 +102,13 @@ const tokenManager = createSignerTokenManager({
   },
 });
 
-function toSignerContext(token: CachedSignerToken): SignerContext {
+function toSignerContext(
+  token: CachedSignerToken,
+  signerUrl: string | undefined,
+): SignerContext {
   return {
     jwt: token.jwt,
-    signerUrl: readSignerUrl(),
+    signerUrl,
     balanceUsdMicros: token.balanceUsdMicros,
     lifetimeGrantedUsdMicros: token.lifetimeGrantedUsdMicros,
     expiresAt: token.expiresAt,
@@ -104,10 +131,13 @@ export async function getSignerContext(
     });
   }
   const publicClientId = readPublicClientId();
-  const token = await tokenManager.getToken(publicClientId, trimmed, {
-    forceRefresh: options?.forceRefresh,
-  });
-  return toSignerContext(token);
+  const [token, signerUrl] = await Promise.all([
+    tokenManager.getToken(publicClientId, trimmed, {
+      forceRefresh: options?.forceRefresh,
+    }),
+    resolveSignerUrl(publicClientId),
+  ]);
+  return toSignerContext(token, signerUrl);
 }
 
 export async function getSignerSessionStatus(externalUserId: string): Promise<{
diff --git a/lib/dashboard/useApiKeys.ts b/lib/dashboard/useApiKeys.ts
index d7ee89d..0cfa57f 100644
--- a/lib/dashboard/useApiKeys.ts
+++ b/lib/dashboard/useApiKeys.ts
@@ -96,26 +96,31 @@ export function useApiKeys(
       if (!response.ok || !body.apiKey || !body.row) {
         throw new Error(body.error ?? `Create failed (${response.status})`);
       }
-      // Show the new row immediately so a soft-list failure cannot blank the table.
-      setState((prev) => {
-        const existing = prev.status === "ready" ? prev.keys : [];
-        return {
-          status: "ready",
-          keys: [body.row!, ...existing.filter((row) => row.id !== body.row!.id)],
-        };
-      });
-      await load({ soft: true });
+      // Caller inserts the row in the same paint as the reveal banner, then
+      // soft-refreshes — keep create itself free of list mutations.
       return {
         apiKey: body.apiKey,
+        id: body.row.id,
+        row: body.row,
         sdkToken:
           typeof body.sdkToken === "string" && body.sdkToken.trim()
             ? body.sdkToken.trim()
             : null,
       };
     },
-    [email, externalUserId, load],
+    [email, externalUserId],
   );
 
+  const insertKey = useCallback((row: DashboardApiKeyRow) => {
+    setState((prev) => {
+      const existing = prev.status === "ready" ? prev.keys : [];
+      return {
+        status: "ready",
+        keys: [row, ...existing.filter((existingRow) => existingRow.id !== row.id)],
+      };
+    });
+  }, []);
+
   const revokeKey = useCallback(
     async (keyId: string) => {
       if (!externalUserId?.trim()) {
@@ -146,5 +151,5 @@ export function useApiKeys(
     [externalUserId, load],
   );
 
-  return { state, reload: load, createKey, revokeKey };
+  return { state, reload: load, createKey, insertKey, revokeKey };
 }

From 59b954a4ccc5ca75842be7efa2db237f232ae400 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Sat, 8 Aug 2026 00:08:29 -0400
Subject: [PATCH 08/13] fix(billing): gate cancel affordances on the live plan,
 add owner wallet
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The UI trusted any pendingCancel the Builder API returned, but upstream
reports whichever canceled OpenMeter row still occupies the slot — including
one belonging to a plan the user has already switched away from. Billing
therefore showed "Pay as you go" as the current plan while simultaneously
offering to restore a superseded plan, behind a restore button that could
only fail. Cancel/restore affordances now require the pending cancel to
match the live plan, current-plan resolution is single-sourced through
deriveBillingSubscriptionUiState, and a rejected resume reconciles the stale
snapshot instead of stranding an error.

That reconciliation keys on the upstream machine-readable code
`nothing_to_resume`, not on the status class. Treating any 4xx as "nothing
was scheduled" silently swallowed 401/403, unrelated 404s, and the 502
`resume_failed` branch where a resume target existed but the restore threw;
those are real failures and now surface as such.

Cancel and plan change gain explicit timing (immediate, end of period, or a
chosen date), and a scheduled-change conflict prompts before replacing the
existing schedule rather than failing opaquely.

pymthouse-bff gains isUserNotFoundError, accepting both the `code:
"not_found"` envelope and the code-less `{"error":"not_found"}` the
mint-token route returns, so auto-provisioning keeps working across
builder-sdk versions.

Alongside this, the owner wallet surface: prepaid balance, Stripe top-up,
platform invoices, and the auto-debit payment method over Builder M2M. Plan
listing hydrates pay-per-use threshold and behaviour copy from the wallet
summary because the apiVersion=2 product shape omits them, falling back to
generic copy when the wallet API is absent. Allowance copy moves from
"Starter" to "Prepaid" to match. Checkout return URLs prefer a configured
public HTTPS origin, since Stripe rejects most http return URLs.

The settings rail reads its active tab from useSearchParams rather than
window.location, which disagreed between SSR and client and left General
highlighted on a ?tab=billing load until hydration.

Wallet and subscription changes share lib/dashboard/pymthouse-billing-bff.ts
and plan listing calls into the wallet summary, so they ship together rather
than being split by hunk.
---
 app/(app)/usage/page.tsx                      |   2 +-
 app/api/pymthouse/subscribe/route.ts          |  27 +-
 .../pymthouse/subscription/cancel/route.ts    |  44 ++
 .../pymthouse/subscription/change/route.ts    |  14 +-
 .../pymthouse/subscription/resume/route.ts    |  51 ++
 app/api/pymthouse/wallet/invoices/route.ts    |  26 +
 .../pymthouse/wallet/payment-methods/route.ts |  52 ++
 app/api/pymthouse/wallet/route.ts             |  18 +
 app/api/pymthouse/wallet/top-up/route.ts      |  44 ++
 .../pymthouse/wallet/wallet-route-helpers.ts  |  50 ++
 components/dashboard/DashboardSidebar.tsx     |  16 +-
 components/dashboard/PlansPanel.tsx           | 214 ++++++--
 components/dashboard/SidebarUsageCard.tsx     |   2 +-
 components/dashboard/UsageView.tsx            |   7 +-
 components/dashboard/WalletPanel.tsx          | 279 ++++++++++
 .../dashboard/settings/BillingSection.tsx     | 509 ++++++++++++++++--
 .../billing-subscription-state.test.ts        | 216 ++++++++
 lib/dashboard/billing-subscription-state.ts   | 175 +++++-
 lib/dashboard/pymthouse-bff.ts                |  24 +-
 lib/dashboard/pymthouse-billing-bff.ts        | 306 ++++++++++-
 lib/dashboard/useBillingAccount.ts            |  30 +-
 lib/dashboard/useBillingPlans.ts              |  96 +++-
 lib/dashboard/useOwnerWallet.ts               | 155 ++++++
 23 files changed, 2257 insertions(+), 100 deletions(-)
 create mode 100644 app/api/pymthouse/subscription/cancel/route.ts
 create mode 100644 app/api/pymthouse/subscription/resume/route.ts
 create mode 100644 app/api/pymthouse/wallet/invoices/route.ts
 create mode 100644 app/api/pymthouse/wallet/payment-methods/route.ts
 create mode 100644 app/api/pymthouse/wallet/route.ts
 create mode 100644 app/api/pymthouse/wallet/top-up/route.ts
 create mode 100644 app/api/pymthouse/wallet/wallet-route-helpers.ts
 create mode 100644 components/dashboard/WalletPanel.tsx
 create mode 100644 lib/dashboard/useOwnerWallet.ts

diff --git a/app/(app)/usage/page.tsx b/app/(app)/usage/page.tsx
index 1c17602..d95011c 100644
--- a/app/(app)/usage/page.tsx
+++ b/app/(app)/usage/page.tsx
@@ -36,7 +36,7 @@ function UsageContent() {
       <DashboardPageHeader
         title="Usage"
         icon={BarChart3}
-        description="Signed requests, network cost, and Starter allowance from PymtHouse OpenMeter."
+        description="Signed requests, network cost, and prepaid balance usage from PymtHouse OpenMeter."
         actions={
           <>
             <button
diff --git a/app/api/pymthouse/subscribe/route.ts b/app/api/pymthouse/subscribe/route.ts
index 2eacea1..7ad2416 100644
--- a/app/api/pymthouse/subscribe/route.ts
+++ b/app/api/pymthouse/subscribe/route.ts
@@ -26,7 +26,32 @@ export async function POST(request: NextRequest) {
     );
   }
 
-  const origin = request.nextUrl.origin;
+  // Prefer an explicit public HTTPS origin (Stripe rejects most http return
+  // URLs). Fall back to the request origin; for local http://localhost Next
+  // can be started with `next dev --experimental-https`.
+  const configuredOrigin = (
+    process.env.DASHBOARD_PUBLIC_URL ||
+    process.env.NEXT_PUBLIC_APP_URL ||
+    ""
+  )
+    .trim()
+    .replace(/\/$/, "");
+  let origin = configuredOrigin || request.nextUrl.origin;
+  try {
+    const parsed = new URL(origin);
+    if (
+      parsed.protocol === "http:" &&
+      parsed.hostname !== "localhost" &&
+      parsed.hostname !== "127.0.0.1"
+    ) {
+      parsed.protocol = "https:";
+      origin = parsed.origin;
+    } else {
+      origin = parsed.origin;
+    }
+  } catch {
+    origin = request.nextUrl.origin;
+  }
   const successUrl =
     body.successUrl?.trim() || `${origin}/usage?checkout=success`;
   const cancelUrl =
diff --git a/app/api/pymthouse/subscription/cancel/route.ts b/app/api/pymthouse/subscription/cancel/route.ts
new file mode 100644
index 0000000..969a5fe
--- /dev/null
+++ b/app/api/pymthouse/subscription/cancel/route.ts
@@ -0,0 +1,44 @@
+import { NextRequest, NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+import { cancelDashboardUserSubscription } from "@/lib/dashboard/pymthouse-billing-bff";
+
+export const runtime = "nodejs";
+
+export async function POST(request: NextRequest) {
+  let body: {
+    externalUserId?: string;
+    timing?: string;
+    effectiveAt?: string;
+  };
+  try {
+    body = (await request.json()) as typeof body;
+  } catch {
+    return NextResponse.json({ error: "invalid_json" }, { status: 400 });
+  }
+
+  const externalUserId = body.externalUserId?.trim();
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 }
+    );
+  }
+
+  try {
+    await cancelDashboardUserSubscription(externalUserId, {
+      timing: body.timing?.trim(),
+      effectiveAt: body.effectiveAt?.trim(),
+    });
+    return NextResponse.json({ ok: true });
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status }
+      );
+    }
+    const message =
+      error instanceof Error ? error.message : "Failed to cancel subscription";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
diff --git a/app/api/pymthouse/subscription/change/route.ts b/app/api/pymthouse/subscription/change/route.ts
index 3aaf9e9..1869b47 100644
--- a/app/api/pymthouse/subscription/change/route.ts
+++ b/app/api/pymthouse/subscription/change/route.ts
@@ -10,6 +10,9 @@ export async function POST(request: NextRequest) {
     externalUserId?: string;
     successUrl?: string;
     cancelUrl?: string;
+    timing?: string;
+    effectiveAt?: string;
+    confirmReplaceScheduled?: boolean;
   };
   try {
     body = (await request.json()) as typeof body;
@@ -32,12 +35,21 @@ export async function POST(request: NextRequest) {
       externalUserId,
       successUrl: body.successUrl?.trim(),
       cancelUrl: body.cancelUrl?.trim(),
+      timing: body.timing?.trim(),
+      effectiveAt: body.effectiveAt?.trim(),
+      confirmReplaceScheduled: body.confirmReplaceScheduled === true,
     });
     return NextResponse.json(result);
   } catch (error) {
     if (error instanceof PmtHouseError) {
       return NextResponse.json(
-        { error: error.message, code: error.code },
+        {
+          error: error.message,
+          code: error.code,
+          ...(error.details && typeof error.details === "object"
+            ? (error.details as Record<string, unknown>)
+            : {}),
+        },
         { status: error.status }
       );
     }
diff --git a/app/api/pymthouse/subscription/resume/route.ts b/app/api/pymthouse/subscription/resume/route.ts
new file mode 100644
index 0000000..3a1f1b8
--- /dev/null
+++ b/app/api/pymthouse/subscription/resume/route.ts
@@ -0,0 +1,51 @@
+import { NextRequest, NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+import { resumeDashboardUserSubscription } from "@/lib/dashboard/pymthouse-billing-bff";
+
+export const runtime = "nodejs";
+
+/**
+ * The SDK derives `PmtHouseError.code` from the upstream error *message*, so
+ * the machine-readable code (e.g. `nothing_to_resume`) only survives on
+ * `details`. Prefer it so clients can branch on the code.
+ */
+function upstreamCode(error: PmtHouseError): string {
+  const details = error.details;
+  if (details && typeof details === "object" && "code" in details) {
+    const code = (details as { code?: unknown }).code;
+    if (typeof code === "string" && code.trim()) return code;
+  }
+  return error.code;
+}
+
+export async function POST(request: NextRequest) {
+  let body: { externalUserId?: string };
+  try {
+    body = (await request.json()) as typeof body;
+  } catch {
+    return NextResponse.json({ error: "invalid_json" }, { status: 400 });
+  }
+
+  const externalUserId = body.externalUserId?.trim();
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 }
+    );
+  }
+
+  try {
+    await resumeDashboardUserSubscription(externalUserId);
+    return NextResponse.json({ ok: true });
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        { error: error.message, code: upstreamCode(error) },
+        { status: error.status }
+      );
+    }
+    const message =
+      error instanceof Error ? error.message : "Failed to resume subscription";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
diff --git a/app/api/pymthouse/wallet/invoices/route.ts b/app/api/pymthouse/wallet/invoices/route.ts
new file mode 100644
index 0000000..e5e032f
--- /dev/null
+++ b/app/api/pymthouse/wallet/invoices/route.ts
@@ -0,0 +1,26 @@
+import { NextRequest, NextResponse } from "next/server";
+import { listDashboardWalletInvoices } from "@/lib/dashboard/pymthouse-billing-bff";
+import {
+  WALLET_NO_STORE_HEADERS,
+  walletErrorResponse,
+} from "../wallet-route-helpers";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+function parsePageParam(raw: string | null): number | undefined {
+  if (!raw || !/^[1-9]\d*$/.test(raw)) return undefined;
+  return Number(raw);
+}
+
+export async function GET(request: NextRequest) {
+  const page = parsePageParam(request.nextUrl.searchParams.get("page"));
+  const pageSize = parsePageParam(request.nextUrl.searchParams.get("pageSize"));
+
+  try {
+    const result = await listDashboardWalletInvoices({ page, pageSize });
+    return NextResponse.json(result, { headers: WALLET_NO_STORE_HEADERS });
+  } catch (error) {
+    return walletErrorResponse(error, "Failed to load wallet invoices");
+  }
+}
diff --git a/app/api/pymthouse/wallet/payment-methods/route.ts b/app/api/pymthouse/wallet/payment-methods/route.ts
new file mode 100644
index 0000000..02a94e2
--- /dev/null
+++ b/app/api/pymthouse/wallet/payment-methods/route.ts
@@ -0,0 +1,52 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  listDashboardWalletPaymentMethods,
+  startDashboardWalletPaymentMethodCheckout,
+} from "@/lib/dashboard/pymthouse-billing-bff";
+import {
+  WALLET_NO_STORE_HEADERS,
+  checkoutReturnOrigin,
+  walletErrorResponse,
+} from "../wallet-route-helpers";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  try {
+    const paymentMethods = await listDashboardWalletPaymentMethods();
+    return NextResponse.json(
+      { paymentMethods },
+      { headers: WALLET_NO_STORE_HEADERS },
+    );
+  } catch (error) {
+    return walletErrorResponse(error, "Failed to load wallet payment methods");
+  }
+}
+
+export async function POST(request: NextRequest) {
+  let body: { successUrl?: string; cancelUrl?: string };
+  try {
+    body = (await request.json()) as typeof body;
+  } catch {
+    body = {};
+  }
+
+  const origin = checkoutReturnOrigin(request);
+  const successUrl =
+    body.successUrl?.trim() || `${origin}/usage?topup=pm-saved`;
+  const cancelUrl = body.cancelUrl?.trim() || `${origin}/usage?topup=canceled`;
+
+  try {
+    const result = await startDashboardWalletPaymentMethodCheckout({
+      successUrl,
+      cancelUrl,
+    });
+    return NextResponse.json(result);
+  } catch (error) {
+    return walletErrorResponse(
+      error,
+      "Failed to start payment method checkout",
+    );
+  }
+}
diff --git a/app/api/pymthouse/wallet/route.ts b/app/api/pymthouse/wallet/route.ts
new file mode 100644
index 0000000..524fee3
--- /dev/null
+++ b/app/api/pymthouse/wallet/route.ts
@@ -0,0 +1,18 @@
+import { NextResponse } from "next/server";
+import { getDashboardOwnerWallet } from "@/lib/dashboard/pymthouse-billing-bff";
+import {
+  WALLET_NO_STORE_HEADERS,
+  walletErrorResponse,
+} from "./wallet-route-helpers";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  try {
+    const wallet = await getDashboardOwnerWallet();
+    return NextResponse.json(wallet, { headers: WALLET_NO_STORE_HEADERS });
+  } catch (error) {
+    return walletErrorResponse(error, "Failed to load wallet");
+  }
+}
diff --git a/app/api/pymthouse/wallet/top-up/route.ts b/app/api/pymthouse/wallet/top-up/route.ts
new file mode 100644
index 0000000..a66ca32
--- /dev/null
+++ b/app/api/pymthouse/wallet/top-up/route.ts
@@ -0,0 +1,44 @@
+import { NextRequest, NextResponse } from "next/server";
+import { startDashboardWalletTopUp } from "@/lib/dashboard/pymthouse-billing-bff";
+import {
+  checkoutReturnOrigin,
+  walletErrorResponse,
+} from "../wallet-route-helpers";
+
+export const runtime = "nodejs";
+
+export async function POST(request: NextRequest) {
+  let body: { amountUsd?: string | number; successUrl?: string; cancelUrl?: string };
+  try {
+    body = (await request.json()) as typeof body;
+  } catch {
+    return NextResponse.json({ error: "invalid_json" }, { status: 400 });
+  }
+
+  const amountUsd =
+    typeof body.amountUsd === "number"
+      ? body.amountUsd.toFixed(2)
+      : body.amountUsd?.trim();
+  if (!amountUsd) {
+    return NextResponse.json(
+      { error: 'amountUsd is required (e.g. "25.00")' },
+      { status: 400 },
+    );
+  }
+
+  const origin = checkoutReturnOrigin(request);
+  const successUrl =
+    body.successUrl?.trim() || `${origin}/usage?topup=succeeded`;
+  const cancelUrl = body.cancelUrl?.trim() || `${origin}/usage?topup=canceled`;
+
+  try {
+    const result = await startDashboardWalletTopUp({
+      amountUsd,
+      successUrl,
+      cancelUrl,
+    });
+    return NextResponse.json(result);
+  } catch (error) {
+    return walletErrorResponse(error, "Failed to start top-up checkout");
+  }
+}
diff --git a/app/api/pymthouse/wallet/wallet-route-helpers.ts b/app/api/pymthouse/wallet/wallet-route-helpers.ts
new file mode 100644
index 0000000..6075c89
--- /dev/null
+++ b/app/api/pymthouse/wallet/wallet-route-helpers.ts
@@ -0,0 +1,50 @@
+import { NextRequest, NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+
+// Wallet/balance is live money data; never let the browser or a CDN replay a
+// stale response.
+export const WALLET_NO_STORE_HEADERS = {
+  "Cache-Control": "no-store, max-age=0",
+} as const;
+
+export function walletErrorResponse(
+  error: unknown,
+  fallback: string,
+): NextResponse {
+  if (error instanceof PmtHouseError) {
+    return NextResponse.json(
+      { error: error.message, code: error.code },
+      { status: error.status, headers: WALLET_NO_STORE_HEADERS },
+    );
+  }
+  return NextResponse.json(
+    { error: error instanceof Error ? error.message : fallback },
+    { status: 502, headers: WALLET_NO_STORE_HEADERS },
+  );
+}
+
+/** Https-preferring public origin for Stripe Checkout return URLs. */
+export function checkoutReturnOrigin(request: NextRequest): string {
+  const configuredOrigin = (
+    process.env.DASHBOARD_PUBLIC_URL ||
+    process.env.NEXT_PUBLIC_APP_URL ||
+    ""
+  )
+    .trim()
+    .replace(/\/$/, "");
+  let origin = configuredOrigin || request.nextUrl.origin;
+  try {
+    const parsed = new URL(origin);
+    if (
+      parsed.protocol === "http:" &&
+      parsed.hostname !== "localhost" &&
+      parsed.hostname !== "127.0.0.1"
+    ) {
+      parsed.protocol = "https:";
+    }
+    origin = parsed.origin;
+  } catch {
+    origin = request.nextUrl.origin;
+  }
+  return origin;
+}
diff --git a/components/dashboard/DashboardSidebar.tsx b/components/dashboard/DashboardSidebar.tsx
index d851d81..13befba 100644
--- a/components/dashboard/DashboardSidebar.tsx
+++ b/components/dashboard/DashboardSidebar.tsx
@@ -1,8 +1,8 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { Suspense, useEffect, useState } from "react";
 import Link from "next/link";
-import { usePathname, useRouter } from "next/navigation";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
 import {
   House,
   LayoutGrid,
@@ -418,15 +418,17 @@ function SettingsRail({
   onNavigate?: () => void;
 }) {
   const router = useRouter();
+  // useSearchParams (not window.location) so SSR and the client agree —
+  // reading `window` only on the client marked General active during SSR
+  // and Billing after hydrate when `?tab=billing`.
+  const searchParams = useSearchParams();
 
   // Read the active sub-tab from `?tab=<id>` on the current URL. Default to
   // "organization" when on `/settings` with no tab param — matches the
   // prototype's fallback (`route === 'settings' ? 'organization' : ...`).
   let activeTab = "organization";
   if (pathname === "/settings" || pathname.startsWith("/settings")) {
-    const search = typeof window !== "undefined" ? window.location.search : "";
-    const params = new URLSearchParams(search);
-    const t = params.get("tab");
+    const t = searchParams.get("tab");
     if (t) activeTab = t;
   }
 
@@ -647,7 +649,9 @@ function SidebarContent({
           NETWORK destinations get their own labeled section below. On /settings
           the whole list is replaced by the SettingsRail. */}
       {pathname.startsWith("/settings") ? (
-        <SettingsRail pathname={pathname} padX={padX} onNavigate={onNavigate} />
+        <Suspense fallback={<div className={`pb-1 ${padX}`} aria-hidden="true" />}>
+          <SettingsRail pathname={pathname} padX={padX} onNavigate={onNavigate} />
+        </Suspense>
       ) : (
         <>
           {/* Primary — your organization resources. Environment is a per-page
diff --git a/components/dashboard/PlansPanel.tsx b/components/dashboard/PlansPanel.tsx
index 6834997..b7975bc 100644
--- a/components/dashboard/PlansPanel.tsx
+++ b/components/dashboard/PlansPanel.tsx
@@ -1,22 +1,72 @@
 "use client";
 
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import Button from "@/components/design-system/Button";
+import type { DashboardBillingPlan } from "@/lib/dashboard/pymthouse-billing-bff";
 import { useBillingPlans } from "@/lib/dashboard/useBillingPlans";
 
-function formatPrice(amount: string, currency: string, cycle: string | null): string {
-  const n = Number(amount);
+function isUsagePlan(plan: Pick<DashboardBillingPlan, "type">): boolean {
+  return plan.type.trim().toLowerCase() === "usage";
+}
+
+function formatUsdMicrosAsCurrency(usdMicros: string): string {
+  try {
+    const amount = Number(BigInt(usdMicros)) / 1_000_000;
+    return new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: "USD",
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2,
+    }).format(amount);
+  } catch {
+    return "$0.00";
+  }
+}
+
+function formatPrice(plan: DashboardBillingPlan): string {
+  const n = Number(plan.priceAmount);
   const money = Number.isFinite(n)
     ? new Intl.NumberFormat("en-US", {
         style: "currency",
-        currency: currency || "USD",
+        currency: plan.priceCurrency || "USD",
       }).format(n)
-    : amount;
-  if (!cycle) return money;
-  const c = cycle.toLowerCase();
+    : plan.priceAmount;
+
+  if (isUsagePlan(plan)) return `${money} · pay as you go`;
+  if (!plan.billingCycle) return money;
+  const c = plan.billingCycle.toLowerCase();
   if (c === "monthly" || c === "month") return `${money}/mo`;
   if (c === "yearly" || c === "year" || c === "annual") return `${money}/yr`;
-  return `${money} · ${cycle}`;
+  return `${money} · ${plan.billingCycle}`;
+}
+
+function resolvedPayPerUseBehavior(plan: DashboardBillingPlan): string {
+  const resolved = plan.resolvedBehavior?.trim();
+  if (resolved) return resolved;
+
+  const threshold = plan.chargeThresholdUsdMicros?.trim();
+  if (threshold) {
+    return `Charged at every ${formatUsdMicrosAsCurrency(
+      threshold
+    )} of usage (credits first).`;
+  }
+
+  return "Usage settles from prepaid credits first, then auto-debits your default payment method.";
+}
+
+function readCheckoutFlash(): "success" | "cancel" | null {
+  if (typeof window === "undefined") return null;
+  const value = new URLSearchParams(window.location.search).get("checkout");
+  if (value === "success" || value === "cancel") return value;
+  return null;
+}
+
+function clearCheckoutQueryParam(): void {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  if (!url.searchParams.has("checkout")) return;
+  url.searchParams.delete("checkout");
+  window.history.replaceState({}, "", `${url.pathname}${url.search}${url.hash}`);
 }
 
 export default function PlansPanel({
@@ -24,9 +74,21 @@ export default function PlansPanel({
 }: {
   externalUserId: string | undefined;
 }) {
-  const { state, reload, subscribe } = useBillingPlans();
+  const { state, reload, subscribe, changePlan } =
+    useBillingPlans(externalUserId);
   const [busyPlanId, setBusyPlanId] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const [flash, setFlash] = useState<"success" | "cancel" | null>(null);
+
+  useEffect(() => {
+    const next = readCheckoutFlash();
+    if (!next) return;
+    setFlash(next);
+    clearCheckoutQueryParam();
+    if (next === "success") {
+      void reload();
+    }
+  }, [reload]);
 
   async function onSubscribe(planId: string) {
     if (!externalUserId?.trim()) {
@@ -36,11 +98,50 @@ export default function PlansPanel({
     setError(null);
     setBusyPlanId(planId);
     try {
-      const { checkoutUrl } = await subscribe({
-        planId,
-        externalUserId: externalUserId.trim(),
-      });
-      window.location.assign(checkoutUrl);
+      const userId = externalUserId.trim();
+      const plans = state.status === "ready" ? state.plans : [];
+      const targetPlan = plans.find((p) => p.id === planId);
+      const activePlanId =
+        state.status === "ready" ? state.subscription?.planId : null;
+      const activeStatus =
+        state.status === "ready"
+          ? (state.subscription?.status?.toLowerCase() ?? "")
+          : "";
+      const hasActiveSubscription =
+        Boolean(activePlanId) &&
+        (activeStatus === "active" ||
+          activeStatus === "pending" ||
+          activeStatus === "trialing" ||
+          activeStatus === "scheduled");
+
+      // Starter/default users already have a subscription — switch instead of
+      // create, so pay-per-use can still collect a setup Checkout card.
+      const result = hasActiveSubscription
+        ? await changePlan({
+            planId,
+            externalUserId: userId,
+            successUrl: `${window.location.origin}/usage?checkout=success`,
+            cancelUrl: `${window.location.origin}/usage?checkout=cancel`,
+          })
+        : await subscribe({
+            planId,
+            externalUserId: userId,
+            successUrl: `${window.location.origin}/usage?checkout=success`,
+            cancelUrl: `${window.location.origin}/usage?checkout=cancel`,
+          });
+
+      if (result.checkoutUrl) {
+        window.location.assign(result.checkoutUrl);
+        return;
+      }
+
+      await reload();
+      setError(
+        targetPlan && isUsagePlan(targetPlan)
+          ? "Plan updated. Add a payment method in Settings → Billing for pay-per-use auto-debit."
+          : "Plan updated.",
+      );
+      setBusyPlanId(null);
     } catch (err) {
       setError(err instanceof Error ? err.message : "Checkout failed");
       setBusyPlanId(null);
@@ -72,6 +173,15 @@ export default function PlansPanel({
     return null;
   }
 
+  const activePlanId = state.subscription?.planId ?? null;
+  const activeStatus = state.subscription?.status?.toLowerCase() ?? "";
+  const hasActiveSubscription =
+    Boolean(activePlanId) &&
+    (activeStatus === "active" ||
+      activeStatus === "pending" ||
+      activeStatus === "trialing" ||
+      activeStatus === "scheduled");
+
   return (
     <div className="mt-4 overflow-hidden rounded-md border border-hairline bg-dark-lighter shadow-card">
       <div className="border-b border-hairline px-4 py-3.5">
@@ -79,32 +189,62 @@ export default function PlansPanel({
         <p className="mt-0.5 text-[12px] text-fg-muted">
           Subscribe via PymtHouse → Stripe Checkout
         </p>
+        {flash === "success" ? (
+          <p className="mt-2 text-[12px] text-emerald-400">
+            Payment method saved
+            {hasActiveSubscription && state.subscription?.planName
+              ? ` · on ${state.subscription.planName}`
+              : ""}
+            .
+          </p>
+        ) : null}
+        {flash === "cancel" ? (
+          <p className="mt-2 text-[12px] text-fg-muted">Checkout canceled.</p>
+        ) : null}
       </div>
       <ul className="divide-y divide-hairline">
-        {state.plans.map((plan) => (
-          <li
-            key={plan.id}
-            className="flex flex-wrap items-center justify-between gap-3 px-4 py-3"
-          >
-            <div>
-              <p className="text-sm font-semibold text-fg">{plan.name || plan.id}</p>
-              <p className="mt-0.5 font-mono text-[11px] text-fg-faint">
-                {formatPrice(plan.priceAmount, plan.priceCurrency, plan.billingCycle)}
-                {plan.capabilityCount > 0
-                  ? ` · ${plan.capabilityCount} capabilities`
-                  : ""}
-              </p>
-            </div>
-            <Button
-              variant="primary"
-              size="sm"
-              disabled={!externalUserId || busyPlanId === plan.id}
-              onClick={() => void onSubscribe(plan.id)}
+        {state.plans.map((plan) => {
+          const isCurrent = hasActiveSubscription && plan.id === activePlanId;
+          return (
+            <li
+              key={plan.id}
+              className="flex flex-wrap items-center justify-between gap-3 px-4 py-3"
             >
-              {busyPlanId === plan.id ? "Redirecting…" : "Subscribe"}
-            </Button>
-          </li>
-        ))}
+              <div>
+                <p className="text-sm font-semibold text-fg">{plan.name || plan.id}</p>
+                <p className="mt-0.5 font-mono text-[11px] text-fg-faint">
+                  {formatPrice(plan)}
+                  {plan.capabilityCount > 0
+                    ? ` · ${plan.capabilityCount} capabilities`
+                    : ""}
+                </p>
+                {isUsagePlan(plan) ? (
+                  <p className="mt-1 text-[11px] text-fg-faint">
+                    {resolvedPayPerUseBehavior(plan)}
+                  </p>
+                ) : null}
+              </div>
+              {isCurrent ? (
+                <span className="rounded-[4px] border border-hairline px-2.5 py-1 text-[12px] font-medium text-fg-muted">
+                  Current plan
+                </span>
+              ) : (
+                <Button
+                  variant="primary"
+                  size="sm"
+                  disabled={!externalUserId || busyPlanId === plan.id}
+                  onClick={() => void onSubscribe(plan.id)}
+                >
+                  {busyPlanId === plan.id
+                    ? "Redirecting…"
+                    : isUsagePlan(plan)
+                      ? "Enable pay-per-use"
+                      : "Subscribe"}
+                </Button>
+              )}
+            </li>
+          );
+        })}
       </ul>
       {error ? (
         <p className="border-t border-hairline px-4 py-2 text-xs text-rose-400">{error}</p>
diff --git a/components/dashboard/SidebarUsageCard.tsx b/components/dashboard/SidebarUsageCard.tsx
index 207e5dc..d596062 100644
--- a/components/dashboard/SidebarUsageCard.tsx
+++ b/components/dashboard/SidebarUsageCard.tsx
@@ -51,7 +51,7 @@ export default function SidebarUsageCard() {
     balance && BigInt(balance.lifetimeGrantedUsdMicros || "0") > BigInt(0);
 
   const resetsAt = formatPeriodResetLabel(data.period.end);
-  const planLabel = showUsdAllowance ? "Starter" : "Usage";
+  const planLabel = showUsdAllowance ? "Prepaid" : "Usage";
 
   let primaryUsed: number;
   let primaryLimit: number | null;
diff --git a/components/dashboard/UsageView.tsx b/components/dashboard/UsageView.tsx
index aab3b9c..1c3ea18 100644
--- a/components/dashboard/UsageView.tsx
+++ b/components/dashboard/UsageView.tsx
@@ -15,6 +15,7 @@ import {
 } from "@/lib/dashboard/usage-capability-display";
 import DashboardPageSkeleton from "@/components/dashboard/DashboardPageSkeleton";
 import PlansPanel from "@/components/dashboard/PlansPanel";
+import WalletPanel from "@/components/dashboard/WalletPanel";
 
 const PERIOD_DAYS = 30;
 
@@ -84,7 +85,7 @@ function AllowanceStrip({
     <div className="flex flex-col gap-3 rounded-md border border-hairline bg-dark-lighter shadow-card px-5 py-4">
       <div className="flex flex-wrap items-center gap-2">
         <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
-          {showUsdAllowance ? "Starter allowance" : "Usage this period"}
+          {showUsdAllowance ? "Prepaid allowance" : "Usage this period"}
         </p>
         {showUsdAllowance && !hasAccess && (
           <span className="rounded-[3px] border border-warm/30 bg-warm/10 px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-wide text-warm">
@@ -289,6 +290,8 @@ export default function UsageView() {
         resetsAt={resetsAt}
       />
 
+      <WalletPanel />
+
       <PlansPanel externalUserId={externalUserId} />
 
       <div className="mt-4 overflow-hidden rounded-md border border-hairline bg-dark-lighter shadow-card">
@@ -519,7 +522,7 @@ function LimitsPanel({
   const limits = balance
     ? [
         {
-          label: "Included allowance",
+          label: "Prepaid allowance",
           used: microsToUsdDisplay(balance.consumedUsdMicros),
           max: `$${microsToUsdDisplay(balance.lifetimeGrantedUsdMicros)}`,
           pct:
diff --git a/components/dashboard/WalletPanel.tsx b/components/dashboard/WalletPanel.tsx
new file mode 100644
index 0000000..ecf6cb0
--- /dev/null
+++ b/components/dashboard/WalletPanel.tsx
@@ -0,0 +1,279 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import Button from "@/components/design-system/Button";
+import { useOwnerWallet } from "@/lib/dashboard/useOwnerWallet";
+
+type TopUpFlash = "succeeded" | "canceled" | "pm-saved";
+
+function readTopUpFlash(): TopUpFlash | null {
+  if (typeof window === "undefined") return null;
+  const value = new URLSearchParams(window.location.search).get("topup");
+  if (value === "succeeded" || value === "canceled" || value === "pm-saved") {
+    return value;
+  }
+  return null;
+}
+
+function clearTopUpQueryParam(): void {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  if (!url.searchParams.has("topup")) return;
+  url.searchParams.delete("topup");
+  window.history.replaceState({}, "", `${url.pathname}${url.search}${url.hash}`);
+}
+
+function formatInvoiceDate(iso: string | undefined): string {
+  if (!iso) return "—";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return "—";
+  return date.toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+const QUICK_AMOUNTS = ["10.00", "25.00", "100.00"] as const;
+
+/** Only follow https (or localhost http, for dev) Checkout URLs. */
+function redirectToCheckout(url: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error("Invalid checkout URL");
+  }
+  const isLocalhost =
+    parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && isLocalhost)) {
+    throw new Error("Unsafe checkout URL");
+  }
+  window.location.assign(parsed.toString());
+}
+
+export default function WalletPanel() {
+  const { state, reload, startTopUp, startPaymentMethodCheckout } =
+    useOwnerWallet(true);
+  const [showTopUp, setShowTopUp] = useState(false);
+  const [amountUsd, setAmountUsd] = useState<string>("25.00");
+  const [busy, setBusy] = useState<"topup" | "pm" | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [flash, setFlash] = useState<TopUpFlash | null>(null);
+
+  useEffect(() => {
+    const next = readTopUpFlash();
+    if (!next) return;
+    setFlash(next);
+    clearTopUpQueryParam();
+  }, []);
+
+  async function onTopUp() {
+    setError(null);
+    setBusy("topup");
+    try {
+      const { checkoutUrl } = await startTopUp({ amountUsd: amountUsd.trim() });
+      redirectToCheckout(checkoutUrl);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Top-up failed");
+      setBusy(null);
+    }
+  }
+
+  async function onAddPaymentMethod() {
+    setError(null);
+    setBusy("pm");
+    try {
+      const { checkoutUrl } = await startPaymentMethodCheckout();
+      redirectToCheckout(checkoutUrl);
+    } catch (err) {
+      setError(
+        err instanceof Error ? err.message : "Payment method setup failed",
+      );
+      setBusy(null);
+    }
+  }
+
+  if (state.status === "loading" || state.status === "idle") {
+    return (
+      <div className="mt-4 animate-pulse rounded-md border border-hairline bg-dark-lighter px-4 py-6">
+        <div className="h-4 w-40 rounded bg-white/5" />
+        <div className="mt-3 h-16 rounded bg-white/5" />
+      </div>
+    );
+  }
+
+  if (state.status === "error") {
+    return (
+      <div className="mt-4 rounded-md border border-hairline bg-dark-lighter px-4 py-4">
+        <p className="text-sm text-fg-muted">Could not load wallet.</p>
+        <p className="mt-1 font-mono text-xs text-fg-faint">{state.message}</p>
+        <Button
+          className="mt-3"
+          variant="secondary"
+          size="sm"
+          onClick={() => void reload()}
+        >
+          Retry
+        </Button>
+      </div>
+    );
+  }
+
+  const { wallet, paymentMethods, invoices } = state;
+  const balanceUsd = wallet.balance?.usd ?? "0.00";
+  const defaultPm =
+    paymentMethods.find((pm) => pm.isDefault) ?? paymentMethods[0] ?? null;
+  const hasPaymentMethod =
+    wallet.paymentMethod.hasDefault ?? paymentMethods.length > 0;
+
+  return (
+    <div className="mt-4 overflow-hidden rounded-md border border-hairline bg-dark-lighter shadow-card">
+      <div className="flex flex-wrap items-start justify-between gap-3 border-b border-hairline px-4 py-3.5">
+        <div>
+          <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
+            Current balance
+          </p>
+          <p className="mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] text-fg">
+            ${balanceUsd}
+          </p>
+          <p className="mt-1 text-[12px] text-fg-muted">
+            {wallet.settlement.description}
+          </p>
+          {wallet.payPerUsePlans.map((plan) => (
+            <p key={plan.planId} className="mt-1 text-[11px] text-fg-faint">
+              {plan.planName}: {plan.resolvedBehavior}
+            </p>
+          ))}
+        </div>
+        <div className="flex flex-col items-end gap-2">
+          {showTopUp ? (
+            <div className="flex items-center gap-2">
+              <span className="font-mono text-[13px] text-fg-faint">$</span>
+              <input
+                type="text"
+                inputMode="decimal"
+                value={amountUsd}
+                onChange={(e) => setAmountUsd(e.target.value)}
+                className="h-[30px] w-24 rounded-[4px] border border-hairline bg-dark-card px-2 font-mono text-[13px] tabular-nums text-fg outline-none focus-visible:ring-1 focus-visible:ring-green-bright/30"
+                aria-label="Top-up amount in USD"
+              />
+              <Button
+                variant="primary"
+                size="sm"
+                disabled={busy === "topup"}
+                onClick={() => void onTopUp()}
+              >
+                {busy === "topup" ? "Redirecting…" : "Continue"}
+              </Button>
+              <Button
+                variant="secondary"
+                size="sm"
+                disabled={busy === "topup"}
+                onClick={() => setShowTopUp(false)}
+              >
+                Cancel
+              </Button>
+            </div>
+          ) : (
+            <Button variant="primary" size="sm" onClick={() => setShowTopUp(true)}>
+              Add funds
+            </Button>
+          )}
+          {showTopUp ? (
+            <div className="flex gap-1.5">
+              {QUICK_AMOUNTS.map((preset) => (
+                <button
+                  key={preset}
+                  type="button"
+                  onClick={() => setAmountUsd(preset)}
+                  className="rounded-[4px] border border-hairline bg-dark-card px-2 py-0.5 font-mono text-[11px] tabular-nums text-fg-muted transition-colors hover:border-subtle hover:text-fg"
+                >
+                  ${preset}
+                </button>
+              ))}
+            </div>
+          ) : null}
+        </div>
+      </div>
+
+      {flash === "succeeded" ? (
+        <p className="border-b border-hairline px-4 py-2 text-[12px] text-emerald-400">
+          Funds added. Your balance updates once Stripe settles the payment.
+        </p>
+      ) : null}
+      {flash === "pm-saved" ? (
+        <p className="border-b border-hairline px-4 py-2 text-[12px] text-emerald-400">
+          Payment method saved.
+        </p>
+      ) : null}
+      {flash === "canceled" ? (
+        <p className="border-b border-hairline px-4 py-2 text-[12px] text-fg-muted">
+          Checkout canceled.
+        </p>
+      ) : null}
+
+      <div className="flex flex-wrap items-center justify-between gap-3 border-b border-hairline px-4 py-3">
+        <div>
+          <p className="text-[13px] font-semibold text-fg">
+            Auto-debit payment method
+          </p>
+          <p className="mt-0.5 text-[12px] text-fg-muted">
+            {hasPaymentMethod && defaultPm
+              ? `${defaultPm.brand ?? defaultPm.type}${defaultPm.last4 ? ` •••• ${defaultPm.last4}` : ""}`
+              : hasPaymentMethod
+                ? "Payment method on file."
+                : "No payment method on file — pay-per-use auto-debit will fail once credits run out."}
+          </p>
+        </div>
+        <Button
+          variant="secondary"
+          size="sm"
+          disabled={busy === "pm"}
+          onClick={() => void onAddPaymentMethod()}
+        >
+          {busy === "pm"
+            ? "Redirecting…"
+            : hasPaymentMethod
+              ? "Update payment method"
+              : "Add payment method"}
+        </Button>
+      </div>
+
+      <div className="px-4 py-3">
+        <p className="text-[13px] font-semibold text-fg">Billing history</p>
+        {invoices.length === 0 ? (
+          <p className="mt-1 text-[12px] text-fg-faint">No invoices yet.</p>
+        ) : (
+          <ul className="mt-1.5 divide-y divide-hairline">
+            {invoices.slice(0, 8).map((invoice) => (
+              <li
+                key={invoice.id}
+                className="flex flex-wrap items-baseline justify-between gap-2 py-1.5"
+              >
+                <span className="font-mono text-[12px] text-fg-strong">
+                  {invoice.number ?? invoice.id}
+                </span>
+                <span className="text-[11.5px] text-fg-faint">
+                  {formatInvoiceDate(invoice.issuedAt ?? invoice.periodEnd)}
+                </span>
+                <span className="rounded-[3px] border border-hairline px-1.5 py-px font-mono text-[10.5px] uppercase tracking-wide text-fg-muted">
+                  {invoice.status}
+                </span>
+                <span className="font-mono text-[12px] tabular-nums text-fg">
+                  {invoice.totalAmount} {invoice.currency.toUpperCase()}
+                </span>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+
+      {error ? (
+        <p className="border-t border-hairline px-4 py-2 text-xs text-rose-400">
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}
diff --git a/components/dashboard/settings/BillingSection.tsx b/components/dashboard/settings/BillingSection.tsx
index 5ea5e4d..3cb5fd1 100644
--- a/components/dashboard/settings/BillingSection.tsx
+++ b/components/dashboard/settings/BillingSection.tsx
@@ -11,6 +11,7 @@ import {
   Trash2,
 } from "lucide-react";
 import { useAuth } from "@/components/dashboard/AuthContext";
+import Dialog from "@/components/design-system/Dialog";
 import {
   IconButton,
   SettingsCard,
@@ -18,37 +19,91 @@ import {
   ST_COLS_5,
   ST_HEAD_CLASS,
 } from "./SettingsPrimitives";
-import { useBillingPlans } from "@/lib/dashboard/useBillingPlans";
+import {
+  ResumeSubscriptionError,
+  ScheduledChangeConflictError,
+  useBillingPlans,
+} from "@/lib/dashboard/useBillingPlans";
 import { useBillingAccount } from "@/lib/dashboard/useBillingAccount";
-import type { DashboardBillingPlan } from "@/lib/dashboard/pymthouse-billing-bff";
+import type {
+  DashboardBillingPlan,
+  DashboardScheduledChangeConflict,
+} from "@/lib/dashboard/pymthouse-billing-bff";
 import {
   billingPlanActionLabel,
+  defaultCancelTimingChoice,
   deriveBillingPlanAction,
   deriveBillingSubscriptionUiState,
+  formatPendingCancelDate,
   isActiveSubscriptionConflict,
+  isNothingToResumeError,
+  resolveApplicablePendingCancel,
+  resolveCancelingEffectiveAt,
+  resolveCancelingPlanName,
+  resolveTimingPayload,
+  toDateInputValue,
   type BillingPlanAction,
+  type SubscriptionTimingChoice,
+  type SubscriptionTimingOptions,
 } from "@/lib/dashboard/billing-subscription-state";
 
+function isUsagePlan(plan: Pick<DashboardBillingPlan, "type">): boolean {
+  return plan.type.trim().toLowerCase() === "usage";
+}
+
+function formatUsdMicrosAsCurrency(usdMicros: string): string {
+  try {
+    const amount = Number(BigInt(usdMicros)) / 1_000_000;
+    return new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: "USD",
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2,
+    }).format(amount);
+  } catch {
+    return "$0.00";
+  }
+}
+
+function resolvedPayPerUseBehavior(plan: DashboardBillingPlan): string {
+  const resolved = plan.resolvedBehavior?.trim();
+  if (resolved) {
+    return resolved;
+  }
+
+  const threshold = plan.chargeThresholdUsdMicros?.trim();
+  if (threshold) {
+    return `Pay-per-use — charged at every ${formatUsdMicrosAsCurrency(
+      threshold
+    )} of usage (credits first).`;
+  }
+
+  return "Pay-per-use — usage settles against prepaid credits first, then auto-debits your default payment method.";
+}
+
 function formatPlanPrice(
-  amount: string,
-  currency: string,
-  cycle: string | null
+  plan: Pick<DashboardBillingPlan, "type" | "priceAmount" | "priceCurrency" | "billingCycle">
 ): { price: string; priceSub: string } {
-  const n = Number(amount);
+  const n = Number(plan.priceAmount);
   const money = Number.isFinite(n)
     ? new Intl.NumberFormat("en-US", {
         style: "currency",
-        currency: currency || "USD",
+        currency: plan.priceCurrency || "USD",
         maximumFractionDigits: n % 1 === 0 ? 0 : 2,
       }).format(n)
-    : amount;
-  const c = cycle?.toLowerCase() ?? "";
+    : plan.priceAmount;
+
+  if (plan.type.trim().toLowerCase() === "usage") {
+    return { price: money, priceSub: " · pay as you go" };
+  }
+
+  const c = plan.billingCycle?.toLowerCase() ?? "";
   if (c === "monthly" || c === "month")
     return { price: money, priceSub: " / month" };
   if (c === "yearly" || c === "year" || c === "annual") {
     return { price: money, priceSub: " / year" };
   }
-  return { price: money, priceSub: cycle ? ` · ${cycle}` : "" };
+  return { price: money, priceSub: plan.billingCycle ? ` · ${plan.billingCycle}` : "" };
 }
 
 function formatInvoiceAmount(totalAmount: string, currency: string): string {
@@ -91,6 +146,99 @@ function clearCheckoutQueryParam(): void {
   );
 }
 
+function TimingChoicePanel(props: {
+  title: string;
+  description: string;
+  options: SubscriptionTimingOptions | null | undefined;
+  choice: SubscriptionTimingChoice;
+  customDate: string;
+  confirmLabel: string;
+  busy: boolean;
+  onChoice: (choice: SubscriptionTimingChoice) => void;
+  onCustomDate: (ymd: string) => void;
+  onConfirm: () => void;
+  onClose: () => void;
+}) {
+  const min = toDateInputValue(props.options?.minEffectiveAt);
+  const max = toDateInputValue(props.options?.maxEffectiveAt);
+  return (
+    <div className="p-5">
+      <h2 className="text-base font-semibold text-fg">{props.title}</h2>
+      <p className="mt-1 text-[13px] text-fg-muted">{props.description}</p>
+      <div className="mt-4 space-y-2">
+        {(
+          [
+            {
+              id: "next_billing_cycle" as const,
+              label: "End of current period",
+              hint: props.options?.maxEffectiveAt
+                ? formatPendingCancelDate(props.options.maxEffectiveAt)
+                : "Keep access until the period ends",
+            },
+            {
+              id: "immediate" as const,
+              label: "Immediately",
+              hint: "Takes effect right away",
+            },
+            {
+              id: "custom" as const,
+              label: "Pick a date",
+              hint: min && max ? `${min} – ${max}` : "Choose a date in range",
+            },
+          ] as const
+        ).map((opt) => (
+          <label
+            key={opt.id}
+            className="flex cursor-pointer items-start gap-3 rounded-lg border border-hairline px-3 py-2.5 hover:bg-white/[0.02]"
+          >
+            <input
+              type="radio"
+              className="mt-1"
+              name="timing-choice"
+              checked={props.choice === opt.id}
+              onChange={() => props.onChoice(opt.id)}
+            />
+            <span>
+              <span className="block text-[13px] font-medium text-fg">
+                {opt.label}
+              </span>
+              <span className="block text-[12px] text-fg-muted">{opt.hint}</span>
+            </span>
+          </label>
+        ))}
+      </div>
+      {props.choice === "custom" ? (
+        <input
+          type="date"
+          className="mt-3 w-full rounded-md border border-hairline bg-transparent px-3 py-2 text-[13px] text-fg focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-green-bright/30"
+          min={min || undefined}
+          max={max || undefined}
+          value={props.customDate}
+          onChange={(e) => props.onCustomDate(e.target.value)}
+        />
+      ) : null}
+      <div className="mt-5 flex justify-end gap-2">
+        <button
+          type="button"
+          className="rounded-md px-3 py-1.5 text-[12.5px] text-fg-muted hover:text-fg"
+          onClick={props.onClose}
+          disabled={props.busy}
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          className="rounded-md bg-green-bright px-3 py-1.5 text-[12.5px] font-medium text-black disabled:opacity-50"
+          disabled={props.busy || (props.choice === "custom" && !props.customDate)}
+          onClick={props.onConfirm}
+        >
+          {props.busy ? "Working…" : props.confirmLabel}
+        </button>
+      </div>
+    </div>
+  );
+}
+
 /**
  * Organization · Billing — live plan, payment method, and invoices.
  * Fake company/tax/address “Billing details” removed (no API).
@@ -103,6 +251,8 @@ export default function BillingSection() {
     reload: reloadPlans,
     subscribe,
     changePlan,
+    cancelSubscription,
+    resumeSubscription,
   } = useBillingPlans(externalUserId);
   const {
     state: accountState,
@@ -115,6 +265,7 @@ export default function BillingSection() {
 
   const [busyPlanId, setBusyPlanId] = useState<string | null>(null);
   const [pmBusy, setPmBusy] = useState(false);
+  const [lifecycleBusy, setLifecycleBusy] = useState(false);
   const [paymentMethodActionId, setPaymentMethodActionId] = useState<
     string | null
   >(null);
@@ -123,6 +274,19 @@ export default function BillingSection() {
   const [billingNotice, setBillingNotice] = useState<string | null>(null);
   const [flash, setFlash] = useState<"success" | "cancel" | null>(null);
 
+  const [cancelDialogOpen, setCancelDialogOpen] = useState(false);
+  const [cancelChoice, setCancelChoice] = useState<SubscriptionTimingChoice>(
+    defaultCancelTimingChoice()
+  );
+  const [cancelCustomDate, setCancelCustomDate] = useState("");
+  const [changeDialog, setChangeDialog] = useState<{
+    planId: string;
+    conflict: DashboardScheduledChangeConflict | null;
+  } | null>(null);
+  const [changeChoice, setChangeChoice] =
+    useState<SubscriptionTimingChoice>("immediate");
+  const [changeCustomDate, setChangeCustomDate] = useState("");
+
   useEffect(() => {
     const next = readCheckoutFlash();
     if (!next) return;
@@ -134,6 +298,55 @@ export default function BillingSection() {
     }
   }, [reloadPlans, reloadAccount]);
 
+  async function ensurePaymentMethodForUsagePlan(planId: string) {
+    if (!externalUserId) return;
+    const plan = (
+      plansState.status === "ready" ? plansState.plans : []
+    ).find((p) => p.id === planId);
+    if (!plan || !isUsagePlan(plan)) return;
+
+    // Pay-per-use needs a card for threshold auto-debit. If plan change did
+    // not return Checkout (older pymthouse), start setup-mode Checkout here.
+    try {
+      const { checkoutUrl } = await startPaymentMethodCheckout({
+        externalUserId,
+      });
+      window.location.assign(checkoutUrl);
+    } catch (err) {
+      const message =
+        err instanceof Error ? err.message : "Payment method checkout failed";
+      setBillingNotice(
+        "Pay-per-use plan is active. Add a card below so usage can auto-debit after prepaid credits.",
+      );
+      setError(message);
+    }
+  }
+
+  async function runChangePlan(
+    planId: string,
+    timing?: {
+      timing?: string;
+      effectiveAt?: string;
+      confirmReplaceScheduled?: boolean;
+    }
+  ) {
+    if (!externalUserId) return;
+    const result = await changePlan({
+      planId,
+      externalUserId,
+      successUrl: `${window.location.origin}/settings?tab=billing&checkout=success`,
+      cancelUrl: `${window.location.origin}/settings?tab=billing&checkout=cancel`,
+      ...timing,
+    });
+    if (result.checkoutUrl) {
+      window.location.assign(result.checkoutUrl);
+      return;
+    }
+    await reloadPlans();
+    setBillingNotice("Your plan has been updated.");
+    await ensurePaymentMethodForUsagePlan(planId);
+  }
+
   async function onPlanAction(planId: string, action: BillingPlanAction) {
     if (!externalUserId) {
       setError("Sign in to subscribe.");
@@ -147,6 +360,23 @@ export default function BillingSection() {
     setBillingNotice(null);
     setBusyPlanId(planId);
     try {
+      if (action === "change_plan") {
+        try {
+          await runChangePlan(planId);
+        } catch (err) {
+          if (err instanceof ScheduledChangeConflictError) {
+            setChangeChoice("immediate");
+            setChangeCustomDate(
+              toDateInputValue(err.conflict.timingOptions?.minEffectiveAt)
+            );
+            setChangeDialog({ planId, conflict: err.conflict });
+            return;
+          }
+          throw err;
+        }
+        return;
+      }
+
       const input = {
         planId:
           action === "retry_checkout"
@@ -156,10 +386,7 @@ export default function BillingSection() {
         successUrl: `${window.location.origin}/settings?tab=billing&checkout=success`,
         cancelUrl: `${window.location.origin}/settings?tab=billing&checkout=cancel`,
       };
-      const result =
-        action === "change_plan"
-          ? await changePlan(input)
-          : await subscribe(input);
+      const result = await subscribe(input);
 
       if (result.checkoutUrl) {
         window.location.assign(result.checkoutUrl);
@@ -183,6 +410,110 @@ export default function BillingSection() {
     }
   }
 
+  function openCancelDialog() {
+    setCancelChoice(defaultCancelTimingChoice());
+    setCancelCustomDate(
+      toDateInputValue(subscription?.timingOptions?.cancel.minEffectiveAt)
+    );
+    setCancelDialogOpen(true);
+  }
+
+  async function onConfirmCancel() {
+    if (!externalUserId) {
+      setError("Sign in to cancel.");
+      return;
+    }
+    setError(null);
+    setBillingNotice(null);
+    setLifecycleBusy(true);
+    try {
+      const payload = resolveTimingPayload({
+        choice: cancelChoice,
+        customDateYmd: cancelCustomDate,
+      });
+      await cancelSubscription(externalUserId, payload);
+      setCancelDialogOpen(false);
+      await reloadPlans();
+      setBillingNotice(
+        cancelChoice === "immediate"
+          ? "Your subscription has been canceled."
+          : `Cancellation scheduled${
+              payload.effectiveAt
+                ? ` for ${formatPendingCancelDate(payload.effectiveAt)}`
+                : " for the end of this period"
+            }.`
+      );
+    } catch (err) {
+      setError(
+        err instanceof Error ? err.message : "Could not cancel subscription"
+      );
+    } finally {
+      setLifecycleBusy(false);
+    }
+  }
+
+  async function onConfirmChangeTiming() {
+    if (!externalUserId || !changeDialog) return;
+    setError(null);
+    setBillingNotice(null);
+    setBusyPlanId(changeDialog.planId);
+    try {
+      const payload = resolveTimingPayload({
+        choice: changeChoice,
+        customDateYmd: changeCustomDate,
+      });
+      await runChangePlan(changeDialog.planId, {
+        ...payload,
+        confirmReplaceScheduled: true,
+      });
+      setChangeDialog(null);
+    } catch (err) {
+      setError(
+        err instanceof Error ? err.message : "Could not change subscription"
+      );
+    } finally {
+      setBusyPlanId(null);
+    }
+  }
+
+  async function onCancelSubscription() {
+    openCancelDialog();
+  }
+
+  async function onResumeSubscription() {
+    if (!externalUserId) {
+      setError("Sign in to restore your plan.");
+      return;
+    }
+    setError(null);
+    setBillingNotice(null);
+    setFlash(null);
+    setLifecycleBusy(true);
+    try {
+      await resumeSubscription(externalUserId);
+      await reloadPlans();
+      setBillingNotice("Your plan will continue — cancellation removed.");
+    } catch (err) {
+      // Nothing left to undo upstream — the local snapshot is stale, so reload
+      // it and drop the banner rather than stranding an error.
+      if (
+        err instanceof ResumeSubscriptionError &&
+        isNothingToResumeError(err.code)
+      ) {
+        await reloadPlans();
+        setBillingNotice(
+          "No scheduled cancellation is pending — your plan is up to date."
+        );
+        return;
+      }
+      setError(
+        err instanceof Error ? err.message : "Could not restore subscription"
+      );
+    } finally {
+      setLifecycleBusy(false);
+    }
+  }
+
   async function onAddCard() {
     if (!externalUserId) {
       setError("Sign in to add a payment method.");
@@ -270,13 +601,26 @@ export default function BillingSection() {
     accountState.status === "ready" ? accountState.paymentMethods : [];
   const invoices = accountState.status === "ready" ? accountState.invoices : [];
 
+  const cancelingPlanName = resolveCancelingPlanName(subscription);
+  const cancelingEndsAt = resolveCancelingEffectiveAt(subscription);
+  const cancelingEndsLabel = formatPendingCancelDate(cancelingEndsAt);
+
   const planSub =
-    subscription?.planName?.trim() ||
-    (subscriptionUiState.kind === "pending"
-      ? "Payment needs to be completed"
-      : subscriptionUiState.kind === "active"
-        ? "Current subscription"
-        : "Choose a plan to get started");
+    subscriptionUiState.kind === "canceling"
+      ? `${cancelingPlanName} ends ${cancelingEndsLabel}`
+      : subscription?.planName?.trim() ||
+        (subscriptionUiState.kind === "pending"
+          ? "Payment needs to be completed"
+          : subscriptionUiState.kind === "active"
+            ? "Current subscription"
+            : "Choose a plan to get started");
+
+  const canCancel =
+    Boolean(externalUserId) && subscriptionUiState.kind === "active";
+  const canResume =
+    Boolean(externalUserId) &&
+    Boolean(resolveApplicablePendingCancel(subscription));
+  const showCancelingBanner = subscriptionUiState.kind === "canceling";
 
   return (
     <div>
@@ -299,7 +643,55 @@ export default function BillingSection() {
         </p>
       ) : null}
 
-      <SettingsHeader title="Plan" sub={planSub} />
+      {showCancelingBanner ? (
+        <div className="mb-4 rounded-xl border border-hairline bg-white/[0.02] px-4 py-4">
+          <p className="text-[13.5px] font-medium text-fg">
+            Ends at end of current period
+          </p>
+          <p className="mt-1 text-[12.5px] text-fg-muted">
+            {cancelingPlanName} stays active until {cancelingEndsLabel}. You
+            chose to let it expire at the end of the current period — access
+            continues until then. Switching to another plan replaces this
+            remaining period.
+          </p>
+          {canResume ? (
+            <button
+              type="button"
+              className="mt-3 rounded-md bg-green-bright px-3 py-1.5 text-[12.5px] font-medium text-black disabled:opacity-50"
+              disabled={lifecycleBusy}
+              onClick={() => void onResumeSubscription()}
+            >
+              {lifecycleBusy ? "Restoring…" : `Keep ${cancelingPlanName}`}
+            </button>
+          ) : null}
+        </div>
+      ) : null}
+
+      <SettingsHeader
+        title="Plan"
+        sub={planSub}
+        action={
+          canCancel ? (
+            <button
+              type="button"
+              className="text-[12.5px] text-fg-muted underline-offset-2 transition-colors hover:text-fg hover:underline disabled:opacity-50"
+              disabled={lifecycleBusy || busyPlanId !== null}
+              onClick={() => void onCancelSubscription()}
+            >
+              {lifecycleBusy ? "Canceling…" : "Cancel subscription"}
+            </button>
+          ) : canResume ? (
+            <button
+              type="button"
+              className="text-[12.5px] text-green-bright underline-offset-2 hover:underline disabled:opacity-50"
+              disabled={lifecycleBusy}
+              onClick={() => void onResumeSubscription()}
+            >
+              {lifecycleBusy ? "Restoring…" : "Restore plan"}
+            </button>
+          ) : undefined
+        }
+      />
       <SettingsCard>
         {plansLoading ? (
           <div className="animate-pulse p-[18px]">
@@ -337,15 +729,13 @@ export default function BillingSection() {
               const isPending =
                 subscriptionUiState.kind === "pending" &&
                 subscriptionUiState.planId === plan.id;
-              const { price, priceSub } = formatPlanPrice(
-                plan.priceAmount,
-                plan.priceCurrency,
-                plan.billingCycle
-              );
+              const { price, priceSub } = formatPlanPrice(plan);
               const features = [
-                plan.billingCycle
-                  ? `${plan.billingCycle} billing`
-                  : "Usage-based billing",
+                isUsagePlan(plan)
+                  ? resolvedPayPerUseBehavior(plan)
+                  : plan.billingCycle
+                    ? `${plan.billingCycle} billing`
+                    : "Usage-based billing",
                 plan.capabilityCount > 0
                   ? `${plan.capabilityCount} capabilities`
                   : "All included capabilities",
@@ -377,7 +767,7 @@ export default function BillingSection() {
 
       <SettingsHeader
         title="Payment method"
-        sub="Card on file for subscription and usage charges"
+        sub="Card on file for subscription charges and pay-per-use auto-debit"
         action={
           <IconButton
             primary
@@ -399,6 +789,9 @@ export default function BillingSection() {
             <p className="text-[13px] text-fg-muted">
               Could not load payment methods.
             </p>
+            <p className="mt-1 font-mono text-[12px] text-fg-faint">
+              {accountState.message}
+            </p>
             <button
               type="button"
               className="mt-2 text-[12.5px] text-fg-strong underline"
@@ -486,6 +879,9 @@ export default function BillingSection() {
             <p className="text-[13px] text-fg-muted">
               Could not load invoices.
             </p>
+            <p className="mt-1 font-mono text-[12px] text-fg-faint">
+              {accountState.message}
+            </p>
             <button
               type="button"
               className="mt-2 text-[12.5px] text-fg-strong underline"
@@ -548,6 +944,53 @@ export default function BillingSection() {
           </>
         )}
       </SettingsCard>
+
+      <Dialog
+        open={cancelDialogOpen}
+        onClose={() => {
+          if (!lifecycleBusy) setCancelDialogOpen(false);
+        }}
+        maxWidth="max-w-[420px]"
+      >
+        <TimingChoicePanel
+          title="Cancel subscription"
+          description="Choose when access should end. You can restore anytime before then if you pick a future date."
+          options={subscription?.timingOptions?.cancel}
+          choice={cancelChoice}
+          customDate={cancelCustomDate}
+          confirmLabel="Confirm cancel"
+          busy={lifecycleBusy}
+          onChoice={setCancelChoice}
+          onCustomDate={setCancelCustomDate}
+          onConfirm={() => void onConfirmCancel()}
+          onClose={() => setCancelDialogOpen(false)}
+        />
+      </Dialog>
+
+      <Dialog
+        open={changeDialog !== null}
+        onClose={() => {
+          if (busyPlanId === null) setChangeDialog(null);
+        }}
+        maxWidth="max-w-[420px]"
+      >
+        <TimingChoicePanel
+          title="Replace scheduled plan change?"
+          description="A plan change is already scheduled. Choosing a start time replaces that schedule with your new plan."
+          options={
+            changeDialog?.conflict?.timingOptions ??
+            subscription?.timingOptions?.change
+          }
+          choice={changeChoice}
+          customDate={changeCustomDate}
+          confirmLabel="Confirm switch"
+          busy={busyPlanId !== null}
+          onChoice={setChangeChoice}
+          onCustomDate={setChangeCustomDate}
+          onConfirm={() => void onConfirmChangeTiming()}
+          onClose={() => setChangeDialog(null)}
+        />
+      </Dialog>
     </div>
   );
 }
@@ -643,7 +1086,11 @@ function LivePlanCard({
             : "btn-primary"
         }`}
       >
-        {busy ? "Working…" : billingPlanActionLabel(action)}
+        {busy
+          ? "Working…"
+          : billingPlanActionLabel(action, {
+              usagePlan: isUsagePlan(plan),
+            })}
         {action !== "current" && !busy ? (
           <ArrowRight className="h-2.5 w-2.5" aria-hidden="true" />
         ) : null}
diff --git a/lib/dashboard/billing-subscription-state.test.ts b/lib/dashboard/billing-subscription-state.test.ts
index 2e4bc9a..4f1cab2 100644
--- a/lib/dashboard/billing-subscription-state.test.ts
+++ b/lib/dashboard/billing-subscription-state.test.ts
@@ -1,8 +1,15 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import {
+  dateInputToEffectiveAtIso,
+  defaultCancelTimingChoice,
   deriveBillingPlanAction,
   deriveBillingSubscriptionUiState,
+  formatPendingCancelDate,
+  isNothingToResumeError,
+  resolveApplicablePendingCancel,
+  resolveTimingPayload,
+  toDateInputValue,
 } from "./billing-subscription-state";
 
 test("derives no subscription as a subscribe state", () => {
@@ -33,3 +40,212 @@ test("routes pending subscriptions to checkout retry", () => {
   assert.equal(deriveBillingPlanAction(state, "pro"), "retry_checkout");
   assert.equal(deriveBillingPlanAction(state, "scale"), "retry_checkout");
 });
+
+test("cancel-at-period-end is canceling from pendingCancel or inactive status", () => {
+  const fromPending = deriveBillingSubscriptionUiState({
+    planId: "starter",
+    status: "canceled",
+    currentPeriodEnd: "2026-09-07T17:35:18.109Z",
+    pendingCancel: {
+      subscriptionId: "sub_starter",
+      planId: "starter",
+      planName: "Starter",
+      effectiveAt: "2026-09-07T17:35:18.109Z",
+    },
+  });
+  assert.deepEqual(fromPending, { kind: "canceling", planId: "starter" });
+  assert.equal(deriveBillingPlanAction(fromPending, "starter"), "current");
+  assert.equal(deriveBillingPlanAction(fromPending, "pro"), "change_plan");
+
+  const fromInactive = deriveBillingSubscriptionUiState({
+    planId: "starter",
+    status: "inactive",
+    currentPeriodEnd: "2026-09-07T17:35:18.109Z",
+  });
+  assert.deepEqual(fromInactive, { kind: "canceling", planId: "starter" });
+
+  // pendingCancel alone (no subscription.planId) still surfaces canceling
+  const pendingOnly = deriveBillingSubscriptionUiState({
+    planId: null,
+    status: null,
+    pendingCancel: {
+      subscriptionId: "sub_starter",
+      planId: "starter",
+      effectiveAt: "2026-09-07T17:35:18.109Z",
+    },
+  });
+  assert.deepEqual(pendingOnly, { kind: "canceling", planId: "starter" });
+});
+
+test("a pendingCancel for a superseded plan is ignored", () => {
+  const subscription = {
+    planId: "payg",
+    planName: "Pay as you go",
+    status: "active",
+    pendingCancel: {
+      subscriptionId: "sub_m2m",
+      planId: "m2m",
+      planName: "m2m user plan",
+      effectiveAt: "2026-09-07T17:35:18.109Z",
+    },
+  };
+
+  const state = deriveBillingSubscriptionUiState(subscription);
+  assert.deepEqual(state, { kind: "active", planId: "payg" });
+  assert.equal(deriveBillingPlanAction(state, "payg"), "current");
+  assert.equal(deriveBillingPlanAction(state, "m2m"), "change_plan");
+  assert.equal(resolveApplicablePendingCancel(subscription), null);
+});
+
+test("isNothingToResumeError reconciles only the upstream nothing_to_resume code", () => {
+  assert.equal(isNothingToResumeError("nothing_to_resume"), true);
+  // Sibling resume branches are real failures, whatever their status class.
+  assert.equal(isNothingToResumeError("resume_failed"), false);
+  assert.equal(isNothingToResumeError("confirm_required"), false);
+  assert.equal(isNothingToResumeError("openmeter_unavailable"), false);
+  // An unrelated 4xx (401/403/404) carries no code, or the SDK's sentinel.
+  assert.equal(isNothingToResumeError("pymthouse_http_error"), false);
+  assert.equal(isNothingToResumeError(undefined), false);
+});
+
+test("resume errors are classified by code, not status class", async () => {
+  const { ResumeSubscriptionError } = await import("./useBillingPlans");
+
+  const nothingToResume = new ResumeSubscriptionError(
+    "No scheduled cancellation to undo",
+    404,
+    "nothing_to_resume",
+  );
+  assert.equal(isNothingToResumeError(nothingToResume.code), true);
+
+  // 502 resume_failed: a resume target existed but Konnect restore threw.
+  const resumeFailed = new ResumeSubscriptionError(
+    "Could not cancel the scheduled cancellation",
+    502,
+    "resume_failed",
+  );
+  assert.equal(isNothingToResumeError(resumeFailed.code), false);
+
+  // Unrelated 4xx that the old status heuristic wrongly reported as success.
+  const unauthorized = new ResumeSubscriptionError("Unauthorized", 401, undefined);
+  assert.equal(isNothingToResumeError(unauthorized.code), false);
+  const unrelatedNotFound = new ResumeSubscriptionError(
+    "Not Found",
+    404,
+    "pymthouse_http_error",
+  );
+  assert.equal(isNothingToResumeError(unrelatedNotFound.code), false);
+});
+
+test("user-not-found is recognized with and without an upstream code", async () => {
+  const { PmtHouseError } = await import("@pymthouse/builder-sdk");
+  const { isUserNotFoundError } = await import("./pymthouse-bff");
+
+  // The mint-token route answers `{"error":"not_found"}` with no `code`, so the
+  // SDK reports code as its `pymthouse_http_error` sentinel — auto-provisioning
+  // must still trigger.
+  assert.equal(
+    isUserNotFoundError(
+      new PmtHouseError("not_found", {
+        status: 404,
+        code: "pymthouse_http_error",
+        details: { error: "not_found" },
+      }),
+    ),
+    true,
+  );
+  // REST shape: prose on message, machine code on `code`.
+  assert.equal(
+    isUserNotFoundError(
+      new PmtHouseError("App user not found", {
+        status: 404,
+        code: "not_found",
+        details: { error: "App user not found", code: "not_found" },
+      }),
+    ),
+    true,
+  );
+  // An unrelated 404 must not provision a user.
+  assert.equal(
+    isUserNotFoundError(
+      new PmtHouseError("Subscription not found", {
+        status: 404,
+        code: "pymthouse_http_error",
+        details: { error: "Subscription not found" },
+      }),
+    ),
+    false,
+  );
+  assert.equal(
+    isUserNotFoundError(
+      new PmtHouseError("boom", { status: 500, code: "not_found" }),
+    ),
+    false,
+  );
+  assert.equal(isUserNotFoundError(new Error("network down")), false);
+});
+
+test("resolveCancelingEffectiveAt prefers pendingCancel then period end", async () => {
+  const {
+    resolveCancelingEffectiveAt,
+    resolveCancelingPlanName,
+  } = await import("./billing-subscription-state");
+  assert.equal(
+    resolveCancelingEffectiveAt({
+      planId: "starter",
+      status: "canceled",
+      currentPeriodEnd: "2026-09-01T00:00:00.000Z",
+      pendingCancel: {
+        subscriptionId: "s1",
+        effectiveAt: "2026-09-07T17:35:18.109Z",
+      },
+    }),
+    "2026-09-07T17:35:18.109Z",
+  );
+  assert.equal(
+    resolveCancelingPlanName({
+      planName: "__pymthouse_starter__",
+      pendingCancel: { planName: "Starter" },
+    }),
+    "Starter",
+  );
+});
+
+test("formatPendingCancelDate formats UTC calendar day", () => {
+  assert.equal(
+    formatPendingCancelDate("2026-08-20T12:00:00.000Z"),
+    "Aug 20, 2026",
+  );
+  assert.equal(formatPendingCancelDate(null), "the end of this period");
+  assert.equal(
+    formatPendingCancelDate("not-a-date"),
+    "the end of this period",
+  );
+});
+
+test("cancel timing helpers default to end of cycle and map date inputs", () => {
+  assert.equal(defaultCancelTimingChoice(), "next_billing_cycle");
+  assert.equal(toDateInputValue("2026-08-08T00:00:00.000Z"), "2026-08-08");
+  assert.equal(
+    dateInputToEffectiveAtIso("2026-08-15"),
+    "2026-08-15T12:00:00.000Z",
+  );
+  assert.deepEqual(
+    resolveTimingPayload({
+      choice: "next_billing_cycle",
+      customDateYmd: "",
+    }),
+    { timing: "next_billing_cycle" },
+  );
+  assert.deepEqual(
+    resolveTimingPayload({ choice: "immediate", customDateYmd: "" }),
+    { timing: "immediate" },
+  );
+  assert.deepEqual(
+    resolveTimingPayload({
+      choice: "custom",
+      customDateYmd: "2026-08-15",
+    }),
+    { effectiveAt: "2026-08-15T12:00:00.000Z" },
+  );
+});
diff --git a/lib/dashboard/billing-subscription-state.ts b/lib/dashboard/billing-subscription-state.ts
index 68a477d..babb948 100644
--- a/lib/dashboard/billing-subscription-state.ts
+++ b/lib/dashboard/billing-subscription-state.ts
@@ -1,12 +1,32 @@
+export type PendingCancelSnapshot = {
+  subscriptionId?: string;
+  planId?: string | null;
+  planName?: string | null;
+  effectiveAt?: string | null;
+};
+
 export type BillingSubscriptionSnapshot = {
   planId: string | null;
   status: string | null;
+  currentPeriodEnd?: string | null;
+  pendingCancel?: PendingCancelSnapshot | null;
+  timingOptions?: {
+    cancel: SubscriptionTimingOptions;
+    change: SubscriptionTimingOptions;
+  } | null;
+};
+
+export type SubscriptionTimingOptions = {
+  minEffectiveAt: string;
+  maxEffectiveAt: string | null;
+  presets: Array<"immediate" | "next_billing_cycle">;
 };
 
 export type BillingSubscriptionUiState =
   | { kind: "none"; planId: null }
   | { kind: "active"; planId: string }
-  | { kind: "pending"; planId: string };
+  | { kind: "pending"; planId: string }
+  | { kind: "canceling"; planId: string };
 
 export type BillingPlanAction =
   | "subscribe"
@@ -14,6 +34,11 @@ export type BillingPlanAction =
   | "retry_checkout"
   | "current";
 
+export type SubscriptionTimingChoice =
+  | "immediate"
+  | "next_billing_cycle"
+  | "custom";
+
 const ACTIVE_STATUSES = new Set(["active", "trialing", "scheduled"]);
 const PENDING_STATUSES = new Set([
   "pending",
@@ -21,16 +46,58 @@ const PENDING_STATUSES = new Set([
   "incomplete_expired",
   "checkout_pending",
 ]);
+/** Includes Konnect `inactive` (cancel-at-period-end still occupying the slot). */
+const CANCELED_STATUSES = new Set(["canceled", "cancelled", "inactive"]);
+
+/** Sentinel when cancel-at-period-end is known but local plan id is missing. */
+const CANCELING_PLAN_FALLBACK = "__canceling__";
+
+/**
+ * pendingCancel that actually applies to the live subscription.
+ *
+ * Upstream reports any occupying canceled OpenMeter row, so a cancel scheduled
+ * on a plan the user has since switched away from keeps being returned. That
+ * stale row must not drive canceling UI or the resume CTA — resume would 4xx
+ * because there is no scheduled cancellation left to undo.
+ */
+export function resolveApplicablePendingCancel(
+  subscription:
+    | {
+        planId?: string | null;
+        pendingCancel?: PendingCancelSnapshot | null;
+      }
+    | null
+    | undefined
+): PendingCancelSnapshot | null {
+  const pending = subscription?.pendingCancel;
+  if (!pending) return null;
+  const activePlanId = subscription?.planId?.trim();
+  const pendingPlanId = pending.planId?.trim();
+  if (activePlanId && pendingPlanId && activePlanId !== pendingPlanId) {
+    return null;
+  }
+  return pending;
+}
 
 export function deriveBillingSubscriptionUiState(
   subscription: BillingSubscriptionSnapshot | null | undefined
 ): BillingSubscriptionUiState {
-  const planId = subscription?.planId?.trim() || null;
+  const pending = resolveApplicablePendingCancel(subscription);
+  const planId =
+    subscription?.planId?.trim() || pending?.planId?.trim() || null;
+  const status = subscription?.status?.trim().toLowerCase() || "";
+  const isCanceling = Boolean(pending) || CANCELED_STATUSES.has(status);
+
+  // Cancel-at-period-end still owns the OpenMeter customer until effectiveAt /
+  // currentPeriodEnd — surface that even when planId is only on pendingCancel.
+  if (isCanceling) {
+    return { kind: "canceling", planId: planId || CANCELING_PLAN_FALLBACK };
+  }
+
   if (!planId) {
     return { kind: "none", planId: null };
   }
 
-  const status = subscription?.status?.trim().toLowerCase() || "";
   if (PENDING_STATUSES.has(status)) {
     return { kind: "pending", planId };
   }
@@ -51,22 +118,118 @@ export function deriveBillingPlanAction(
   if (subscription.kind === "pending") {
     return "retry_checkout";
   }
+  // canceling still treats current plan as current; other plans can switch/upgrade
   return subscription.planId === planId ? "current" : "change_plan";
 }
 
-export function billingPlanActionLabel(action: BillingPlanAction): string {
+export function billingPlanActionLabel(
+  action: BillingPlanAction,
+  opts?: { usagePlan?: boolean },
+): string {
   switch (action) {
     case "current":
       return "Current plan";
     case "change_plan":
-      return "Switch";
+      return opts?.usagePlan ? "Enable pay-per-use" : "Switch";
     case "retry_checkout":
       return "Complete payment";
     case "subscribe":
-      return "Subscribe";
+      return opts?.usagePlan ? "Enable pay-per-use" : "Subscribe";
   }
 }
 
 export function isActiveSubscriptionConflict(message: string): boolean {
   return /already has an active subscription/i.test(message);
 }
+
+export function isScheduledChangeConflict(code: string | undefined): boolean {
+  return code === "scheduled_change_exists";
+}
+
+/**
+ * End date for cancel-at-period-end, from builder/OpenMeter
+ * (`pendingCancel.effectiveAt` or subscription `currentPeriodEnd`).
+ */
+export function resolveCancelingEffectiveAt(
+  subscription: BillingSubscriptionSnapshot | null | undefined
+): string | null {
+  return (
+    resolveApplicablePendingCancel(subscription)?.effectiveAt?.trim() ||
+    subscription?.currentPeriodEnd?.trim() ||
+    null
+  );
+}
+
+/** Human plan label for the canceling banner / restore CTA. */
+export function resolveCancelingPlanName(
+  subscription: {
+    planId?: string | null;
+    planName?: string | null;
+    pendingCancel?: PendingCancelSnapshot | null;
+  } | null | undefined
+): string {
+  return (
+    resolveApplicablePendingCancel(subscription)?.planName?.trim() ||
+    subscription?.planName?.trim() ||
+    "your plan"
+  );
+}
+
+/**
+ * Upstream answers resume with `404 { code: "nothing_to_resume" }` when there
+ * is no scheduled cancellation left to undo. The local snapshot is simply
+ * stale, so reconcile instead of surfacing an error.
+ *
+ * Keyed on the code alone, never on the status class: the sibling resume
+ * branches (`confirm_required` 400, `resume_failed` 502, `openmeter_unavailable`
+ * 503) and any auth failure are real errors the user must see.
+ */
+export function isNothingToResumeError(code: string | undefined): boolean {
+  return code === "nothing_to_resume";
+}
+
+export function formatPendingCancelDate(
+  iso: string | null | undefined
+): string {
+  if (!iso) return "the end of this period";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "the end of this period";
+  return d.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    timeZone: "UTC",
+  });
+}
+
+/** YYYY-MM-DD for `<input type="date">` min/max (UTC calendar day). */
+export function toDateInputValue(iso: string | null | undefined): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  return d.toISOString().slice(0, 10);
+}
+
+/** Noon UTC on the chosen calendar day — stable for Konnect ISO timing. */
+export function dateInputToEffectiveAtIso(dateYmd: string): string {
+  const [y, m, d] = dateYmd.split("-").map((p) => Number.parseInt(p, 10));
+  if (!y || !m || !d) {
+    throw new Error("Invalid date");
+  }
+  return new Date(Date.UTC(y, m - 1, d, 12, 0, 0, 0)).toISOString();
+}
+
+export function defaultCancelTimingChoice(): SubscriptionTimingChoice {
+  return "next_billing_cycle";
+}
+
+export function resolveTimingPayload(input: {
+  choice: SubscriptionTimingChoice;
+  customDateYmd: string;
+}): { timing?: "immediate" | "next_billing_cycle"; effectiveAt?: string } {
+  if (input.choice === "immediate") return { timing: "immediate" };
+  if (input.choice === "next_billing_cycle") {
+    return { timing: "next_billing_cycle" };
+  }
+  return { effectiveAt: dateInputToEffectiveAtIso(input.customDateYmd) };
+}
diff --git a/lib/dashboard/pymthouse-bff.ts b/lib/dashboard/pymthouse-bff.ts
index 90a45d2..d51cefa 100644
--- a/lib/dashboard/pymthouse-bff.ts
+++ b/lib/dashboard/pymthouse-bff.ts
@@ -294,6 +294,24 @@ function issuerOriginFromConfig(): string {
   return new URL(config.issuerUrl).origin;
 }
 
+/**
+ * Pymthouse signals user-not-found with two envelopes: the REST shape
+ * (`{ error: <prose>, code: "not_found" }`) and the OAuth shape used by the
+ * mint-token route (`{ error: "not_found" }`, no `code` — the SDK then reports
+ * `code` as `pymthouse_http_error`). Accept both, matching the SDK's own
+ * `isUserNotFoundError`.
+ */
+export function isUserNotFoundError(error: unknown): boolean {
+  if (!(error instanceof PmtHouseError) || error.status !== 404) {
+    return false;
+  }
+  if (error.code === "not_found") {
+    return true;
+  }
+  const details = error.details as { error?: unknown } | null | undefined;
+  return details?.error === "not_found";
+}
+
 async function mintEndUserAccessToken(
   client: PmtHouseClient,
   externalUserId: string,
@@ -302,11 +320,7 @@ async function mintEndUserAccessToken(
     const minted = await client.mintUserAccessToken({ externalUserId });
     return minted.access_token;
   } catch (error) {
-    if (
-      error instanceof PmtHouseError &&
-      error.status === 404 &&
-      error.code === "not_found"
-    ) {
+    if (isUserNotFoundError(error)) {
       await client.upsertAppUser({ externalUserId });
       const minted = await client.mintUserAccessToken({ externalUserId });
       return minted.access_token;
diff --git a/lib/dashboard/pymthouse-billing-bff.ts b/lib/dashboard/pymthouse-billing-bff.ts
index ee4f7ad..83a66b6 100644
--- a/lib/dashboard/pymthouse-billing-bff.ts
+++ b/lib/dashboard/pymthouse-billing-bff.ts
@@ -87,10 +87,25 @@ export type DashboardBillingPlan = {
   priceAmount: string;
   priceCurrency: string;
   billingCycle: string | null;
+  chargeThresholdUsdMicros: string | null;
+  resolvedBehavior: string | null;
   capabilityCount: number;
 };
 
+function readOptionalString(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
 function mapProduct(product: BillingProduct): DashboardBillingPlan {
+  // PymtHouse sends these fields for usage plans; keep the mapping resilient
+  // until the SDK's BillingProduct type guarantees them.
+  const dynamicProduct = product as BillingProduct & {
+    chargeThresholdUsdMicros?: unknown;
+    resolvedBehavior?: unknown;
+  };
+
   return {
     id: product.id,
     name: product.name,
@@ -99,6 +114,10 @@ function mapProduct(product: BillingProduct): DashboardBillingPlan {
     priceAmount: product.priceAmount,
     priceCurrency: product.priceCurrency,
     billingCycle: product.allowance?.billingCycle ?? null,
+    chargeThresholdUsdMicros: readOptionalString(
+      dynamicProduct.chargeThresholdUsdMicros
+    ),
+    resolvedBehavior: readOptionalString(dynamicProduct.resolvedBehavior),
     capabilityCount: product.capabilities?.length ?? 0,
   };
 }
@@ -109,11 +128,38 @@ export async function listDashboardBillingPlans(): Promise<
 > {
   const client = createPmtHouseClientForPublicApp(readPublicClientId());
   const { products } = await client.listBillingProducts();
-  return (products ?? [])
+  const plans = (products ?? [])
     .filter(
       (p) => p.status === "active" && !p.isNetworkDefault && !p.isStarterDefault
     )
     .map(mapProduct);
+
+  // The apiVersion=2 billing-product shape omits chargeThresholdUsdMicros /
+  // resolvedBehavior (pymthouse toBillingProduct). The owner wallet summary
+  // (pymthouse PR #399) carries them per active usage plan — hydrate from it.
+  const needsHydration = plans.some(
+    (p) =>
+      p.type.trim().toLowerCase() === "usage" &&
+      (!p.chargeThresholdUsdMicros || !p.resolvedBehavior)
+  );
+  if (needsHydration) {
+    try {
+      const wallet = await getDashboardOwnerWallet();
+      const byPlanId = new Map(
+        wallet.payPerUsePlans.map((p) => [p.planId, p])
+      );
+      for (const plan of plans) {
+        const walletPlan = byPlanId.get(plan.id);
+        if (!walletPlan) continue;
+        plan.chargeThresholdUsdMicros ??= walletPlan.chargeThresholdUsdMicros;
+        plan.resolvedBehavior ??= walletPlan.resolvedBehavior;
+      }
+    } catch {
+      // Wallet API unavailable (older pymthouse deploy) — keep fields null and
+      // let the UI fall back to its generic pay-per-use copy.
+    }
+  }
+  return plans;
 }
 
 export async function startDashboardBillingCheckout(input: {
@@ -135,15 +181,31 @@ export type DashboardSubscriptionChange = {
   subscriptionId: string;
   planId: string;
   effectiveAt: string | null;
-  timing: "immediate" | "next_billing_cycle";
+  timing: "immediate" | "next_billing_cycle" | string;
   checkoutUrl?: string;
 };
 
+export type DashboardScheduledChangeConflict = {
+  code: "scheduled_change_exists";
+  error: string;
+  timingOptions: {
+    minEffectiveAt: string;
+    maxEffectiveAt: string | null;
+    presets: Array<"immediate" | "next_billing_cycle">;
+  } | null;
+  scheduledSubscriptionId: string | null;
+  scheduledPlanKey: string | null;
+  scheduledActiveFrom: string | null;
+};
+
 export async function changeDashboardBillingSubscription(input: {
   planId: string;
   externalUserId: string;
   successUrl?: string;
   cancelUrl?: string;
+  timing?: string;
+  effectiveAt?: string;
+  confirmReplaceScheduled?: boolean;
 }): Promise<DashboardSubscriptionChange> {
   const publicClientId = readPublicClientId();
   const response = await fetch(
@@ -159,10 +221,33 @@ export async function changeDashboardBillingSubscription(input: {
         planId: input.planId,
         ...(input.successUrl ? { successUrl: input.successUrl } : {}),
         ...(input.cancelUrl ? { cancelUrl: input.cancelUrl } : {}),
+        ...(input.timing ? { timing: input.timing } : {}),
+        ...(input.effectiveAt ? { effectiveAt: input.effectiveAt } : {}),
+        ...(input.confirmReplaceScheduled
+          ? { confirmReplaceScheduled: true }
+          : {}),
       }),
       cache: "no-store",
     }
   );
+  if (response.status === 409) {
+    const text = await response.text();
+    let body: DashboardScheduledChangeConflict | null = null;
+    try {
+      body = text
+        ? (JSON.parse(text) as DashboardScheduledChangeConflict)
+        : null;
+    } catch {
+      body = null;
+    }
+    if (body?.code === "scheduled_change_exists") {
+      throw new PmtHouseError(body.error || "Scheduled plan change exists", {
+        status: 409,
+        code: "scheduled_change_exists",
+        details: body,
+      });
+    }
+  }
   return readPymthouseResponse<DashboardSubscriptionChange>(response);
 }
 
@@ -171,6 +256,26 @@ export type DashboardUserSubscription = {
   planName: string | null;
   status: string | null;
   subscriptionId: string | null;
+  currentPeriodEnd: string | null;
+  timingOptions: {
+    cancel: {
+      minEffectiveAt: string;
+      maxEffectiveAt: string | null;
+      presets: Array<"immediate" | "next_billing_cycle">;
+    };
+    change: {
+      minEffectiveAt: string;
+      maxEffectiveAt: string | null;
+      presets: Array<"immediate" | "next_billing_cycle">;
+    };
+  } | null;
+  pendingCancel: {
+    subscriptionId: string;
+    planId: string | null;
+    planKey: string | null;
+    planName: string | null;
+    effectiveAt: string | null;
+  } | null;
 };
 
 export async function getDashboardUserSubscription(
@@ -180,14 +285,48 @@ export async function getDashboardUserSubscription(
   const result: UserSubscriptionResponse =
     await client.getUserSubscription(externalUserId);
   const sub = result.subscription;
+  const pending = result.pendingCancel ?? null;
+  // Prefer OpenMeter/builder fields; pendingCancel carries cancel-at-period-end
+  // plan identity when the live row is already canceled/inactive.
   return {
-    planId: sub?.planId?.trim() || null,
-    planName: sub?.planName?.trim() || null,
-    status: sub?.status?.trim() || null,
-    subscriptionId: sub?.id?.trim() || null,
+    planId: sub?.planId?.trim() || pending?.planId?.trim() || null,
+    planName: sub?.planName?.trim() || pending?.planName?.trim() || null,
+    status: sub?.status?.trim() || (pending ? "canceled" : null),
+    subscriptionId: sub?.id?.trim() || pending?.subscriptionId?.trim() || null,
+    currentPeriodEnd:
+      sub?.currentPeriodEnd?.trim() || pending?.effectiveAt?.trim() || null,
+    timingOptions: result.timingOptions ?? null,
+    pendingCancel: pending
+      ? {
+          subscriptionId: pending.subscriptionId,
+          planId: pending.planId,
+          planKey: pending.planKey,
+          planName: pending.planName,
+          effectiveAt: pending.effectiveAt,
+        }
+      : null,
   };
 }
 
+export async function cancelDashboardUserSubscription(
+  externalUserId: string,
+  opts?: { timing?: string; effectiveAt?: string }
+): Promise<void> {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  await client.cancelUserSubscription(externalUserId, {
+    confirm: true,
+    ...(opts?.timing ? { timing: opts.timing } : {}),
+    ...(opts?.effectiveAt ? { effectiveAt: opts.effectiveAt } : {}),
+  });
+}
+
+export async function resumeDashboardUserSubscription(
+  externalUserId: string
+): Promise<void> {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  await client.resumeUserSubscription(externalUserId, { confirm: true });
+}
+
 export type DashboardInvoice = AppUserInvoice;
 export type DashboardPaymentMethod = AppUserPaymentMethod;
 
@@ -248,3 +387,158 @@ export async function removeDashboardUserPaymentMethod(
   const client = createPmtHouseClientForPublicApp(readPublicClientId());
   return client.unlinkUserPaymentMethod(externalUserId, paymentMethodId);
 }
+
+// ---------------------------------------------------------------------------
+// Owner wallet (Builder M2M) — pymthouse PR #399
+// /api/v1/apps/{clientId}/billing/wallet* over M2M Basic auth. This is the
+// app owner's prepaid wallet (OpenAI-style usage page): balance, top-up via
+// Stripe Checkout, past platform invoices, and the auto-debit payment method.
+// ---------------------------------------------------------------------------
+
+export type DashboardWalletBalance = {
+  usdMicros: string;
+  usd: string;
+  lifetimeGrantedUsdMicros: string;
+  consumedUsdMicros: string;
+};
+
+export type DashboardWalletPayPerUsePlan = {
+  planId: string;
+  planName: string;
+  chargeThresholdUsdMicros: string | null;
+  resolvedBehavior: string;
+};
+
+export type DashboardOwnerWallet = {
+  clientId: string;
+  balance: DashboardWalletBalance | null;
+  paymentMethod: {
+    /** null = provider state unknown (fail open upstream). */
+    hasDefault: boolean | null;
+  };
+  payPerUsePlans: DashboardWalletPayPerUsePlan[];
+  settlement: {
+    order: string; // "credits_then_auto_debit"
+    description: string;
+  };
+};
+
+export type DashboardWalletInvoice = {
+  id: string;
+  number?: string;
+  status: string;
+  currency: string;
+  totalAmount: string;
+  issuedAt?: string;
+  periodStart?: string;
+  periodEnd?: string;
+  invoiceType?: string;
+};
+
+export type DashboardWalletPaymentMethod = {
+  id: string;
+  type: string;
+  brand: string | null;
+  last4: string | null;
+  expMonth: number | null;
+  expYear: number | null;
+  isDefault: boolean;
+};
+
+export type DashboardWalletTopUpResult = {
+  checkoutUrl: string;
+  sessionId: string | null;
+  amountUsdMicros: string;
+};
+
+export type DashboardWalletPaymentMethodCheckoutResult = {
+  checkoutUrl: string;
+  sessionId: string | null;
+  hasDefaultPaymentMethod: boolean;
+};
+
+async function walletFetch<T>(
+  path: string,
+  init?: { method?: string; body?: Record<string, unknown> }
+): Promise<T> {
+  const publicClientId = readPublicClientId();
+  const response = await fetch(
+    `${pymthouseAppsOrigin()}/api/v1/apps/${encodeURIComponent(publicClientId)}/billing/wallet${path}`,
+    {
+      method: init?.method ?? "GET",
+      headers: {
+        Authorization: readM2mAuthHeader(),
+        Accept: "application/json",
+        ...(init?.body ? { "Content-Type": "application/json" } : {}),
+      },
+      ...(init?.body ? { body: JSON.stringify(init.body) } : {}),
+      cache: "no-store",
+    }
+  );
+  return readPymthouseResponse<T>(response);
+}
+
+/** GET …/billing/wallet — balance, PM on file, resolved PPU behavior, settlement order. */
+export async function getDashboardOwnerWallet(): Promise<DashboardOwnerWallet> {
+  return walletFetch<DashboardOwnerWallet>("");
+}
+
+/** POST …/billing/wallet/top-up — payment-mode Stripe Checkout ($1–$10,000). */
+export async function startDashboardWalletTopUp(input: {
+  amountUsd: string;
+  successUrl?: string;
+  cancelUrl?: string;
+}): Promise<DashboardWalletTopUpResult> {
+  return walletFetch<DashboardWalletTopUpResult>("/top-up", {
+    method: "POST",
+    body: {
+      amountUsd: input.amountUsd,
+      ...(input.successUrl ? { successUrl: input.successUrl } : {}),
+      ...(input.cancelUrl ? { cancelUrl: input.cancelUrl } : {}),
+    },
+  });
+}
+
+/** GET …/billing/wallet/invoices — past platform invoices, newest first. */
+export async function listDashboardWalletInvoices(opts?: {
+  page?: number;
+  pageSize?: number;
+}): Promise<{
+  items: DashboardWalletInvoice[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}> {
+  const params = new URLSearchParams();
+  if (opts?.page) params.set("page", String(opts.page));
+  if (opts?.pageSize) params.set("pageSize", String(opts.pageSize));
+  const query = params.toString();
+  return walletFetch(`/invoices${query ? `?${query}` : ""}`);
+}
+
+/** GET …/billing/wallet/payment-methods — attached PMs (brand + last4 only). */
+export async function listDashboardWalletPaymentMethods(): Promise<
+  DashboardWalletPaymentMethod[]
+> {
+  const result = await walletFetch<{
+    paymentMethods?: DashboardWalletPaymentMethod[];
+  }>("/payment-methods");
+  return result.paymentMethods ?? [];
+}
+
+/** POST …/billing/wallet/payment-methods — setup-mode Stripe Checkout for the auto-debit PM. */
+export async function startDashboardWalletPaymentMethodCheckout(input: {
+  successUrl?: string;
+  cancelUrl?: string;
+}): Promise<DashboardWalletPaymentMethodCheckoutResult> {
+  return walletFetch<DashboardWalletPaymentMethodCheckoutResult>(
+    "/payment-methods",
+    {
+      method: "POST",
+      body: {
+        ...(input.successUrl ? { successUrl: input.successUrl } : {}),
+        ...(input.cancelUrl ? { cancelUrl: input.cancelUrl } : {}),
+      },
+    }
+  );
+}
diff --git a/lib/dashboard/useBillingAccount.ts b/lib/dashboard/useBillingAccount.ts
index 0fc47da..cd41e39 100644
--- a/lib/dashboard/useBillingAccount.ts
+++ b/lib/dashboard/useBillingAccount.ts
@@ -18,6 +18,22 @@ async function readResponseJson<T>(response: Response): Promise<T> {
   }
 }
 
+/** Map missing/unroutable upstream billing APIs to an actionable message. */
+function billingUpstreamMessage(
+  surface: "payment methods" | "invoices",
+  status: number,
+  upstreamError?: string,
+): string {
+  if (status === 404 || status === 405) {
+    return (
+      `PymtHouse end-user ${surface} API is unavailable (${status}). ` +
+      "Deploy the /users/{id}/payment-methods and /users/{id}/invoices routes " +
+      "(pymthouse PR #386) to this environment."
+    );
+  }
+  return upstreamError ?? `${surface} failed (${status})`;
+}
+
 export type BillingAccountState =
   | { status: "idle" }
   | { status: "loading" }
@@ -53,20 +69,30 @@ export function useBillingAccount(externalUserId: string | undefined) {
       const pmBody = await readResponseJson<{
         paymentMethods?: DashboardPaymentMethod[];
         error?: string;
+        code?: string;
       }>(pmResponse);
       if (!pmResponse.ok) {
         throw new Error(
-          pmBody.error ?? `Payment methods failed (${pmResponse.status})`,
+          billingUpstreamMessage(
+            "payment methods",
+            pmResponse.status,
+            pmBody.error,
+          ),
         );
       }
 
       const invBody = await readResponseJson<{
         items?: DashboardInvoice[];
         error?: string;
+        code?: string;
       }>(invResponse);
       if (!invResponse.ok) {
         throw new Error(
-          invBody.error ?? `Invoices failed (${invResponse.status})`,
+          billingUpstreamMessage(
+            "invoices",
+            invResponse.status,
+            invBody.error,
+          ),
         );
       }
 
diff --git a/lib/dashboard/useBillingPlans.ts b/lib/dashboard/useBillingPlans.ts
index ef54da7..a21737b 100644
--- a/lib/dashboard/useBillingPlans.ts
+++ b/lib/dashboard/useBillingPlans.ts
@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useState } from "react";
 import type {
   DashboardBillingPlan,
+  DashboardScheduledChangeConflict,
   DashboardUserSubscription,
 } from "@/lib/dashboard/pymthouse-billing-bff";
 
@@ -16,6 +17,34 @@ export type BillingPlansState =
     }
   | { status: "error"; message: string };
 
+export class ResumeSubscriptionError extends Error {
+  readonly status: number;
+  /** Upstream machine-readable code, forwarded by the resume route. */
+  readonly code: string | undefined;
+
+  constructor(
+    message: string,
+    status: number,
+    code: string | undefined
+  ) {
+    super(message);
+    this.name = "ResumeSubscriptionError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export class ScheduledChangeConflictError extends Error {
+  readonly code = "scheduled_change_exists" as const;
+  readonly conflict: DashboardScheduledChangeConflict;
+
+  constructor(conflict: DashboardScheduledChangeConflict) {
+    super(conflict.error || "A plan change is already scheduled");
+    this.name = "ScheduledChangeConflictError";
+    this.conflict = conflict;
+  }
+}
+
 async function readResponseJson<T>(response: Response): Promise<T> {
   const text = await response.text();
   if (!text.trim()) {
@@ -112,6 +141,9 @@ export function useBillingPlans(externalUserId: string | undefined) {
       externalUserId: string;
       successUrl?: string;
       cancelUrl?: string;
+      timing?: string;
+      effectiveAt?: string;
+      confirmReplaceScheduled?: boolean;
     }) => {
       const response = await fetch("/api/pymthouse/subscription/change", {
         method: "POST",
@@ -122,7 +154,22 @@ export function useBillingPlans(externalUserId: string | undefined) {
         checkoutUrl?: string;
         subscriptionId?: string;
         error?: string;
+        code?: string;
+        timingOptions?: DashboardScheduledChangeConflict["timingOptions"];
+        scheduledSubscriptionId?: string | null;
+        scheduledPlanKey?: string | null;
+        scheduledActiveFrom?: string | null;
       }>(response);
+      if (response.status === 409 && body.code === "scheduled_change_exists") {
+        throw new ScheduledChangeConflictError({
+          code: "scheduled_change_exists",
+          error: body.error ?? "A plan change is already scheduled",
+          timingOptions: body.timingOptions ?? null,
+          scheduledSubscriptionId: body.scheduledSubscriptionId ?? null,
+          scheduledPlanKey: body.scheduledPlanKey ?? null,
+          scheduledActiveFrom: body.scheduledActiveFrom ?? null,
+        });
+      }
       if (!response.ok) {
         throw new Error(
           body.error ?? `Plan change failed (${response.status})`
@@ -136,5 +183,52 @@ export function useBillingPlans(externalUserId: string | undefined) {
     []
   );
 
-  return { state, reload: load, subscribe, changePlan };
+  const cancelSubscription = useCallback(
+    async (
+      externalUserId: string,
+      opts?: { timing?: string; effectiveAt?: string }
+    ) => {
+      const response = await fetch("/api/pymthouse/subscription/cancel", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          externalUserId,
+          ...(opts?.timing ? { timing: opts.timing } : {}),
+          ...(opts?.effectiveAt ? { effectiveAt: opts.effectiveAt } : {}),
+        }),
+      });
+      const body = await readResponseJson<{ error?: string }>(response);
+      if (!response.ok) {
+        throw new Error(body.error ?? `Cancel failed (${response.status})`);
+      }
+    },
+    []
+  );
+
+  const resumeSubscription = useCallback(async (externalUserId: string) => {
+    const response = await fetch("/api/pymthouse/subscription/resume", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ externalUserId }),
+    });
+    const body = await readResponseJson<{ error?: string; code?: string }>(
+      response
+    );
+    if (!response.ok) {
+      throw new ResumeSubscriptionError(
+        body.error ?? `Resume failed (${response.status})`,
+        response.status,
+        body.code
+      );
+    }
+  }, []);
+
+  return {
+    state,
+    reload: load,
+    subscribe,
+    changePlan,
+    cancelSubscription,
+    resumeSubscription,
+  };
 }
diff --git a/lib/dashboard/useOwnerWallet.ts b/lib/dashboard/useOwnerWallet.ts
new file mode 100644
index 0000000..0e2ced8
--- /dev/null
+++ b/lib/dashboard/useOwnerWallet.ts
@@ -0,0 +1,155 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import type {
+  DashboardOwnerWallet,
+  DashboardWalletInvoice,
+  DashboardWalletPaymentMethod,
+} from "@/lib/dashboard/pymthouse-billing-bff";
+
+async function readResponseJson<T>(response: Response): Promise<T> {
+  const text = await response.text();
+  if (!text.trim()) {
+    throw new Error(`Empty response (${response.status})`);
+  }
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(`Invalid JSON (${response.status})`);
+  }
+}
+
+/** Map missing/unroutable upstream wallet APIs to an actionable message. */
+function walletUpstreamMessage(status: number, upstreamError?: string): string {
+  if (status === 404 || status === 405) {
+    return (
+      `PymtHouse owner wallet API is unavailable (${status}). ` +
+      "Deploy the /apps/{clientId}/billing/wallet routes (pymthouse PR #399) " +
+      "to this environment and check the M2M client credentials."
+    );
+  }
+  return upstreamError ?? `Wallet request failed (${status})`;
+}
+
+export type OwnerWalletState =
+  | { status: "idle" }
+  | { status: "loading" }
+  | {
+      status: "ready";
+      wallet: DashboardOwnerWallet;
+      paymentMethods: DashboardWalletPaymentMethod[];
+      invoices: DashboardWalletInvoice[];
+    }
+  | { status: "error"; message: string };
+
+export function useOwnerWallet(enabled: boolean) {
+  const [state, setState] = useState<OwnerWalletState>({ status: "idle" });
+
+  const load = useCallback(async () => {
+    if (!enabled) {
+      setState({ status: "idle" });
+      return;
+    }
+
+    setState({ status: "loading" });
+    try {
+      const [walletResponse, pmResponse, invResponse] = await Promise.all([
+        fetch("/api/pymthouse/wallet"),
+        fetch("/api/pymthouse/wallet/payment-methods"),
+        fetch("/api/pymthouse/wallet/invoices?pageSize=20"),
+      ]);
+
+      const walletBody = await readResponseJson<
+        DashboardOwnerWallet & { error?: string }
+      >(walletResponse);
+      if (!walletResponse.ok) {
+        throw new Error(
+          walletUpstreamMessage(walletResponse.status, walletBody.error),
+        );
+      }
+
+      const pmBody = await readResponseJson<{
+        paymentMethods?: DashboardWalletPaymentMethod[];
+        error?: string;
+      }>(pmResponse);
+      if (!pmResponse.ok) {
+        throw new Error(walletUpstreamMessage(pmResponse.status, pmBody.error));
+      }
+
+      const invBody = await readResponseJson<{
+        items?: DashboardWalletInvoice[];
+        error?: string;
+      }>(invResponse);
+      if (!invResponse.ok) {
+        throw new Error(
+          walletUpstreamMessage(invResponse.status, invBody.error),
+        );
+      }
+
+      setState({
+        status: "ready",
+        wallet: walletBody,
+        paymentMethods: pmBody.paymentMethods ?? [],
+        invoices: invBody.items ?? [],
+      });
+    } catch (error) {
+      setState({
+        status: "error",
+        message:
+          error instanceof Error ? error.message : "Failed to load wallet",
+      });
+    }
+  }, [enabled]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const startTopUp = useCallback(async (input: { amountUsd: string }) => {
+    const response = await fetch("/api/pymthouse/wallet/top-up", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        amountUsd: input.amountUsd,
+        successUrl: `${window.location.origin}/usage?topup=succeeded`,
+        cancelUrl: `${window.location.origin}/usage?topup=canceled`,
+      }),
+    });
+    const body = await readResponseJson<{
+      checkoutUrl?: string;
+      error?: string;
+    }>(response);
+    if (!response.ok || !body.checkoutUrl) {
+      throw new Error(body.error ?? `Top-up failed (${response.status})`);
+    }
+    return { checkoutUrl: body.checkoutUrl };
+  }, []);
+
+  const startPaymentMethodCheckout = useCallback(async () => {
+    const response = await fetch("/api/pymthouse/wallet/payment-methods", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        successUrl: `${window.location.origin}/usage?topup=pm-saved`,
+        cancelUrl: `${window.location.origin}/usage?topup=canceled`,
+      }),
+    });
+    const body = await readResponseJson<{
+      checkoutUrl?: string;
+      error?: string;
+    }>(response);
+    if (!response.ok || !body.checkoutUrl) {
+      throw new Error(
+        body.error ?? `Payment method checkout failed (${response.status})`,
+      );
+    }
+    return { checkoutUrl: body.checkoutUrl };
+  }, []);
+
+  return {
+    state,
+    reload: load,
+    startTopUp,
+    startPaymentMethodCheckout,
+  };
+}

From f81087285b36afe7c3dce675b79c8b0fdb2b4c2e Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Sun, 9 Aug 2026 00:27:36 -0400
Subject: [PATCH 09/13] feat(billing): drive wallet UI from billingState spend
 posture

Replace soft-limit strip copy with the API-owned posture card (status badge, buffer meter, collection schedule) and align pay-per-use plan wording with progressive invoicing.
---
 app/api/pymthouse/payment-methods/route.ts    |  44 +++++-
 app/api/pymthouse/wallet/invoices/route.ts    |  15 +-
 .../pymthouse/wallet/payment-methods/route.ts |  68 +++++++-
 app/api/pymthouse/wallet/route.ts             |  27 +++-
 app/api/pymthouse/wallet/top-up/route.ts      |  16 +-
 components/dashboard/PlansPanel.tsx           |  23 +--
 components/dashboard/UsageView.tsx            |  11 +-
 components/dashboard/WalletPanel.tsx          | 130 ++++++++++++++--
 .../dashboard/settings/BillingSection.tsx     |  76 +++++----
 lib/dashboard/pymthouse-billing-bff.ts        | 103 +++++++++---
 lib/dashboard/useBillingAccount.ts            |  23 +++
 lib/dashboard/useOwnerWallet.ts               |  87 ++++++++---
 .../wallet-settlement-display.test.ts         | 147 ++++++++++++++++++
 lib/dashboard/wallet-settlement-display.ts    |  72 +++++++++
 14 files changed, 711 insertions(+), 131 deletions(-)
 create mode 100644 lib/dashboard/wallet-settlement-display.test.ts
 create mode 100644 lib/dashboard/wallet-settlement-display.ts

diff --git a/app/api/pymthouse/payment-methods/route.ts b/app/api/pymthouse/payment-methods/route.ts
index dfd9663..f7d3965 100644
--- a/app/api/pymthouse/payment-methods/route.ts
+++ b/app/api/pymthouse/payment-methods/route.ts
@@ -3,6 +3,7 @@ import { PmtHouseError } from "@pymthouse/builder-sdk";
 import {
   listDashboardUserPaymentMethods,
   removeDashboardUserPaymentMethod,
+  ensureDashboardUserDefaultPaymentMethod,
   setDashboardUserDefaultPaymentMethod,
   startDashboardPaymentMethodCheckout,
 } from "@/lib/dashboard/pymthouse-billing-bff";
@@ -134,15 +135,48 @@ async function readPaymentMethodMutation(request: NextRequest): Promise<
 }
 
 export async function PATCH(request: NextRequest) {
-  const input = await readPaymentMethodMutation(request);
-  if (input instanceof NextResponse) {
-    return input;
+  let body: {
+    externalUserId?: string;
+    paymentMethodId?: string;
+    ensureDefault?: boolean;
+  };
+  try {
+    body = (await request.json()) as typeof body;
+  } catch {
+    return NextResponse.json({ error: "invalid_json" }, { status: 400 });
+  }
+
+  const externalUserId = body.externalUserId?.trim();
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 },
+    );
+  }
+
+  if (body.ensureDefault === true) {
+    try {
+      return NextResponse.json(
+        await ensureDashboardUserDefaultPaymentMethod(externalUserId),
+      );
+    } catch (error) {
+      return billingErrorResponse(error, "Failed to ensure default payment method");
+    }
+  }
+
+  const paymentMethodId = body.paymentMethodId?.trim();
+  if (!paymentMethodId) {
+    return NextResponse.json(
+      { error: "paymentMethodId is required" },
+      { status: 400 },
+    );
   }
+
   try {
     return NextResponse.json(
       await setDashboardUserDefaultPaymentMethod(
-        input.externalUserId,
-        input.paymentMethodId,
+        externalUserId,
+        paymentMethodId,
       ),
     );
   } catch (error) {
diff --git a/app/api/pymthouse/wallet/invoices/route.ts b/app/api/pymthouse/wallet/invoices/route.ts
index e5e032f..ae2d938 100644
--- a/app/api/pymthouse/wallet/invoices/route.ts
+++ b/app/api/pymthouse/wallet/invoices/route.ts
@@ -14,11 +14,24 @@ function parsePageParam(raw: string | null): number | undefined {
 }
 
 export async function GET(request: NextRequest) {
+  const externalUserId =
+    request.nextUrl.searchParams.get("externalUserId")?.trim() || "";
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400, headers: WALLET_NO_STORE_HEADERS },
+    );
+  }
+
   const page = parsePageParam(request.nextUrl.searchParams.get("page"));
   const pageSize = parsePageParam(request.nextUrl.searchParams.get("pageSize"));
 
   try {
-    const result = await listDashboardWalletInvoices({ page, pageSize });
+    const result = await listDashboardWalletInvoices({
+      externalUserId,
+      page,
+      pageSize,
+    });
     return NextResponse.json(result, { headers: WALLET_NO_STORE_HEADERS });
   } catch (error) {
     return walletErrorResponse(error, "Failed to load wallet invoices");
diff --git a/app/api/pymthouse/wallet/payment-methods/route.ts b/app/api/pymthouse/wallet/payment-methods/route.ts
index 02a94e2..38a8b2e 100644
--- a/app/api/pymthouse/wallet/payment-methods/route.ts
+++ b/app/api/pymthouse/wallet/payment-methods/route.ts
@@ -2,6 +2,7 @@ import { NextRequest, NextResponse } from "next/server";
 import {
   listDashboardWalletPaymentMethods,
   startDashboardWalletPaymentMethodCheckout,
+  ensureDashboardWalletDefaultPaymentMethod,
 } from "@/lib/dashboard/pymthouse-billing-bff";
 import {
   WALLET_NO_STORE_HEADERS,
@@ -12,9 +13,19 @@ import {
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
-export async function GET() {
+export async function GET(request: NextRequest) {
+  const externalUserId =
+    request.nextUrl.searchParams.get("externalUserId")?.trim() || "";
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400, headers: WALLET_NO_STORE_HEADERS },
+    );
+  }
+
   try {
-    const paymentMethods = await listDashboardWalletPaymentMethods();
+    const paymentMethods =
+      await listDashboardWalletPaymentMethods(externalUserId);
     return NextResponse.json(
       { paymentMethods },
       { headers: WALLET_NO_STORE_HEADERS },
@@ -25,13 +36,25 @@ export async function GET() {
 }
 
 export async function POST(request: NextRequest) {
-  let body: { successUrl?: string; cancelUrl?: string };
+  let body: {
+    externalUserId?: string;
+    successUrl?: string;
+    cancelUrl?: string;
+  };
   try {
     body = (await request.json()) as typeof body;
   } catch {
     body = {};
   }
 
+  const externalUserId = body.externalUserId?.trim();
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 },
+    );
+  }
+
   const origin = checkoutReturnOrigin(request);
   const successUrl =
     body.successUrl?.trim() || `${origin}/usage?topup=pm-saved`;
@@ -39,6 +62,7 @@ export async function POST(request: NextRequest) {
 
   try {
     const result = await startDashboardWalletPaymentMethodCheckout({
+      externalUserId,
       successUrl,
       cancelUrl,
     });
@@ -50,3 +74,41 @@ export async function POST(request: NextRequest) {
     );
   }
 }
+
+export async function PATCH(request: NextRequest) {
+  let body: {
+    externalUserId?: string;
+    ensureDefault?: boolean;
+  };
+  try {
+    body = (await request.json()) as typeof body;
+  } catch {
+    return NextResponse.json({ error: "invalid_json" }, { status: 400 });
+  }
+
+  const externalUserId = body.externalUserId?.trim();
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 },
+    );
+  }
+
+  if (body.ensureDefault !== true) {
+    return NextResponse.json(
+      { error: "ensureDefault: true is required" },
+      { status: 400 },
+    );
+  }
+
+  try {
+    const result =
+      await ensureDashboardWalletDefaultPaymentMethod(externalUserId);
+    return NextResponse.json(result);
+  } catch (error) {
+    return walletErrorResponse(
+      error,
+      "Failed to ensure default payment method",
+    );
+  }
+}
diff --git a/app/api/pymthouse/wallet/route.ts b/app/api/pymthouse/wallet/route.ts
index 524fee3..e2592d0 100644
--- a/app/api/pymthouse/wallet/route.ts
+++ b/app/api/pymthouse/wallet/route.ts
@@ -1,4 +1,4 @@
-import { NextResponse } from "next/server";
+import { NextRequest, NextResponse } from "next/server";
 import { getDashboardOwnerWallet } from "@/lib/dashboard/pymthouse-billing-bff";
 import {
   WALLET_NO_STORE_HEADERS,
@@ -8,11 +8,32 @@ import {
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
-export async function GET() {
+export async function GET(request: NextRequest) {
+  const externalUserId =
+    request.nextUrl.searchParams.get("externalUserId")?.trim() || "";
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400, headers: WALLET_NO_STORE_HEADERS },
+    );
+  }
+
   try {
-    const wallet = await getDashboardOwnerWallet();
+    const wallet = await getDashboardOwnerWallet(externalUserId);
     return NextResponse.json(wallet, { headers: WALLET_NO_STORE_HEADERS });
   } catch (error) {
     return walletErrorResponse(error, "Failed to load wallet");
   }
 }
+
+/** Per-user auto top-up prefs are retired upstream (410). */
+export async function PATCH() {
+  return NextResponse.json(
+    {
+      error:
+        "Per-user auto top-up is retired. Soft-negative is configured on the app; usage is billed via progressive invoicing.",
+      code: "auto_topup_retired",
+    },
+    { status: 410, headers: WALLET_NO_STORE_HEADERS },
+  );
+}
diff --git a/app/api/pymthouse/wallet/top-up/route.ts b/app/api/pymthouse/wallet/top-up/route.ts
index a66ca32..20552de 100644
--- a/app/api/pymthouse/wallet/top-up/route.ts
+++ b/app/api/pymthouse/wallet/top-up/route.ts
@@ -8,13 +8,26 @@ import {
 export const runtime = "nodejs";
 
 export async function POST(request: NextRequest) {
-  let body: { amountUsd?: string | number; successUrl?: string; cancelUrl?: string };
+  let body: {
+    amountUsd?: string | number;
+    externalUserId?: string;
+    successUrl?: string;
+    cancelUrl?: string;
+  };
   try {
     body = (await request.json()) as typeof body;
   } catch {
     return NextResponse.json({ error: "invalid_json" }, { status: 400 });
   }
 
+  const externalUserId = body.externalUserId?.trim();
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 },
+    );
+  }
+
   const amountUsd =
     typeof body.amountUsd === "number"
       ? body.amountUsd.toFixed(2)
@@ -34,6 +47,7 @@ export async function POST(request: NextRequest) {
   try {
     const result = await startDashboardWalletTopUp({
       amountUsd,
+      externalUserId,
       successUrl,
       cancelUrl,
     });
diff --git a/components/dashboard/PlansPanel.tsx b/components/dashboard/PlansPanel.tsx
index b7975bc..0a1df80 100644
--- a/components/dashboard/PlansPanel.tsx
+++ b/components/dashboard/PlansPanel.tsx
@@ -9,20 +9,6 @@ function isUsagePlan(plan: Pick<DashboardBillingPlan, "type">): boolean {
   return plan.type.trim().toLowerCase() === "usage";
 }
 
-function formatUsdMicrosAsCurrency(usdMicros: string): string {
-  try {
-    const amount = Number(BigInt(usdMicros)) / 1_000_000;
-    return new Intl.NumberFormat("en-US", {
-      style: "currency",
-      currency: "USD",
-      minimumFractionDigits: 2,
-      maximumFractionDigits: 2,
-    }).format(amount);
-  } catch {
-    return "$0.00";
-  }
-}
-
 function formatPrice(plan: DashboardBillingPlan): string {
   const n = Number(plan.priceAmount);
   const money = Number.isFinite(n)
@@ -44,14 +30,7 @@ function resolvedPayPerUseBehavior(plan: DashboardBillingPlan): string {
   const resolved = plan.resolvedBehavior?.trim();
   if (resolved) return resolved;
 
-  const threshold = plan.chargeThresholdUsdMicros?.trim();
-  if (threshold) {
-    return `Charged at every ${formatUsdMicrosAsCurrency(
-      threshold
-    )} of usage (credits first).`;
-  }
-
-  return "Usage settles from prepaid credits first, then auto-debits your default payment method.";
+  return "Usage draws down prepaid credits first, then is invoiced automatically as it accrues.";
 }
 
 function readCheckoutFlash(): "success" | "cancel" | null {
diff --git a/components/dashboard/UsageView.tsx b/components/dashboard/UsageView.tsx
index 1c3ea18..30b15d3 100644
--- a/components/dashboard/UsageView.tsx
+++ b/components/dashboard/UsageView.tsx
@@ -85,7 +85,7 @@ function AllowanceStrip({
     <div className="flex flex-col gap-3 rounded-md border border-hairline bg-dark-lighter shadow-card px-5 py-4">
       <div className="flex flex-wrap items-center gap-2">
         <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
-          {showUsdAllowance ? "Prepaid allowance" : "Usage this period"}
+          {showUsdAllowance ? "Included this period" : "Usage this period"}
         </p>
         {showUsdAllowance && !hasAccess && (
           <span className="rounded-[3px] border border-warm/30 bg-warm/10 px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-wide text-warm">
@@ -290,7 +290,14 @@ export default function UsageView() {
         resetsAt={resetsAt}
       />
 
-      <WalletPanel />
+      <WalletPanel
+        externalUserId={externalUserId}
+        periodBillableUsdMicros={
+          data.current.endUserBillableUsdMicros ||
+          data.current.networkFeeUsdMicros ||
+          null
+        }
+      />
 
       <PlansPanel externalUserId={externalUserId} />
 
diff --git a/components/dashboard/WalletPanel.tsx b/components/dashboard/WalletPanel.tsx
index ecf6cb0..bf50a6e 100644
--- a/components/dashboard/WalletPanel.tsx
+++ b/components/dashboard/WalletPanel.tsx
@@ -3,6 +3,13 @@
 import { useEffect, useState } from "react";
 import Button from "@/components/design-system/Button";
 import { useOwnerWallet } from "@/lib/dashboard/useOwnerWallet";
+import {
+  collectionSchedule,
+  formatWalletUsd,
+  overageBufferMeter,
+  spendPostureBadge,
+  type SpendPostureTone,
+} from "@/lib/dashboard/wallet-settlement-display";
 
 type TopUpFlash = "succeeded" | "canceled" | "pm-saved";
 
@@ -36,6 +43,20 @@ function formatInvoiceDate(iso: string | undefined): string {
 
 const QUICK_AMOUNTS = ["10.00", "25.00", "100.00"] as const;
 
+const POSTURE_TONE_CLASS: Record<SpendPostureTone, string> = {
+  ok: "border-emerald-400/30 text-emerald-400",
+  info: "border-hairline text-fg-muted",
+  warn: "border-amber-400/30 text-amber-400",
+  danger: "border-rose-400/30 text-rose-400",
+};
+
+const METER_TONE_CLASS: Record<SpendPostureTone, string> = {
+  ok: "bg-emerald-400",
+  info: "bg-fg-muted",
+  warn: "bg-amber-400",
+  danger: "bg-rose-400",
+};
+
 /** Only follow https (or localhost http, for dev) Checkout URLs. */
 function redirectToCheckout(url: string): void {
   let parsed: URL;
@@ -52,9 +73,16 @@ function redirectToCheckout(url: string): void {
   window.location.assign(parsed.toString());
 }
 
-export default function WalletPanel() {
-  const { state, reload, startTopUp, startPaymentMethodCheckout } =
-    useOwnerWallet(true);
+export default function WalletPanel({
+  externalUserId,
+  periodBillableUsdMicros = null,
+}: {
+  externalUserId: string | undefined;
+  /** Period end-user billable USD micros from the Usage page (metered usage, not credits). */
+  periodBillableUsdMicros?: string | null;
+}) {
+  const { state, reload, startTopUp, startPaymentMethodCheckout, ensureDefaultPaymentMethod } =
+    useOwnerWallet(Boolean(externalUserId), externalUserId);
   const [showTopUp, setShowTopUp] = useState(false);
   const [amountUsd, setAmountUsd] = useState<string>("25.00");
   const [busy, setBusy] = useState<"topup" | "pm" | null>(null);
@@ -66,7 +94,19 @@ export default function WalletPanel() {
     if (!next) return;
     setFlash(next);
     clearTopUpQueryParam();
-  }, []);
+    if (next === "pm-saved") {
+      void (async () => {
+        try {
+          await ensureDefaultPaymentMethod();
+        } catch {
+          // Webhook may already have promoted; list still refreshes below.
+        }
+        void reload();
+      })();
+    } else if (next === "succeeded") {
+      void reload();
+    }
+  }, [ensureDefaultPaymentMethod, reload]);
 
   async function onTopUp() {
     setError(null);
@@ -122,6 +162,10 @@ export default function WalletPanel() {
 
   const { wallet, paymentMethods, invoices } = state;
   const balanceUsd = wallet.balance?.usd ?? "0.00";
+  const usageUsd = formatWalletUsd(periodBillableUsdMicros);
+  const billingState = wallet.billingState;
+  const posture = spendPostureBadge(billingState.status);
+  const meter = overageBufferMeter(billingState);
   const defaultPm =
     paymentMethods.find((pm) => pm.isDefault) ?? paymentMethods[0] ?? null;
   const hasPaymentMethod =
@@ -130,15 +174,65 @@ export default function WalletPanel() {
   return (
     <div className="mt-4 overflow-hidden rounded-md border border-hairline bg-dark-lighter shadow-card">
       <div className="flex flex-wrap items-start justify-between gap-3 border-b border-hairline px-4 py-3.5">
-        <div>
-          <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
-            Current balance
-          </p>
-          <p className="mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] text-fg">
-            ${balanceUsd}
+        <div className="min-w-0 flex-1">
+          <div className="flex flex-wrap items-baseline gap-2">
+            <span
+              className={`rounded-[3px] border px-1.5 py-px font-mono text-[10.5px] uppercase tracking-[0.06em] ${POSTURE_TONE_CLASS[posture.tone]}`}
+            >
+              {posture.label}
+            </span>
+            <p className="text-[13px] font-semibold text-fg">
+              {billingState.explain.headline}
+            </p>
+          </div>
+          <p className="mt-1 max-w-prose text-[12px] text-fg-muted">
+            {billingState.explain.detail}
           </p>
-          <p className="mt-1 text-[12px] text-fg-muted">
-            {wallet.settlement.description}
+
+          <div className="mt-4 grid grid-cols-1 gap-4 sm:grid-cols-3">
+            <div>
+              <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
+                Prepaid credits
+              </p>
+              <p className="mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] text-fg">
+                ${balanceUsd}
+              </p>
+            </div>
+            <div>
+              <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
+                Usage this period
+              </p>
+              <p className="mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] text-fg">
+                ${usageUsd}
+              </p>
+            </div>
+            {meter ? (
+              <div>
+                <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
+                  Spending buffer
+                </p>
+                <p className="mt-1 font-mono text-[20px] font-medium tabular-nums tracking-[-0.01em] text-fg sm:text-[28px]">
+                  {meter.primary}
+                </p>
+                <div
+                  className="mt-1.5 h-1 w-full overflow-hidden rounded-full bg-white/5"
+                  role="progressbar"
+                  aria-label="Spending buffer used"
+                  aria-valuemin={0}
+                  aria-valuemax={100}
+                  aria-valuenow={meter.percent}
+                >
+                  <div
+                    className={`h-full rounded-full ${METER_TONE_CLASS[posture.tone]}`}
+                    style={{ width: `${meter.percent}%` }}
+                  />
+                </div>
+                <p className="mt-1 text-[11px] text-fg-muted">{meter.status}</p>
+              </div>
+            ) : null}
+          </div>
+          <p className="mt-3 text-[12px] text-fg-muted">
+            {collectionSchedule(billingState)}
           </p>
           {wallet.payPerUsePlans.map((plan) => (
             <p key={plan.planId} className="mt-1 text-[11px] text-fg-faint">
@@ -216,14 +310,14 @@ export default function WalletPanel() {
       <div className="flex flex-wrap items-center justify-between gap-3 border-b border-hairline px-4 py-3">
         <div>
           <p className="text-[13px] font-semibold text-fg">
-            Auto-debit payment method
+            Payment method for usage billing
           </p>
           <p className="mt-0.5 text-[12px] text-fg-muted">
             {hasPaymentMethod && defaultPm
               ? `${defaultPm.brand ?? defaultPm.type}${defaultPm.last4 ? ` •••• ${defaultPm.last4}` : ""}`
               : hasPaymentMethod
                 ? "Payment method on file."
-                : "No payment method on file — pay-per-use auto-debit will fail once credits run out."}
+                : "No payment method on file — progressive invoices cannot charge once credits run out."}
           </p>
         </div>
         <Button
@@ -243,7 +337,9 @@ export default function WalletPanel() {
       <div className="px-4 py-3">
         <p className="text-[13px] font-semibold text-fg">Billing history</p>
         {invoices.length === 0 ? (
-          <p className="mt-1 text-[12px] text-fg-faint">No invoices yet.</p>
+          <p className="mt-1 text-[12px] text-fg-faint">
+            No invoices or top-ups yet.
+          </p>
         ) : (
           <ul className="mt-1.5 divide-y divide-hairline">
             {invoices.slice(0, 8).map((invoice) => (
@@ -258,7 +354,9 @@ export default function WalletPanel() {
                   {formatInvoiceDate(invoice.issuedAt ?? invoice.periodEnd)}
                 </span>
                 <span className="rounded-[3px] border border-hairline px-1.5 py-px font-mono text-[10.5px] uppercase tracking-wide text-fg-muted">
-                  {invoice.status}
+                  {invoice.invoiceType === "auto_topup"
+                    ? "top-up"
+                    : invoice.status}
                 </span>
                 <span className="font-mono text-[12px] tabular-nums text-fg">
                   {invoice.totalAmount} {invoice.currency.toUpperCase()}
diff --git a/components/dashboard/settings/BillingSection.tsx b/components/dashboard/settings/BillingSection.tsx
index 3cb5fd1..61c6db5 100644
--- a/components/dashboard/settings/BillingSection.tsx
+++ b/components/dashboard/settings/BillingSection.tsx
@@ -51,34 +51,13 @@ function isUsagePlan(plan: Pick<DashboardBillingPlan, "type">): boolean {
   return plan.type.trim().toLowerCase() === "usage";
 }
 
-function formatUsdMicrosAsCurrency(usdMicros: string): string {
-  try {
-    const amount = Number(BigInt(usdMicros)) / 1_000_000;
-    return new Intl.NumberFormat("en-US", {
-      style: "currency",
-      currency: "USD",
-      minimumFractionDigits: 2,
-      maximumFractionDigits: 2,
-    }).format(amount);
-  } catch {
-    return "$0.00";
-  }
-}
-
 function resolvedPayPerUseBehavior(plan: DashboardBillingPlan): string {
   const resolved = plan.resolvedBehavior?.trim();
   if (resolved) {
     return resolved;
   }
 
-  const threshold = plan.chargeThresholdUsdMicros?.trim();
-  if (threshold) {
-    return `Pay-per-use — charged at every ${formatUsdMicrosAsCurrency(
-      threshold
-    )} of usage (credits first).`;
-  }
-
-  return "Pay-per-use — usage settles against prepaid credits first, then auto-debits your default payment method.";
+  return "Pay-per-use — usage draws down prepaid credits first, then is invoiced automatically as it accrues.";
 }
 
 function formatPlanPrice(
@@ -260,6 +239,7 @@ export default function BillingSection() {
     startPaymentMethodCheckout,
     openInvoice,
     setDefaultPaymentMethod,
+    ensureDefaultPaymentMethod,
     removePaymentMethod,
   } = useBillingAccount(externalUserId);
 
@@ -293,10 +273,24 @@ export default function BillingSection() {
     setFlash(next);
     clearCheckoutQueryParam();
     if (next === "success") {
-      void reloadPlans();
-      void reloadAccount();
+      void (async () => {
+        if (externalUserId) {
+          try {
+            await ensureDefaultPaymentMethod({ externalUserId });
+          } catch {
+            // Webhook may already have promoted; list/UI still refreshes.
+          }
+        }
+        void reloadPlans();
+        void reloadAccount();
+      })();
     }
-  }, [reloadPlans, reloadAccount]);
+  }, [
+    externalUserId,
+    ensureDefaultPaymentMethod,
+    reloadPlans,
+    reloadAccount,
+  ]);
 
   async function ensurePaymentMethodForUsagePlan(planId: string) {
     if (!externalUserId) return;
@@ -545,7 +539,11 @@ export default function BillingSection() {
           ? links.invoicePdf || links.hostedInvoiceUrl
           : links.hostedInvoiceUrl || links.invoicePdf;
       if (!url) {
-        throw new Error("No Stripe invoice page for this invoice yet.");
+        throw new Error(
+          invoiceId.startsWith("pi_")
+            ? "No Stripe receipt for this top-up yet."
+            : "No Stripe invoice page for this invoice yet.",
+        );
       }
       window.open(url, "_blank", "noopener,noreferrer");
     } catch (err) {
@@ -868,7 +866,10 @@ export default function BillingSection() {
         )}
       </SettingsCard>
 
-      <SettingsHeader title="Invoices" sub="Stripe invoices for this account" />
+      <SettingsHeader
+        title="Billing history"
+        sub="Stripe invoices and auto top-ups for this account"
+      />
       <SettingsCard>
         {accountLoading ? (
           <div className="animate-pulse p-5">
@@ -877,7 +878,7 @@ export default function BillingSection() {
         ) : accountState.status === "error" ? (
           <div className="px-5 py-6 text-center">
             <p className="text-[13px] text-fg-muted">
-              Could not load invoices.
+              Could not load billing history.
             </p>
             <p className="mt-1 font-mono text-[12px] text-fg-faint">
               {accountState.message}
@@ -892,18 +893,22 @@ export default function BillingSection() {
           </div>
         ) : invoices.length === 0 ? (
           <div className="px-5 py-9 text-center">
-            <p className="text-[13.5px] text-fg-muted">No invoices yet.</p>
+            <p className="text-[13.5px] text-fg-muted">
+              No invoices or top-ups yet.
+            </p>
           </div>
         ) : (
           <>
             <div className={`${ST_COLS_5} ${ST_HEAD_CLASS}`}>
-              <span>Invoice</span>
+              <span>Item</span>
               <span>Date</span>
               <span>Amount</span>
               <span>Status</span>
               <span aria-hidden="true" />
             </div>
-            {invoices.map((inv) => (
+            {invoices.map((inv) => {
+              const isAutoTopUp = inv.invoiceType === "auto_topup";
+              return (
               <div
                 key={inv.id}
                 className={`${ST_COLS_5} border-b border-hairline last:border-b-0 transition-colors hover:bg-zebra`}
@@ -918,7 +923,7 @@ export default function BillingSection() {
                   {formatInvoiceAmount(inv.totalAmount, inv.currency)}
                 </div>
                 <div className="text-[12px] capitalize text-fg-faint">
-                  {inv.status}
+                  {isAutoTopUp ? "Top-up" : inv.status}
                 </div>
                 <div className="flex justify-end gap-3">
                   <button
@@ -927,8 +932,9 @@ export default function BillingSection() {
                     disabled={invoiceBusyId === inv.id}
                     onClick={() => void onOpenInvoice(inv.id, "hosted")}
                   >
-                    View
+                    {isAutoTopUp ? "Receipt" : "View"}
                   </button>
+                  {isAutoTopUp ? null : (
                   <button
                     type="button"
                     className="inline-flex items-center gap-1 text-[12px] text-fg-strong transition-colors hover:text-fg disabled:opacity-50"
@@ -938,9 +944,11 @@ export default function BillingSection() {
                     <Download className="h-3 w-3" aria-hidden="true" />
                     PDF
                   </button>
+                  )}
                 </div>
               </div>
-            ))}
+              );
+            })}
           </>
         )}
       </SettingsCard>
diff --git a/lib/dashboard/pymthouse-billing-bff.ts b/lib/dashboard/pymthouse-billing-bff.ts
index 83a66b6..3664521 100644
--- a/lib/dashboard/pymthouse-billing-bff.ts
+++ b/lib/dashboard/pymthouse-billing-bff.ts
@@ -4,6 +4,7 @@ import {
   type AppUserInvoiceHostedUrlResult,
   type AppUserPaymentMethod,
   type BillingProduct,
+  type BillingState,
   type CreateAppUserPaymentMethodCheckoutResult,
   type CreateBillingCheckoutResult,
   type UserSubscriptionResponse,
@@ -380,6 +381,14 @@ export async function setDashboardUserDefaultPaymentMethod(
   return client.setUserDefaultPaymentMethod(externalUserId, paymentMethodId);
 }
 
+/** Promote first attached PM to Stripe default when none is set (post-Checkout). */
+export async function ensureDashboardUserDefaultPaymentMethod(
+  externalUserId: string
+) {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  return client.ensureUserDefaultPaymentMethod(externalUserId);
+}
+
 export async function removeDashboardUserPaymentMethod(
   externalUserId: string,
   paymentMethodId: string
@@ -416,11 +425,9 @@ export type DashboardOwnerWallet = {
     /** null = provider state unknown (fail open upstream). */
     hasDefault: boolean | null;
   };
+  /** Canonical spend posture; the API owns the customer-facing copy. */
+  billingState: BillingState;
   payPerUsePlans: DashboardWalletPayPerUsePlan[];
-  settlement: {
-    order: string; // "credits_then_auto_debit"
-    description: string;
-  };
 };
 
 export type DashboardWalletInvoice = {
@@ -459,38 +466,75 @@ export type DashboardWalletPaymentMethodCheckoutResult = {
 
 async function walletFetch<T>(
   path: string,
-  init?: { method?: string; body?: Record<string, unknown> }
+  init?: {
+    method?: string;
+    body?: Record<string, unknown>;
+    externalUserId?: string;
+    query?: Record<string, string | number | undefined>;
+  }
 ): Promise<T> {
   const publicClientId = readPublicClientId();
+  const params = new URLSearchParams();
+  const externalUserId = init?.externalUserId?.trim();
+  // GETs carry externalUserId as a query param; mutating methods put it in JSON.
+  if (externalUserId && (init?.method ?? "GET") === "GET") {
+    params.set("externalUserId", externalUserId);
+  }
+  for (const [key, value] of Object.entries(init?.query ?? {})) {
+    if (value === undefined) continue;
+    params.set(key, String(value));
+  }
+  const query = params.toString();
+  const separator = path.includes("?") ? "&" : "?";
+  const urlPath = `${path}${query ? `${separator}${query}` : ""}`;
+
+  const method = init?.method ?? "GET";
+  const body =
+    init?.body ||
+    (externalUserId && (method === "POST" || method === "PATCH"))
+      ? {
+          ...(init?.body ?? {}),
+          ...(externalUserId && (method === "POST" || method === "PATCH")
+            ? { externalUserId }
+            : {}),
+        }
+      : undefined;
+
   const response = await fetch(
-    `${pymthouseAppsOrigin()}/api/v1/apps/${encodeURIComponent(publicClientId)}/billing/wallet${path}`,
+    `${pymthouseAppsOrigin()}/api/v1/apps/${encodeURIComponent(publicClientId)}/billing/wallet${urlPath}`,
     {
       method: init?.method ?? "GET",
       headers: {
         Authorization: readM2mAuthHeader(),
         Accept: "application/json",
-        ...(init?.body ? { "Content-Type": "application/json" } : {}),
+        ...(body ? { "Content-Type": "application/json" } : {}),
       },
-      ...(init?.body ? { body: JSON.stringify(init.body) } : {}),
+      ...(body ? { body: JSON.stringify(body) } : {}),
       cache: "no-store",
     }
   );
   return readPymthouseResponse<T>(response);
 }
 
-/** GET …/billing/wallet — balance, PM on file, resolved PPU behavior, settlement order. */
-export async function getDashboardOwnerWallet(): Promise<DashboardOwnerWallet> {
-  return walletFetch<DashboardOwnerWallet>("");
+/** GET …/billing/wallet — balance, PM on file, billing state, PPU plans. */
+export async function getDashboardOwnerWallet(
+  externalUserId?: string
+): Promise<DashboardOwnerWallet> {
+  return walletFetch<DashboardOwnerWallet>("", {
+    externalUserId,
+  });
 }
 
 /** POST …/billing/wallet/top-up — payment-mode Stripe Checkout ($1–$10,000). */
 export async function startDashboardWalletTopUp(input: {
   amountUsd: string;
+  externalUserId: string;
   successUrl?: string;
   cancelUrl?: string;
 }): Promise<DashboardWalletTopUpResult> {
   return walletFetch<DashboardWalletTopUpResult>("/top-up", {
     method: "POST",
+    externalUserId: input.externalUserId,
     body: {
       amountUsd: input.amountUsd,
       ...(input.successUrl ? { successUrl: input.successUrl } : {}),
@@ -501,6 +545,7 @@ export async function startDashboardWalletTopUp(input: {
 
 /** GET …/billing/wallet/invoices — past platform invoices, newest first. */
 export async function listDashboardWalletInvoices(opts?: {
+  externalUserId?: string;
   page?: number;
   pageSize?: number;
 }): Promise<{
@@ -509,25 +554,28 @@ export async function listDashboardWalletInvoices(opts?: {
   pageSize: number;
   totalCount: number;
 }> {
-  const params = new URLSearchParams();
-  if (opts?.page) params.set("page", String(opts.page));
-  if (opts?.pageSize) params.set("pageSize", String(opts.pageSize));
-  const query = params.toString();
-  return walletFetch(`/invoices${query ? `?${query}` : ""}`);
+  return walletFetch(`/invoices`, {
+    externalUserId: opts?.externalUserId,
+    query: {
+      page: opts?.page,
+      pageSize: opts?.pageSize,
+    },
+  });
 }
 
 /** GET …/billing/wallet/payment-methods — attached PMs (brand + last4 only). */
-export async function listDashboardWalletPaymentMethods(): Promise<
-  DashboardWalletPaymentMethod[]
-> {
+export async function listDashboardWalletPaymentMethods(
+  externalUserId?: string
+): Promise<DashboardWalletPaymentMethod[]> {
   const result = await walletFetch<{
     paymentMethods?: DashboardWalletPaymentMethod[];
-  }>("/payment-methods");
+  }>("/payment-methods", { externalUserId });
   return result.paymentMethods ?? [];
 }
 
 /** POST …/billing/wallet/payment-methods — setup-mode Stripe Checkout for the auto-debit PM. */
 export async function startDashboardWalletPaymentMethodCheckout(input: {
+  externalUserId: string;
   successUrl?: string;
   cancelUrl?: string;
 }): Promise<DashboardWalletPaymentMethodCheckoutResult> {
@@ -535,6 +583,7 @@ export async function startDashboardWalletPaymentMethodCheckout(input: {
     "/payment-methods",
     {
       method: "POST",
+      externalUserId: input.externalUserId,
       body: {
         ...(input.successUrl ? { successUrl: input.successUrl } : {}),
         ...(input.cancelUrl ? { cancelUrl: input.cancelUrl } : {}),
@@ -542,3 +591,17 @@ export async function startDashboardWalletPaymentMethodCheckout(input: {
     }
   );
 }
+
+/** PATCH …/billing/wallet/payment-methods — promote default after Checkout return. */
+export async function ensureDashboardWalletDefaultPaymentMethod(
+  externalUserId: string
+): Promise<{ promoted: boolean; paymentMethodId: string | null }> {
+  return walletFetch<{ promoted: boolean; paymentMethodId: string | null }>(
+    "/payment-methods",
+    {
+      method: "PATCH",
+      externalUserId,
+      body: { ensureDefault: true },
+    }
+  );
+}
diff --git a/lib/dashboard/useBillingAccount.ts b/lib/dashboard/useBillingAccount.ts
index cd41e39..bbf907a 100644
--- a/lib/dashboard/useBillingAccount.ts
+++ b/lib/dashboard/useBillingAccount.ts
@@ -176,6 +176,28 @@ export function useBillingAccount(externalUserId: string | undefined) {
     [load],
   );
 
+  const ensureDefaultPaymentMethod = useCallback(
+    async (input: { externalUserId: string }) => {
+      const response = await fetch("/api/pymthouse/payment-methods", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          externalUserId: input.externalUserId,
+          ensureDefault: true,
+        }),
+      });
+      const body = await readResponseJson<{ error?: string }>(response);
+      if (!response.ok) {
+        throw new Error(
+          body.error ??
+            `Ensure default payment method failed (${response.status})`,
+        );
+      }
+      await load();
+    },
+    [load],
+  );
+
   const removePaymentMethod = useCallback(
     async (input: { externalUserId: string; paymentMethodId: string }) => {
       const response = await fetch("/api/pymthouse/payment-methods", {
@@ -200,6 +222,7 @@ export function useBillingAccount(externalUserId: string | undefined) {
     startPaymentMethodCheckout,
     openInvoice,
     setDefaultPaymentMethod,
+    ensureDefaultPaymentMethod,
     removePaymentMethod,
   };
 }
diff --git a/lib/dashboard/useOwnerWallet.ts b/lib/dashboard/useOwnerWallet.ts
index 0e2ced8..eec985a 100644
--- a/lib/dashboard/useOwnerWallet.ts
+++ b/lib/dashboard/useOwnerWallet.ts
@@ -42,21 +42,26 @@ export type OwnerWalletState =
     }
   | { status: "error"; message: string };
 
-export function useOwnerWallet(enabled: boolean) {
+export function useOwnerWallet(
+  enabled: boolean,
+  externalUserId: string | undefined,
+) {
   const [state, setState] = useState<OwnerWalletState>({ status: "idle" });
+  const trimmedUserId = externalUserId?.trim() || "";
 
   const load = useCallback(async () => {
-    if (!enabled) {
+    if (!enabled || !trimmedUserId) {
       setState({ status: "idle" });
       return;
     }
 
     setState({ status: "loading" });
     try {
+      const qs = `externalUserId=${encodeURIComponent(trimmedUserId)}`;
       const [walletResponse, pmResponse, invResponse] = await Promise.all([
-        fetch("/api/pymthouse/wallet"),
-        fetch("/api/pymthouse/wallet/payment-methods"),
-        fetch("/api/pymthouse/wallet/invoices?pageSize=20"),
+        fetch(`/api/pymthouse/wallet?${qs}`),
+        fetch(`/api/pymthouse/wallet/payment-methods?${qs}`),
+        fetch(`/api/pymthouse/wallet/invoices?${qs}&pageSize=20`),
       ]);
 
       const walletBody = await readResponseJson<
@@ -99,19 +104,49 @@ export function useOwnerWallet(enabled: boolean) {
           error instanceof Error ? error.message : "Failed to load wallet",
       });
     }
-  }, [enabled]);
+  }, [enabled, trimmedUserId]);
 
   useEffect(() => {
     void load();
   }, [load]);
 
-  const startTopUp = useCallback(async (input: { amountUsd: string }) => {
-    const response = await fetch("/api/pymthouse/wallet/top-up", {
+  const startTopUp = useCallback(
+    async (input: { amountUsd: string }) => {
+      if (!trimmedUserId) {
+        throw new Error("externalUserId is required");
+      }
+      const response = await fetch("/api/pymthouse/wallet/top-up", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          externalUserId: trimmedUserId,
+          amountUsd: input.amountUsd,
+          successUrl: `${window.location.origin}/usage?topup=succeeded`,
+          cancelUrl: `${window.location.origin}/usage?topup=canceled`,
+        }),
+      });
+      const body = await readResponseJson<{
+        checkoutUrl?: string;
+        error?: string;
+      }>(response);
+      if (!response.ok || !body.checkoutUrl) {
+        throw new Error(body.error ?? `Top-up failed (${response.status})`);
+      }
+      return { checkoutUrl: body.checkoutUrl };
+    },
+    [trimmedUserId],
+  );
+
+  const startPaymentMethodCheckout = useCallback(async () => {
+    if (!trimmedUserId) {
+      throw new Error("externalUserId is required");
+    }
+    const response = await fetch("/api/pymthouse/wallet/payment-methods", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
-        amountUsd: input.amountUsd,
-        successUrl: `${window.location.origin}/usage?topup=succeeded`,
+        externalUserId: trimmedUserId,
+        successUrl: `${window.location.origin}/usage?topup=pm-saved`,
         cancelUrl: `${window.location.origin}/usage?topup=canceled`,
       }),
     });
@@ -120,36 +155,40 @@ export function useOwnerWallet(enabled: boolean) {
       error?: string;
     }>(response);
     if (!response.ok || !body.checkoutUrl) {
-      throw new Error(body.error ?? `Top-up failed (${response.status})`);
+      throw new Error(
+        body.error ?? `Payment method checkout failed (${response.status})`,
+      );
     }
     return { checkoutUrl: body.checkoutUrl };
-  }, []);
+  }, [trimmedUserId]);
 
-  const startPaymentMethodCheckout = useCallback(async () => {
+  const ensureDefaultPaymentMethod = useCallback(async () => {
+    if (!trimmedUserId) {
+      throw new Error("externalUserId is required");
+    }
     const response = await fetch("/api/pymthouse/wallet/payment-methods", {
-      method: "POST",
+      method: "PATCH",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
-        successUrl: `${window.location.origin}/usage?topup=pm-saved`,
-        cancelUrl: `${window.location.origin}/usage?topup=canceled`,
+        externalUserId: trimmedUserId,
+        ensureDefault: true,
       }),
     });
-    const body = await readResponseJson<{
-      checkoutUrl?: string;
-      error?: string;
-    }>(response);
-    if (!response.ok || !body.checkoutUrl) {
+    const body = await readResponseJson<{ error?: string }>(response);
+    if (!response.ok) {
       throw new Error(
-        body.error ?? `Payment method checkout failed (${response.status})`,
+        body.error ??
+          `Ensure default payment method failed (${response.status})`,
       );
     }
-    return { checkoutUrl: body.checkoutUrl };
-  }, []);
+    await load();
+  }, [trimmedUserId, load]);
 
   return {
     state,
     reload: load,
     startTopUp,
     startPaymentMethodCheckout,
+    ensureDefaultPaymentMethod,
   };
 }
diff --git a/lib/dashboard/wallet-settlement-display.test.ts b/lib/dashboard/wallet-settlement-display.test.ts
new file mode 100644
index 0000000..279b79b
--- /dev/null
+++ b/lib/dashboard/wallet-settlement-display.test.ts
@@ -0,0 +1,147 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import type { BillingState } from "@pymthouse/builder-sdk";
+import {
+  collectionSchedule,
+  overageBufferMeter,
+  spendPostureBadge,
+} from "@/lib/dashboard/wallet-settlement-display";
+
+function money(usdMicros: string, usd: string) {
+  return { usdMicros, usd, currency: "USD" };
+}
+
+function makeState(overrides: {
+  status?: BillingState["status"];
+  ceiling?: { usdMicros: string; usd: string };
+  unbilledDebt?: { usdMicros: string; usd: string } | null;
+  remaining?: { usdMicros: string; usd: string } | null;
+  utilizationBps?: number | null;
+  leadThreshold?: { usdMicros: string; usd: string };
+}): BillingState {
+  return {
+    asOf: "2026-08-08T00:00:00.000Z",
+    subject: {
+      type: "owner",
+      externalUserId: null,
+      billingMode: "owner_rollup",
+    },
+    status: overrides.status ?? "overage",
+    canSpend: true,
+    reason: null,
+    funding: {
+      prepaid: money("0", "0.00"),
+      included: money("0", "0.00"),
+      spendable: money("0", "0.00"),
+      overage: {
+        eligible: true,
+        ceiling: {
+          ...money("2000000", "2.00"),
+          ...(overrides.ceiling ?? {}),
+        },
+        unbilledDebt:
+          overrides.unbilledDebt === undefined
+            ? money("500000", "0.50")
+            : overrides.unbilledDebt && {
+                ...money("0", "0.00"),
+                ...overrides.unbilledDebt,
+              },
+        remaining:
+          overrides.remaining === undefined
+            ? money("1500000", "1.50")
+            : overrides.remaining && {
+                ...money("0", "0.00"),
+                ...overrides.remaining,
+              },
+        utilizationBps:
+          overrides.utilizationBps === undefined
+            ? 2500
+            : overrides.utilizationBps,
+        debtSource: "gathering_invoice",
+      },
+    },
+    collection: {
+      mode: "progressive_invoice",
+      collector: "openmeter_stripe",
+      paymentMethod: { hasDefault: true, brand: "visa", last4: "4242" },
+      nextAction: "none",
+      leadThreshold: {
+        ...money("1000000", "1.00"),
+        ...(overrides.leadThreshold ?? {}),
+      },
+      minimumCharge: money("500000", "0.50"),
+      cycle: "MONTH",
+      collectionInterval: "DAY",
+      lastRaisedAt: null,
+      nextRaiseEligibleAt: null,
+    },
+    explain: { headline: "", detail: "", docsUrl: "" },
+  };
+}
+
+describe("spendPostureBadge", () => {
+  it("colours each posture distinctly", () => {
+    assert.deepEqual(spendPostureBadge("active"), {
+      label: "Credits",
+      tone: "ok",
+    });
+    assert.equal(spendPostureBadge("overage").tone, "info");
+    assert.equal(spendPostureBadge("at_risk").tone, "warn");
+    assert.equal(spendPostureBadge("blocked").tone, "danger");
+  });
+});
+
+describe("overageBufferMeter", () => {
+  it("reports debt against the ceiling with remaining headroom", () => {
+    const meter = overageBufferMeter(makeState({}));
+    assert.equal(meter?.primary, "$0.50 / $2.00");
+    assert.equal(meter?.status, "$1.50 of buffer left");
+    assert.equal(meter?.percent, 25);
+  });
+
+  it("says the buffer is used up when blocked", () => {
+    const meter = overageBufferMeter(
+      makeState({
+        status: "blocked",
+        unbilledDebt: { usdMicros: "2000000", usd: "2.00" },
+        remaining: { usdMicros: "0", usd: "0.00" },
+        utilizationBps: 10_000,
+      }),
+    );
+    assert.equal(meter?.status, "Buffer used up");
+    assert.equal(meter?.percent, 100);
+  });
+
+  it("clamps utilization above the ceiling to a full bar", () => {
+    const meter = overageBufferMeter(makeState({ utilizationBps: 14_000 }));
+    assert.equal(meter?.percent, 100);
+  });
+
+  it("hides the meter when there is no ceiling", () => {
+    const meter = overageBufferMeter(
+      makeState({ ceiling: { usdMicros: "0", usd: "0.00" } }),
+    );
+    assert.equal(meter, null);
+  });
+
+  it("hides the meter when debt could not be read", () => {
+    const meter = overageBufferMeter(makeState({ unbilledDebt: null }));
+    assert.equal(meter, null);
+  });
+});
+
+describe("collectionSchedule", () => {
+  it("names the amount trigger and the recurring sweep", () => {
+    const copy = collectionSchedule(makeState({}));
+    assert.match(copy, /\$1\.00/);
+    assert.match(copy, /at least once a day/);
+  });
+
+  it("falls back to the sweep alone with no amount trigger", () => {
+    const copy = collectionSchedule(
+      makeState({ leadThreshold: { usdMicros: "0", usd: "0.00" } }),
+    );
+    assert.equal(copy, "Usage is invoiced every day.");
+  });
+});
diff --git a/lib/dashboard/wallet-settlement-display.ts b/lib/dashboard/wallet-settlement-display.ts
new file mode 100644
index 0000000..c94d3a0
--- /dev/null
+++ b/lib/dashboard/wallet-settlement-display.ts
@@ -0,0 +1,72 @@
+import type { BillingState, BillingStatus } from "@pymthouse/builder-sdk";
+import { microsToUsd } from "@/lib/dashboard/usage-capability-display";
+
+/** Wallet strip amounts: always two decimals (matches prepaid `$0.00`). */
+export function formatWalletUsd(micros: string | null | undefined): string {
+  if (!micros?.trim()) return "0.00";
+  return microsToUsd(micros).toFixed(2);
+}
+
+export type SpendPostureTone = "ok" | "info" | "warn" | "danger";
+
+/**
+ * Short badge for the spend posture. The long-form copy comes from
+ * `billingState.explain`, which the API owns so every surface says the same
+ * thing; the dashboard only picks the label and the colour.
+ */
+export function spendPostureBadge(status: BillingStatus): {
+  label: string;
+  tone: SpendPostureTone;
+} {
+  switch (status) {
+    case "active":
+      return { label: "Credits", tone: "ok" };
+    case "overage":
+      return { label: "Pay as you go", tone: "info" };
+    case "at_risk":
+      return { label: "Collecting payment", tone: "warn" };
+    case "blocked":
+      return { label: "Paused", tone: "danger" };
+  }
+}
+
+/**
+ * Buffer consumption for the progress meter. Null when there is no ceiling to
+ * fill, or when debt could not be read — the meter is hidden in both cases
+ * rather than drawn at a made-up value.
+ */
+export function overageBufferMeter(state: BillingState): {
+  primary: string;
+  status: string;
+  percent: number;
+} | null {
+  const { overage } = state.funding;
+  const debt = overage.unbilledDebt;
+  if (!debt || overage.ceiling.usdMicros === "0") return null;
+
+  const percent = Math.min(
+    100,
+    Math.max(0, Math.round((overage.utilizationBps ?? 0) / 100)),
+  );
+  const remaining = overage.remaining?.usd ?? "0.00";
+  return {
+    primary: `$${debt.usd} / $${overage.ceiling.usd}`,
+    status:
+      state.status === "blocked"
+        ? "Buffer used up"
+        : `$${remaining} of buffer left`,
+    percent,
+  };
+}
+
+/** When the next invoice goes out, in the customer's terms. */
+export function collectionSchedule(state: BillingState): string {
+  const lead = state.collection.leadThreshold;
+  if (lead.usdMicros === "0") {
+    return `Usage is invoiced every ${state.collection.collectionInterval.toLowerCase()}.`;
+  }
+  return (
+    `Usage is invoiced automatically once $${lead.usd} of it has built up, ` +
+    `and at least once a ${state.collection.collectionInterval.toLowerCase()}.`
+  );
+}

From bc550427071b42b23d6720ae5fb2443b7be9d942 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Mon, 10 Aug 2026 21:18:44 -0400
Subject: [PATCH 10/13] refactor(auth): update user ID handling and async
 methods in AuthContext

- Changed `MockUser.id` to derive from email using SHA-256 for consistency.
- Updated `connect` and `updateUser` methods to return promises for better async handling.
- Enhanced `hydrateMockUser` to support async operations and ensure proper user ID assignment.
- Improved localStorage handling for user sessions and legacy machine IDs.
- Adjusted login page to await connection on email and OAuth submissions.
- Refined comments and documentation for clarity.
---
 components/dashboard/AuthContext.tsx          | 90 ++++++++++++-------
 components/dashboard/LoginPage.tsx            |  8 +-
 components/dashboard/PlansPanel.tsx           |  2 +-
 components/dashboard/SidebarUsageCard.tsx     |  2 +-
 components/dashboard/UsageView.tsx            |  2 +-
 components/dashboard/WalletPanel.tsx          | 32 +++++--
 .../wallet-settlement-display.test.ts         |  7 ++
 7 files changed, 98 insertions(+), 45 deletions(-)

diff --git a/components/dashboard/AuthContext.tsx b/components/dashboard/AuthContext.tsx
index 797ba0a..d7b97d5 100644
--- a/components/dashboard/AuthContext.tsx
+++ b/components/dashboard/AuthContext.tsx
@@ -11,7 +11,10 @@ import {
 export type AuthProvider = "github" | "google" | "email";
 
 export interface MockUser {
-  /** Persistent machine id used as PymtHouse `externalUserId` (never email). */
+  /**
+   * Stable id derived from email (SHA-256 hex, `eu_` prefix).
+   * Used as PymtHouse `externalUserId` — never the raw email (SDK forbids @).
+   */
   id: string;
   name: string;
   email: string;
@@ -24,8 +27,8 @@ interface AuthContextValue {
   isConnected: boolean;
   isLoading: boolean;
   user: MockUser | null;
-  connect: (user: Omit<MockUser, "id"> & { id?: string }) => void;
-  updateUser: (patch: Partial<MockUser>) => void;
+  connect: (user: Omit<MockUser, "id">) => Promise<void>;
+  updateUser: (patch: Partial<Omit<MockUser, "id">>) => Promise<void>;
   disconnect: () => void;
 }
 
@@ -33,8 +36,8 @@ const AuthContext = createContext<AuthContextValue>({
   isConnected: false,
   isLoading: true,
   user: null,
-  connect: () => {},
-  updateUser: () => {},
+  connect: async () => {},
+  updateUser: async () => {},
   disconnect: () => {},
 });
 
@@ -42,18 +45,34 @@ export function useAuth() {
   return useContext(AuthContext);
 }
 
-function newMachineId(): string {
-  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
-    return crypto.randomUUID();
-  }
-  return `dash_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+const USER_SESSION_KEY = "dashboard-user";
+/** Legacy key from machine-id identity; cleared on load. */
+const LEGACY_MACHINE_ID_KEY = "dashboard-machine-id";
+
+/**
+ * Deterministic PymtHouse externalUserId from email.
+ * Must match builder-sdk: no `@`, no `owner:`/`user:` prefix, charset [A-Za-z0-9._:-].
+ */
+export async function externalUserIdFromEmail(email: string): Promise<string> {
+  const normalized = email.trim().toLowerCase() || "demo@livepeer.org";
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(`livepeer-dashboard:externalUserId:${normalized}`),
+  );
+  const hex = Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  return `eu_${hex}`;
 }
 
-function hydrateMockUser(parsed: Partial<MockUser>): MockUser {
+async function hydrateMockUser(
+  parsed: Partial<MockUser> & Pick<MockUser, "email">,
+): Promise<MockUser> {
+  const email = parsed.email?.trim() || "demo@livepeer.org";
   return {
-    id: typeof parsed.id === "string" && parsed.id.trim() ? parsed.id.trim() : newMachineId(),
+    id: await externalUserIdFromEmail(email),
     name: parsed.name ?? "Demo User",
-    email: parsed.email ?? "demo@livepeer.org",
+    email,
     initials: parsed.initials ?? "DU",
     provider: (parsed.provider as AuthProvider) ?? "email",
     avatarUrl: parsed.avatarUrl,
@@ -65,46 +84,51 @@ export function AuthProvider({ children }: { children: ReactNode }) {
   const [isLoading, setIsLoading] = useState(true);
   const [user, setUser] = useState<MockUser | null>(null);
 
-  // Restore from localStorage
+  // Restore from localStorage; re-derive id from email so prior UUID sessions migrate.
   useEffect(() => {
-    if (typeof window !== "undefined") {
-      const stored = localStorage.getItem("dashboard-user");
+    if (typeof window === "undefined") return;
+
+    localStorage.removeItem(LEGACY_MACHINE_ID_KEY);
+
+    void (async () => {
+      const stored = localStorage.getItem(USER_SESSION_KEY);
       if (stored) {
         try {
           const parsed = JSON.parse(stored) as Partial<MockUser>;
-          // Backfill provider + machine id for pre-existing localStorage entries
-          const hydrated = hydrateMockUser(parsed);
-          setUser(hydrated);
-          setIsConnected(true);
-          localStorage.setItem("dashboard-user", JSON.stringify(hydrated));
+          if (parsed.email) {
+            const hydrated = await hydrateMockUser(parsed);
+            setUser(hydrated);
+            setIsConnected(true);
+            localStorage.setItem(USER_SESSION_KEY, JSON.stringify(hydrated));
+          }
         } catch {
           // ignore
         }
       }
       setIsLoading(false);
-    }
+    })();
   }, []);
 
-  const connect = (u: Omit<MockUser, "id"> & { id?: string }) => {
-    const next = hydrateMockUser(u);
+  const connect = async (u: Omit<MockUser, "id">) => {
+    const next = await hydrateMockUser(u);
     setUser(next);
     setIsConnected(true);
-    localStorage.setItem("dashboard-user", JSON.stringify(next));
+    localStorage.setItem(USER_SESSION_KEY, JSON.stringify(next));
   };
 
-  const updateUser = (patch: Partial<MockUser>) => {
-    setUser((prev) => {
-      if (!prev) return prev;
-      const next = hydrateMockUser({ ...prev, ...patch });
-      localStorage.setItem("dashboard-user", JSON.stringify(next));
-      return next;
-    });
+  const updateUser = async (patch: Partial<Omit<MockUser, "id">>) => {
+    const prev = user;
+    if (!prev) return;
+    const next = await hydrateMockUser({ ...prev, ...patch });
+    setUser(next);
+    localStorage.setItem(USER_SESSION_KEY, JSON.stringify(next));
   };
 
   const disconnect = () => {
     setUser(null);
     setIsConnected(false);
-    localStorage.removeItem("dashboard-user");
+    localStorage.removeItem(USER_SESSION_KEY);
+    localStorage.removeItem(LEGACY_MACHINE_ID_KEY);
   };
 
   return (
diff --git a/components/dashboard/LoginPage.tsx b/components/dashboard/LoginPage.tsx
index 3ddd7f6..acb1387 100644
--- a/components/dashboard/LoginPage.tsx
+++ b/components/dashboard/LoginPage.tsx
@@ -78,10 +78,10 @@ export default function LoginPage({ initialMode = "signin" }: LoginPageProps = {
   const { connect } = useAuth();
   const router = useRouter();
 
-  function handleEmailSubmit(e?: React.FormEvent) {
+  async function handleEmailSubmit(e?: React.FormEvent) {
     e?.preventDefault();
     const displayName = name || email.split("@")[0] || "Demo User";
-    connect({
+    await connect({
       name: displayName,
       email: email || "demo@livepeer.org",
       initials: getInitials(displayName),
@@ -90,14 +90,14 @@ export default function LoginPage({ initialMode = "signin" }: LoginPageProps = {
     router.push("/home");
   }
 
-  function handleOAuthSubmit(provider: AuthProvider) {
+  async function handleOAuthSubmit(provider: AuthProvider) {
     // Mock OAuth — pretend the provider returned a profile.
     const mockProfiles: Record<"github" | "google", { name: string; email: string }> = {
       github: { name: "Rick Staa", email: "rick.staa@github.com" },
       google: { name: "Rick Staa", email: "rick.staa@gmail.com" },
     };
     const profile = mockProfiles[provider as "github" | "google"];
-    connect({
+    await connect({
       name: profile.name,
       email: profile.email,
       initials: getInitials(profile.name),
diff --git a/components/dashboard/PlansPanel.tsx b/components/dashboard/PlansPanel.tsx
index 0a1df80..9ac4c20 100644
--- a/components/dashboard/PlansPanel.tsx
+++ b/components/dashboard/PlansPanel.tsx
@@ -30,7 +30,7 @@ function resolvedPayPerUseBehavior(plan: DashboardBillingPlan): string {
   const resolved = plan.resolvedBehavior?.trim();
   if (resolved) return resolved;
 
-  return "Usage draws down prepaid credits first, then is invoiced automatically as it accrues.";
+  return "Usage draws down included usage first, then prepaid credits, then is invoiced automatically as it accrues.";
 }
 
 function readCheckoutFlash(): "success" | "cancel" | null {
diff --git a/components/dashboard/SidebarUsageCard.tsx b/components/dashboard/SidebarUsageCard.tsx
index d596062..ea1178b 100644
--- a/components/dashboard/SidebarUsageCard.tsx
+++ b/components/dashboard/SidebarUsageCard.tsx
@@ -51,7 +51,7 @@ export default function SidebarUsageCard() {
     balance && BigInt(balance.lifetimeGrantedUsdMicros || "0") > BigInt(0);
 
   const resetsAt = formatPeriodResetLabel(data.period.end);
-  const planLabel = showUsdAllowance ? "Prepaid" : "Usage";
+  const planLabel = showUsdAllowance ? "Included usage" : "Usage";
 
   let primaryUsed: number;
   let primaryLimit: number | null;
diff --git a/components/dashboard/UsageView.tsx b/components/dashboard/UsageView.tsx
index 30b15d3..ad43e78 100644
--- a/components/dashboard/UsageView.tsx
+++ b/components/dashboard/UsageView.tsx
@@ -529,7 +529,7 @@ function LimitsPanel({
   const limits = balance
     ? [
         {
-          label: "Prepaid allowance",
+          label: "Included usage",
           used: microsToUsdDisplay(balance.consumedUsdMicros),
           max: `$${microsToUsdDisplay(balance.lifetimeGrantedUsdMicros)}`,
           pct:
diff --git a/components/dashboard/WalletPanel.tsx b/components/dashboard/WalletPanel.tsx
index bf50a6e..0aa3904 100644
--- a/components/dashboard/WalletPanel.tsx
+++ b/components/dashboard/WalletPanel.tsx
@@ -192,18 +192,31 @@ export default function WalletPanel({
           <div className="mt-4 grid grid-cols-1 gap-4 sm:grid-cols-3">
             <div>
               <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
-                Prepaid credits
+                Included usage
               </p>
               <p className="mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] text-fg">
-                ${balanceUsd}
+                $
+                {billingState.funding.includedUsage?.remaining.usd ??
+                  billingState.funding.included.usd}
               </p>
+              {billingState.funding.includedUsage &&
+              billingState.funding.includedUsage.total.usdMicros !== "0" ? (
+                <p className="mt-1 text-[11px] text-fg-muted">
+                  $
+                  {billingState.funding.includedUsage.consumed.usd} of $
+                  {billingState.funding.includedUsage.total.usd} used
+                  {billingState.funding.includedUsage.sourcePlan?.name
+                    ? ` · ${billingState.funding.includedUsage.sourcePlan.name}`
+                    : ""}
+                </p>
+              ) : null}
             </div>
             <div>
               <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
-                Usage this period
+                Prepaid credits
               </p>
               <p className="mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] text-fg">
-                ${usageUsd}
+                ${balanceUsd}
               </p>
             </div>
             {meter ? (
@@ -229,7 +242,16 @@ export default function WalletPanel({
                 </div>
                 <p className="mt-1 text-[11px] text-fg-muted">{meter.status}</p>
               </div>
-            ) : null}
+            ) : (
+              <div>
+                <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
+                  Usage this period
+                </p>
+                <p className="mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] text-fg">
+                  ${usageUsd}
+                </p>
+              </div>
+            )}
           </div>
           <p className="mt-3 text-[12px] text-fg-muted">
             {collectionSchedule(billingState)}
diff --git a/lib/dashboard/wallet-settlement-display.test.ts b/lib/dashboard/wallet-settlement-display.test.ts
index 279b79b..7c28269 100644
--- a/lib/dashboard/wallet-settlement-display.test.ts
+++ b/lib/dashboard/wallet-settlement-display.test.ts
@@ -33,6 +33,13 @@ function makeState(overrides: {
     funding: {
       prepaid: money("0", "0.00"),
       included: money("0", "0.00"),
+      includedUsage: {
+        total: money("0", "0.00"),
+        remaining: money("0", "0.00"),
+        consumed: money("0", "0.00"),
+        resetsAt: "2026-09-01T00:00:00.000Z",
+        sourcePlan: null,
+      },
       spendable: money("0", "0.00"),
       overage: {
         eligible: true,

From 6d4b24af34bb3c71e30720c5c2231bd5f9244d8b Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Mon, 10 Aug 2026 21:18:55 -0400
Subject: [PATCH 11/13] feat(billing): enhance billing plan handling and UI
 updates

- Introduced `formatBillingPlanPrice` to standardize billing plan price formatting, including handling of included usage for Starter plans.
- Updated `isUsagePlan` to account for `isStarterDefault` in plan checks.
- Enhanced `PlansPanel` and `BillingSection` components to support new billing logic, including improved URL handling for plan changes.
- Added `availableRunway` and `overageLimitNote` functions to better represent wallet states and spending limits in the UI.
- Implemented soft error handling for billing list availability in `useBillingAccount`.
- Updated tests to cover new billing functionalities and ensure accurate behavior across components.
---
 components/dashboard/PlansPanel.tsx           |  98 ++++++---
 components/dashboard/UsageView.tsx            |   3 +-
 components/dashboard/WalletPanel.tsx          |  81 ++------
 .../dashboard/settings/BillingSection.tsx     | 192 ++++++++++++------
 .../billing-subscription-state.test.ts        | 125 ++++++++++++
 lib/dashboard/billing-subscription-state.ts   | 172 +++++++++++++++-
 lib/dashboard/pymthouse-billing-bff.ts        |  38 +++-
 lib/dashboard/useBillingAccount.test.ts       |  16 ++
 lib/dashboard/useBillingAccount.ts            | 148 +++++++++-----
 .../wallet-settlement-display.test.ts         | 126 +++++++++---
 lib/dashboard/wallet-settlement-display.ts    | 100 ++++++---
 11 files changed, 840 insertions(+), 259 deletions(-)
 create mode 100644 lib/dashboard/useBillingAccount.test.ts

diff --git a/components/dashboard/PlansPanel.tsx b/components/dashboard/PlansPanel.tsx
index 9ac4c20..7c8e84b 100644
--- a/components/dashboard/PlansPanel.tsx
+++ b/components/dashboard/PlansPanel.tsx
@@ -3,27 +3,21 @@
 import { useEffect, useState } from "react";
 import Button from "@/components/design-system/Button";
 import type { DashboardBillingPlan } from "@/lib/dashboard/pymthouse-billing-bff";
+import {
+  formatBillingPlanPrice,
+} from "@/lib/dashboard/billing-subscription-state";
 import { useBillingPlans } from "@/lib/dashboard/useBillingPlans";
 
-function isUsagePlan(plan: Pick<DashboardBillingPlan, "type">): boolean {
+function isUsagePlan(
+  plan: Pick<DashboardBillingPlan, "type" | "isStarterDefault">
+): boolean {
+  if (plan.isStarterDefault) return false;
   return plan.type.trim().toLowerCase() === "usage";
 }
 
 function formatPrice(plan: DashboardBillingPlan): string {
-  const n = Number(plan.priceAmount);
-  const money = Number.isFinite(n)
-    ? new Intl.NumberFormat("en-US", {
-        style: "currency",
-        currency: plan.priceCurrency || "USD",
-      }).format(n)
-    : plan.priceAmount;
-
-  if (isUsagePlan(plan)) return `${money} · pay as you go`;
-  if (!plan.billingCycle) return money;
-  const c = plan.billingCycle.toLowerCase();
-  if (c === "monthly" || c === "month") return `${money}/mo`;
-  if (c === "yearly" || c === "year" || c === "annual") return `${money}/yr`;
-  return `${money} · ${plan.billingCycle}`;
+  const { price, priceSub } = formatBillingPlanPrice(plan);
+  return `${price}${priceSub}`;
 }
 
 function resolvedPayPerUseBehavior(plan: DashboardBillingPlan): string {
@@ -40,11 +34,25 @@ function readCheckoutFlash(): "success" | "cancel" | null {
   return null;
 }
 
+function readResumePlanChange(): string | null {
+  if (typeof window === "undefined") return null;
+  const value = new URLSearchParams(window.location.search)
+    .get("changePlan")
+    ?.trim();
+  return value || null;
+}
+
 function clearCheckoutQueryParam(): void {
   if (typeof window === "undefined") return;
   const url = new URL(window.location.href);
-  if (!url.searchParams.has("checkout")) return;
-  url.searchParams.delete("checkout");
+  let changed = false;
+  for (const key of ["checkout", "changePlan"] as const) {
+    if (url.searchParams.has(key)) {
+      url.searchParams.delete(key);
+      changed = true;
+    }
+  }
+  if (!changed) return;
   window.history.replaceState({}, "", `${url.pathname}${url.search}${url.hash}`);
 }
 
@@ -61,13 +69,45 @@ export default function PlansPanel({
 
   useEffect(() => {
     const next = readCheckoutFlash();
-    if (!next) return;
-    setFlash(next);
+    const resumePlanId = readResumePlanChange();
+    if (!next && !resumePlanId) return;
+    if (resumePlanId && !externalUserId?.trim()) return;
+
+    if (next) setFlash(next);
     clearCheckoutQueryParam();
-    if (next === "success") {
+    if (next !== "success") return;
+
+    void (async () => {
+      if (resumePlanId && externalUserId?.trim()) {
+        setBusyPlanId(resumePlanId);
+        try {
+          const result = await changePlan({
+            planId: resumePlanId,
+            externalUserId: externalUserId.trim(),
+            successUrl: `${window.location.origin}/usage?checkout=success&changePlan=${encodeURIComponent(resumePlanId)}`,
+            cancelUrl: `${window.location.origin}/usage?checkout=cancel`,
+          });
+          if (result.checkoutUrl) {
+            window.location.assign(result.checkoutUrl);
+            return;
+          }
+          await reload();
+          setError("Plan updated.");
+        } catch (err) {
+          setError(
+            err instanceof Error
+              ? err.message
+              : "Could not finish plan change after adding a card",
+          );
+        } finally {
+          setBusyPlanId(null);
+        }
+        return;
+      }
       void reload();
-    }
-  }, [reload]);
+    })();
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- resume once from return URL
+  }, [reload, changePlan, externalUserId]);
 
   async function onSubscribe(planId: string) {
     if (!externalUserId?.trim()) {
@@ -99,13 +139,13 @@ export default function PlansPanel({
         ? await changePlan({
             planId,
             externalUserId: userId,
-            successUrl: `${window.location.origin}/usage?checkout=success`,
+            successUrl: `${window.location.origin}/usage?checkout=success&changePlan=${encodeURIComponent(planId)}`,
             cancelUrl: `${window.location.origin}/usage?checkout=cancel`,
           })
         : await subscribe({
             planId,
             externalUserId: userId,
-            successUrl: `${window.location.origin}/usage?checkout=success`,
+            successUrl: `${window.location.origin}/usage?checkout=success&changePlan=${encodeURIComponent(planId)}`,
             cancelUrl: `${window.location.origin}/usage?checkout=cancel`,
           });
 
@@ -216,9 +256,13 @@ export default function PlansPanel({
                 >
                   {busyPlanId === plan.id
                     ? "Redirecting…"
-                    : isUsagePlan(plan)
-                      ? "Enable pay-per-use"
-                      : "Subscribe"}
+                    : plan.isStarterDefault
+                      ? hasActiveSubscription && !isCurrent
+                        ? "Switch to Starter"
+                        : "Choose Starter"
+                      : isUsagePlan(plan)
+                        ? "Enable pay-per-use"
+                        : "Subscribe"}
                 </Button>
               )}
             </li>
diff --git a/components/dashboard/UsageView.tsx b/components/dashboard/UsageView.tsx
index ad43e78..6d104de 100644
--- a/components/dashboard/UsageView.tsx
+++ b/components/dashboard/UsageView.tsx
@@ -6,7 +6,6 @@ import StackedAreaChart, { MiniSpark } from "@/components/dashboard/StackedAreaC
 import Button from "@/components/design-system/Button";
 import { useAuth } from "@/components/dashboard/AuthContext";
 import { useAccountUsage } from "@/lib/dashboard/useAccountUsage";
-import { getUtcCalendarMonthIsoBounds } from "@pymthouse/builder-sdk";
 import {
   buildUsageCapabilityRows,
   formatPeriodResetLabel,
@@ -266,7 +265,7 @@ export default function UsageView() {
   const { data } = usageState;
   const grandReq = filteredRows.reduce((a, c) => a + c.requestCount, 0);
   const grandSpend = filteredRows.reduce((a, c) => a + c.spendUsd, 0);
-  const resetsAt = formatPeriodResetLabel(getUtcCalendarMonthIsoBounds().endDate);
+  const resetsAt = formatPeriodResetLabel(data.period.end);
   const grantedMicros = data.balance?.lifetimeGrantedUsdMicros ?? null;
 
   return (
diff --git a/components/dashboard/WalletPanel.tsx b/components/dashboard/WalletPanel.tsx
index 0aa3904..8c4b939 100644
--- a/components/dashboard/WalletPanel.tsx
+++ b/components/dashboard/WalletPanel.tsx
@@ -4,9 +4,10 @@ import { useEffect, useState } from "react";
 import Button from "@/components/design-system/Button";
 import { useOwnerWallet } from "@/lib/dashboard/useOwnerWallet";
 import {
+  availableRunway,
   collectionSchedule,
   formatWalletUsd,
-  overageBufferMeter,
+  overageLimitNote,
   spendPostureBadge,
   type SpendPostureTone,
 } from "@/lib/dashboard/wallet-settlement-display";
@@ -50,11 +51,11 @@ const POSTURE_TONE_CLASS: Record<SpendPostureTone, string> = {
   danger: "border-rose-400/30 text-rose-400",
 };
 
-const METER_TONE_CLASS: Record<SpendPostureTone, string> = {
-  ok: "bg-emerald-400",
-  info: "bg-fg-muted",
-  warn: "bg-amber-400",
-  danger: "bg-rose-400",
+const AVAILABLE_TONE_CLASS: Record<SpendPostureTone, string> = {
+  ok: "text-fg",
+  info: "text-fg",
+  warn: "text-amber-400",
+  danger: "text-rose-400",
 };
 
 /** Only follow https (or localhost http, for dev) Checkout URLs. */
@@ -161,11 +162,11 @@ export default function WalletPanel({
   }
 
   const { wallet, paymentMethods, invoices } = state;
-  const balanceUsd = wallet.balance?.usd ?? "0.00";
   const usageUsd = formatWalletUsd(periodBillableUsdMicros);
   const billingState = wallet.billingState;
   const posture = spendPostureBadge(billingState.status);
-  const meter = overageBufferMeter(billingState);
+  const runway = availableRunway(billingState);
+  const limitNote = overageLimitNote(billingState);
   const defaultPm =
     paymentMethods.find((pm) => pm.isDefault) ?? paymentMethods[0] ?? null;
   const hasPaymentMethod =
@@ -189,69 +190,31 @@ export default function WalletPanel({
             {billingState.explain.detail}
           </p>
 
-          <div className="mt-4 grid grid-cols-1 gap-4 sm:grid-cols-3">
+          <div className="mt-4 grid grid-cols-1 gap-4 sm:grid-cols-2">
             <div>
               <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
-                Included usage
+                Available
               </p>
-              <p className="mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] text-fg">
-                $
-                {billingState.funding.includedUsage?.remaining.usd ??
-                  billingState.funding.included.usd}
+              <p
+                className={`mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] ${AVAILABLE_TONE_CLASS[runway.tone]}`}
+              >
+                {runway.usd}
               </p>
-              {billingState.funding.includedUsage &&
-              billingState.funding.includedUsage.total.usdMicros !== "0" ? (
-                <p className="mt-1 text-[11px] text-fg-muted">
-                  $
-                  {billingState.funding.includedUsage.consumed.usd} of $
-                  {billingState.funding.includedUsage.total.usd} used
-                  {billingState.funding.includedUsage.sourcePlan?.name
-                    ? ` · ${billingState.funding.includedUsage.sourcePlan.name}`
-                    : ""}
-                </p>
+              {runway.detail ? (
+                <p className="mt-1 text-[11px] text-fg-muted">{runway.detail}</p>
+              ) : null}
+              {limitNote ? (
+                <p className="mt-1 text-[11px] text-fg-muted">{limitNote}</p>
               ) : null}
             </div>
             <div>
               <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
-                Prepaid credits
+                Usage this period
               </p>
               <p className="mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] text-fg">
-                ${balanceUsd}
+                ${usageUsd}
               </p>
             </div>
-            {meter ? (
-              <div>
-                <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
-                  Spending buffer
-                </p>
-                <p className="mt-1 font-mono text-[20px] font-medium tabular-nums tracking-[-0.01em] text-fg sm:text-[28px]">
-                  {meter.primary}
-                </p>
-                <div
-                  className="mt-1.5 h-1 w-full overflow-hidden rounded-full bg-white/5"
-                  role="progressbar"
-                  aria-label="Spending buffer used"
-                  aria-valuemin={0}
-                  aria-valuemax={100}
-                  aria-valuenow={meter.percent}
-                >
-                  <div
-                    className={`h-full rounded-full ${METER_TONE_CLASS[posture.tone]}`}
-                    style={{ width: `${meter.percent}%` }}
-                  />
-                </div>
-                <p className="mt-1 text-[11px] text-fg-muted">{meter.status}</p>
-              </div>
-            ) : (
-              <div>
-                <p className="font-mono text-[10.5px] font-medium uppercase tracking-[0.06em] text-fg-faint">
-                  Usage this period
-                </p>
-                <p className="mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] text-fg">
-                  ${usageUsd}
-                </p>
-              </div>
-            )}
           </div>
           <p className="mt-3 text-[12px] text-fg-muted">
             {collectionSchedule(billingState)}
diff --git a/components/dashboard/settings/BillingSection.tsx b/components/dashboard/settings/BillingSection.tsx
index 61c6db5..0ced4e6 100644
--- a/components/dashboard/settings/BillingSection.tsx
+++ b/components/dashboard/settings/BillingSection.tsx
@@ -31,23 +31,31 @@ import type {
 } from "@/lib/dashboard/pymthouse-billing-bff";
 import {
   billingPlanActionLabel,
+  canCancelBillingSubscription,
   defaultCancelTimingChoice,
   deriveBillingPlanAction,
   deriveBillingSubscriptionUiState,
+  formatBillingPlanPrice,
   formatPendingCancelDate,
   isActiveSubscriptionConflict,
   isNothingToResumeError,
+  paidCatalogPlanIds,
   resolveApplicablePendingCancel,
   resolveCancelingEffectiveAt,
   resolveCancelingPlanName,
   resolveTimingPayload,
+  includedUsageFeatureLabel,
   toDateInputValue,
+  withCurrentPlanInDisplayList,
   type BillingPlanAction,
   type SubscriptionTimingChoice,
   type SubscriptionTimingOptions,
 } from "@/lib/dashboard/billing-subscription-state";
 
-function isUsagePlan(plan: Pick<DashboardBillingPlan, "type">): boolean {
+function isUsagePlan(
+  plan: Pick<DashboardBillingPlan, "type" | "isStarterDefault">
+): boolean {
+  if (plan.isStarterDefault) return false;
   return plan.type.trim().toLowerCase() === "usage";
 }
 
@@ -60,31 +68,6 @@ function resolvedPayPerUseBehavior(plan: DashboardBillingPlan): string {
   return "Pay-per-use — usage draws down prepaid credits first, then is invoiced automatically as it accrues.";
 }
 
-function formatPlanPrice(
-  plan: Pick<DashboardBillingPlan, "type" | "priceAmount" | "priceCurrency" | "billingCycle">
-): { price: string; priceSub: string } {
-  const n = Number(plan.priceAmount);
-  const money = Number.isFinite(n)
-    ? new Intl.NumberFormat("en-US", {
-        style: "currency",
-        currency: plan.priceCurrency || "USD",
-        maximumFractionDigits: n % 1 === 0 ? 0 : 2,
-      }).format(n)
-    : plan.priceAmount;
-
-  if (plan.type.trim().toLowerCase() === "usage") {
-    return { price: money, priceSub: " · pay as you go" };
-  }
-
-  const c = plan.billingCycle?.toLowerCase() ?? "";
-  if (c === "monthly" || c === "month")
-    return { price: money, priceSub: " / month" };
-  if (c === "yearly" || c === "year" || c === "annual") {
-    return { price: money, priceSub: " / year" };
-  }
-  return { price: money, priceSub: plan.billingCycle ? ` · ${plan.billingCycle}` : "" };
-}
-
 function formatInvoiceAmount(totalAmount: string, currency: string): string {
   const n = Number(totalAmount);
   if (!Number.isFinite(n)) return `${totalAmount} ${currency}`;
@@ -113,11 +96,26 @@ function readCheckoutFlash(): "success" | "cancel" | null {
   return null;
 }
 
+/** Plan id to finish switching after setup-mode Checkout returns. */
+function readResumePlanChange(): string | null {
+  if (typeof window === "undefined") return null;
+  const value = new URLSearchParams(window.location.search)
+    .get("changePlan")
+    ?.trim();
+  return value || null;
+}
+
 function clearCheckoutQueryParam(): void {
   if (typeof window === "undefined") return;
   const url = new URL(window.location.href);
-  if (!url.searchParams.has("checkout")) return;
-  url.searchParams.delete("checkout");
+  let changed = false;
+  for (const key of ["checkout", "changePlan"] as const) {
+    if (url.searchParams.has(key)) {
+      url.searchParams.delete(key);
+      changed = true;
+    }
+  }
+  if (!changed) return;
   window.history.replaceState(
     {},
     "",
@@ -125,6 +123,18 @@ function clearCheckoutQueryParam(): void {
   );
 }
 
+function billingChangePlanSuccessUrl(planId: string): string {
+  const url = new URL("/settings", window.location.origin);
+  url.searchParams.set("tab", "billing");
+  url.searchParams.set("checkout", "success");
+  url.searchParams.set("changePlan", planId);
+  return url.toString();
+}
+
+function billingChangePlanCancelUrl(): string {
+  return `${window.location.origin}/settings?tab=billing&checkout=cancel`;
+}
+
 function TimingChoicePanel(props: {
   title: string;
   description: string;
@@ -147,6 +157,11 @@ function TimingChoicePanel(props: {
       <div className="mt-4 space-y-2">
         {(
           [
+            {
+              id: "immediate" as const,
+              label: "Immediately",
+              hint: "Takes effect right away",
+            },
             {
               id: "next_billing_cycle" as const,
               label: "End of current period",
@@ -154,11 +169,6 @@ function TimingChoicePanel(props: {
                 ? formatPendingCancelDate(props.options.maxEffectiveAt)
                 : "Keep access until the period ends",
             },
-            {
-              id: "immediate" as const,
-              label: "Immediately",
-              hint: "Takes effect right away",
-            },
             {
               id: "custom" as const,
               label: "Pick a date",
@@ -269,8 +279,12 @@ export default function BillingSection() {
 
   useEffect(() => {
     const next = readCheckoutFlash();
-    if (!next) return;
-    setFlash(next);
+    const resumePlanId = readResumePlanChange();
+    if (!next && !resumePlanId) return;
+    // Wait for auth before consuming a resume intent from the return URL.
+    if (resumePlanId && !externalUserId) return;
+
+    if (next) setFlash(next);
     clearCheckoutQueryParam();
     if (next === "success") {
       void (async () => {
@@ -281,10 +295,26 @@ export default function BillingSection() {
             // Webhook may already have promoted; list/UI still refreshes.
           }
         }
+        if (resumePlanId && externalUserId) {
+          setBusyPlanId(resumePlanId);
+          try {
+            await runChangePlan(resumePlanId);
+          } catch (err) {
+            setError(
+              err instanceof Error
+                ? err.message
+                : "Could not finish plan change after adding a card"
+            );
+          } finally {
+            setBusyPlanId(null);
+          }
+          return;
+        }
         void reloadPlans();
         void reloadAccount();
       })();
     }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- resume once from return URL
   }, [
     externalUserId,
     ensureDefaultPaymentMethod,
@@ -328,8 +358,8 @@ export default function BillingSection() {
     const result = await changePlan({
       planId,
       externalUserId,
-      successUrl: `${window.location.origin}/settings?tab=billing&checkout=success`,
-      cancelUrl: `${window.location.origin}/settings?tab=billing&checkout=cancel`,
+      successUrl: billingChangePlanSuccessUrl(planId),
+      cancelUrl: billingChangePlanCancelUrl(),
       ...timing,
     });
     if (result.checkoutUrl) {
@@ -377,8 +407,12 @@ export default function BillingSection() {
             ? (subscriptionUiState.planId ?? planId)
             : planId,
         externalUserId,
-        successUrl: `${window.location.origin}/settings?tab=billing&checkout=success`,
-        cancelUrl: `${window.location.origin}/settings?tab=billing&checkout=cancel`,
+        successUrl: billingChangePlanSuccessUrl(
+          action === "retry_checkout"
+            ? (subscriptionUiState.planId ?? planId)
+            : planId
+        ),
+        cancelUrl: billingChangePlanCancelUrl(),
       };
       const result = await subscribe(input);
 
@@ -591,13 +625,21 @@ export default function BillingSection() {
   const accountLoading =
     accountState.status === "loading" || accountState.status === "idle";
 
-  const plans = plansState.status === "ready" ? plansState.plans : [];
+  const catalogPlans = plansState.status === "ready" ? plansState.plans : [];
   const subscription =
     plansState.status === "ready" ? plansState.subscription : null;
+  const plans = withCurrentPlanInDisplayList(
+    catalogPlans,
+    subscription
+  ) as DashboardBillingPlan[];
   const subscriptionUiState = deriveBillingSubscriptionUiState(subscription);
   const paymentMethods =
     accountState.status === "ready" ? accountState.paymentMethods : [];
   const invoices = accountState.status === "ready" ? accountState.invoices : [];
+  const paymentMethodsError =
+    accountState.status === "ready" ? accountState.paymentMethodsError : null;
+  const invoicesError =
+    accountState.status === "ready" ? accountState.invoicesError : null;
 
   const cancelingPlanName = resolveCancelingPlanName(subscription);
   const cancelingEndsAt = resolveCancelingEffectiveAt(subscription);
@@ -613,8 +655,12 @@ export default function BillingSection() {
             ? "Current subscription"
             : "Choose a plan to get started");
 
-  const canCancel =
-    Boolean(externalUserId) && subscriptionUiState.kind === "active";
+  // Starter is the floor — cancel is only for paid catalog plans.
+  const canCancel = canCancelBillingSubscription(
+    subscriptionUiState,
+    paidCatalogPlanIds(catalogPlans),
+    Boolean(externalUserId)
+  );
   const canResume =
     Boolean(externalUserId) &&
     Boolean(resolveApplicablePendingCancel(subscription));
@@ -727,17 +773,33 @@ export default function BillingSection() {
               const isPending =
                 subscriptionUiState.kind === "pending" &&
                 subscriptionUiState.planId === plan.id;
-              const { price, priceSub } = formatPlanPrice(plan);
-              const features = [
-                isUsagePlan(plan)
-                  ? resolvedPayPerUseBehavior(plan)
-                  : plan.billingCycle
-                    ? `${plan.billingCycle} billing`
-                    : "Usage-based billing",
+              const { price, priceSub } = formatBillingPlanPrice(plan);
+              const isStarter =
+                plan.isStarterDefault === true ||
+                plan.type.trim().toLowerCase() === "free";
+              const includedUsage = includedUsageFeatureLabel(plan);
+              const features: string[] = [];
+              if (isUsagePlan(plan)) {
+                features.push(resolvedPayPerUseBehavior(plan));
+              } else {
+                if (includedUsage) {
+                  features.push(includedUsage);
+                } else if (isStarter) {
+                  features.push("Free included usage");
+                }
+                if (!isStarter) {
+                  features.push(
+                    plan.billingCycle
+                      ? `${plan.billingCycle} billing`
+                      : "Usage-based billing",
+                  );
+                }
+              }
+              features.push(
                 plan.capabilityCount > 0
                   ? `${plan.capabilityCount} capabilities`
                   : "All included capabilities",
-              ];
+              );
               return (
                 <LivePlanCard
                   key={plan.id}
@@ -782,13 +844,13 @@ export default function BillingSection() {
           <div className="animate-pulse px-5 py-9">
             <div className="mx-auto h-5 w-40 rounded bg-white/5" />
           </div>
-        ) : accountState.status === "error" ? (
+        ) : paymentMethodsError ? (
           <div className="px-5 py-6 text-center">
             <p className="text-[13px] text-fg-muted">
               Could not load payment methods.
             </p>
             <p className="mt-1 font-mono text-[12px] text-fg-faint">
-              {accountState.message}
+              {paymentMethodsError}
             </p>
             <button
               type="button"
@@ -809,8 +871,9 @@ export default function BillingSection() {
               No payment method
             </p>
             <p className="mt-1 text-[12.5px] text-fg-faint">
-              Add a card via Stripe Checkout. Completing Checkout updates your
-              card on file even if you do not return to this page.
+              Add a card via Stripe Checkout for subscription and usage charges.
+              Completing Checkout updates your card on file even if you do not
+              return to this page.
             </p>
           </div>
         ) : (
@@ -875,13 +938,13 @@ export default function BillingSection() {
           <div className="animate-pulse p-5">
             <div className="h-4 w-full rounded bg-white/5" />
           </div>
-        ) : accountState.status === "error" ? (
+        ) : invoicesError ? (
           <div className="px-5 py-6 text-center">
             <p className="text-[13px] text-fg-muted">
               Could not load billing history.
             </p>
             <p className="mt-1 font-mono text-[12px] text-fg-faint">
-              {accountState.message}
+              {invoicesError}
             </p>
             <button
               type="button"
@@ -907,7 +970,15 @@ export default function BillingSection() {
               <span aria-hidden="true" />
             </div>
             {invoices.map((inv) => {
-              const isAutoTopUp = inv.invoiceType === "auto_topup";
+              const isReceiptOnly =
+                inv.invoiceType === "auto_topup" ||
+                inv.invoiceType === "payment";
+              const statusLabel =
+                inv.invoiceType === "auto_topup"
+                  ? "Top-up"
+                  : inv.invoiceType === "payment"
+                    ? "Paid"
+                    : inv.status;
               return (
               <div
                 key={inv.id}
@@ -923,7 +994,7 @@ export default function BillingSection() {
                   {formatInvoiceAmount(inv.totalAmount, inv.currency)}
                 </div>
                 <div className="text-[12px] capitalize text-fg-faint">
-                  {isAutoTopUp ? "Top-up" : inv.status}
+                  {statusLabel}
                 </div>
                 <div className="flex justify-end gap-3">
                   <button
@@ -932,9 +1003,9 @@ export default function BillingSection() {
                     disabled={invoiceBusyId === inv.id}
                     onClick={() => void onOpenInvoice(inv.id, "hosted")}
                   >
-                    {isAutoTopUp ? "Receipt" : "View"}
+                    {isReceiptOnly ? "Receipt" : "View"}
                   </button>
-                  {isAutoTopUp ? null : (
+                  {isReceiptOnly ? null : (
                   <button
                     type="button"
                     className="inline-flex items-center gap-1 text-[12px] text-fg-strong transition-colors hover:text-fg disabled:opacity-50"
@@ -1098,6 +1169,7 @@ function LivePlanCard({
           ? "Working…"
           : billingPlanActionLabel(action, {
               usagePlan: isUsagePlan(plan),
+              starterPlan: plan.isStarterDefault === true,
             })}
         {action !== "current" && !busy ? (
           <ArrowRight className="h-2.5 w-2.5" aria-hidden="true" />
diff --git a/lib/dashboard/billing-subscription-state.test.ts b/lib/dashboard/billing-subscription-state.test.ts
index 4f1cab2..cfb7d9d 100644
--- a/lib/dashboard/billing-subscription-state.test.ts
+++ b/lib/dashboard/billing-subscription-state.test.ts
@@ -3,13 +3,20 @@ import test from "node:test";
 import {
   dateInputToEffectiveAtIso,
   defaultCancelTimingChoice,
+  canCancelBillingSubscription,
   deriveBillingPlanAction,
   deriveBillingSubscriptionUiState,
+  formatBillingPlanPrice,
+  formatIncludedUsdMicros,
   formatPendingCancelDate,
   isNothingToResumeError,
+  paidCatalogPlanIds,
   resolveApplicablePendingCancel,
   resolveTimingPayload,
+  includedUsageFeatureLabel,
+  starterIncludedUsageLabel,
   toDateInputValue,
+  withCurrentPlanInDisplayList,
 } from "./billing-subscription-state";
 
 test("derives no subscription as a subscribe state", () => {
@@ -30,6 +37,86 @@ test("marks the active plan current and other plans switchable", () => {
   assert.equal(deriveBillingPlanAction(state, "scale"), "change_plan");
 });
 
+test("Starter / non-catalog plans cannot be canceled — only paid catalog plans can", () => {
+  const starterActive = deriveBillingSubscriptionUiState({
+    planId: "starter",
+    status: "active",
+  });
+  assert.equal(
+    canCancelBillingSubscription(starterActive, ["pro", "scale"], true),
+    false,
+  );
+  assert.equal(
+    canCancelBillingSubscription(
+      deriveBillingSubscriptionUiState({ planId: "pro", status: "active" }),
+      ["pro", "scale"],
+      true,
+    ),
+    true,
+  );
+  assert.equal(
+    canCancelBillingSubscription(starterActive, ["pro"], false),
+    false,
+  );
+});
+
+test("withCurrentPlanInDisplayList injects Starter when missing from catalog", () => {
+  const paid = [
+    {
+      id: "pro",
+      name: "Pro",
+      type: "subscription",
+      status: "active",
+      priceAmount: "29",
+      priceCurrency: "USD",
+      billingCycle: "monthly",
+      chargeThresholdUsdMicros: null,
+      resolvedBehavior: null,
+      capabilityCount: 3,
+      isStarterDefault: false,
+    },
+  ];
+
+  const withStarter = withCurrentPlanInDisplayList(paid, {
+    planId: "starter",
+    planName: "Starter",
+  });
+  assert.equal(withStarter.length, 2);
+  assert.equal(withStarter[0]?.id, "starter");
+  assert.equal(withStarter[0]?.name, "Starter");
+  assert.equal(withStarter[0]?.type, "free");
+  assert.equal(withStarter[0]?.isStarterDefault, true);
+  assert.equal(withStarter[1]?.id, "pro");
+
+  // Already in catalog — no duplicate
+  assert.deepEqual(
+    withCurrentPlanInDisplayList(paid, { planId: "pro", planName: "Pro" }),
+    paid,
+  );
+
+  // No subscription — catalog only
+  assert.deepEqual(withCurrentPlanInDisplayList(paid, null), paid);
+
+  // Starter alone when no paid plans published
+  const starterOnly = withCurrentPlanInDisplayList([], {
+    planId: "starter",
+    planName: "Starter",
+  });
+  assert.equal(starterOnly.length, 1);
+  assert.equal(starterOnly[0]?.name, "Starter");
+});
+
+test("paidCatalogPlanIds excludes Starter defaults", () => {
+  assert.deepEqual(
+    paidCatalogPlanIds([
+      { id: "starter", isStarterDefault: true },
+      { id: "pro", isStarterDefault: false },
+      { id: "legacy" },
+    ]),
+    ["pro", "legacy"],
+  );
+});
+
 test("routes pending subscriptions to checkout retry", () => {
   const state = deriveBillingSubscriptionUiState({
     planId: "pro",
@@ -249,3 +336,41 @@ test("cancel timing helpers default to end of cycle and map date inputs", () =>
     { effectiveAt: "2026-08-15T12:00:00.000Z" },
   );
 });
+
+test("formatIncludedUsdMicros converts OpenMeter discounts.usage micros", () => {
+  assert.equal(formatIncludedUsdMicros("10000000"), "$10");
+  assert.equal(formatIncludedUsdMicros("2500000"), "$2.50");
+  assert.equal(formatIncludedUsdMicros("0"), null);
+  assert.equal(formatIncludedUsdMicros(null), null);
+  assert.equal(formatIncludedUsdMicros("not-a-number"), null);
+});
+
+test("formatBillingPlanPrice prefers Starter included usage over $0 fee", () => {
+  assert.deepEqual(
+    formatBillingPlanPrice({
+      type: "free",
+      priceAmount: "0",
+      priceCurrency: "USD",
+      billingCycle: "monthly",
+      includedUsdMicros: "10000000",
+      isStarterDefault: true,
+    }),
+    { price: "$10", priceSub: " · included" },
+  );
+  assert.equal(
+    includedUsageFeatureLabel({ includedUsdMicros: "10000000" }),
+    "$10 included usage",
+  );
+  assert.equal(
+    includedUsageFeatureLabel({ includedUsdMicros: null }),
+    null,
+  );
+  assert.equal(
+    starterIncludedUsageLabel({ includedUsdMicros: "10000000" }),
+    "$10 included usage",
+  );
+  assert.equal(
+    starterIncludedUsageLabel({ includedUsdMicros: null }),
+    "Free included usage",
+  );
+});
diff --git a/lib/dashboard/billing-subscription-state.ts b/lib/dashboard/billing-subscription-state.ts
index babb948..a61d1c1 100644
--- a/lib/dashboard/billing-subscription-state.ts
+++ b/lib/dashboard/billing-subscription-state.ts
@@ -122,18 +122,188 @@ export function deriveBillingPlanAction(
   return subscription.planId === planId ? "current" : "change_plan";
 }
 
+/**
+ * Cancel only applies to paid catalog plans — Starter is the floor and cannot
+ * be unsubscribed.
+ */
+export function canCancelBillingSubscription(
+  subscription: BillingSubscriptionUiState,
+  paidCatalogPlanIds: ReadonlyArray<string>,
+  hasExternalUserId: boolean
+): boolean {
+  return (
+    hasExternalUserId &&
+    subscription.kind === "active" &&
+    paidCatalogPlanIds.includes(subscription.planId)
+  );
+}
+
+export type BillingPlanDisplaySeed = {
+  id: string;
+  name: string;
+  type: string;
+  status: string;
+  priceAmount: string;
+  priceCurrency: string;
+  billingCycle: string | null;
+  includedUsdMicros?: string | null;
+  chargeThresholdUsdMicros: string | null;
+  resolvedBehavior: string | null;
+  capabilityCount: number;
+  isStarterDefault?: boolean;
+};
+
+/** Format plan included-usage micros (discounts.usage) as a USD money string. */
+export function formatIncludedUsdMicros(
+  micros: string | null | undefined,
+  currency = "USD"
+): string | null {
+  const trimmed = micros?.trim();
+  if (!trimmed || !/^\d+$/.test(trimmed)) return null;
+  let usd: number;
+  try {
+    usd = Number(BigInt(trimmed)) / 1_000_000;
+  } catch {
+    return null;
+  }
+  if (!Number.isFinite(usd) || usd <= 0) return null;
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: currency || "USD",
+    maximumFractionDigits: usd % 1 === 0 ? 0 : 2,
+  }).format(usd);
+}
+
+/**
+ * Starter is priced $0 but the headline value is the included-usage discount
+ * from OpenMeter (`allowance.includedUsdMicros`), not the subscription fee.
+ */
+export function formatBillingPlanPrice(plan: {
+  type: string;
+  priceAmount: string;
+  priceCurrency: string;
+  billingCycle: string | null;
+  includedUsdMicros?: string | null;
+  isStarterDefault?: boolean;
+}): { price: string; priceSub: string } {
+  const isStarter =
+    plan.isStarterDefault === true ||
+    plan.type.trim().toLowerCase() === "free";
+  const includedMoney = isStarter
+    ? formatIncludedUsdMicros(plan.includedUsdMicros, plan.priceCurrency)
+    : null;
+
+  if (isStarter) {
+    return {
+      price: includedMoney ?? formatPriceAmount(plan.priceAmount, plan.priceCurrency),
+      priceSub: " · included",
+    };
+  }
+
+  const money = formatPriceAmount(plan.priceAmount, plan.priceCurrency);
+  if (plan.type.trim().toLowerCase() === "usage") {
+    return { price: money, priceSub: " · pay as you go" };
+  }
+
+  const c = plan.billingCycle?.toLowerCase() ?? "";
+  if (c === "monthly" || c === "month") {
+    return { price: money, priceSub: " / month" };
+  }
+  if (c === "yearly" || c === "year" || c === "annual") {
+    return { price: money, priceSub: " / year" };
+  }
+  return {
+    price: money,
+    priceSub: plan.billingCycle ? ` · ${plan.billingCycle}` : "",
+  };
+}
+
+/**
+ * Feature-line label for plans that grant included usage via OpenMeter
+ * `allowance.includedUsdMicros` (Starter and paid plans alike).
+ */
+export function includedUsageFeatureLabel(plan: {
+  includedUsdMicros?: string | null;
+  priceCurrency?: string;
+}): string | null {
+  const money = formatIncludedUsdMicros(
+    plan.includedUsdMicros,
+    plan.priceCurrency || "USD"
+  );
+  return money ? `${money} included usage` : null;
+}
+
+/** @deprecated Prefer {@link includedUsageFeatureLabel}; kept for Starter fallback copy. */
+export function starterIncludedUsageLabel(plan: {
+  includedUsdMicros?: string | null;
+  priceCurrency?: string;
+}): string {
+  return includedUsageFeatureLabel(plan) ?? "Free included usage";
+}
+
+function formatPriceAmount(amount: string, currency: string): string {
+  const n = Number(amount);
+  if (!Number.isFinite(n)) return amount;
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: currency || "USD",
+    maximumFractionDigits: n % 1 === 0 ? 0 : 2,
+  }).format(n);
+}
+
+/**
+ * Ensure the user's current plan appears in the grid even when it is missing
+ * from the catalog response (legacy / race). Prefer including Starter via the
+ * plans API (`isStarterDefault`) so upgrades and downgrades both show.
+ */
+export function withCurrentPlanInDisplayList(
+  catalogPlans: ReadonlyArray<BillingPlanDisplaySeed>,
+  subscription: { planId: string | null; planName: string | null } | null
+): BillingPlanDisplaySeed[] {
+  const planId = subscription?.planId?.trim() || null;
+  if (!planId) return [...catalogPlans];
+  if (catalogPlans.some((p) => p.id === planId)) return [...catalogPlans];
+
+  return [
+    {
+      id: planId,
+      name: subscription?.planName?.trim() || "Starter",
+      type: "free",
+      status: "active",
+      priceAmount: "0",
+      priceCurrency: "USD",
+      billingCycle: null,
+      includedUsdMicros: null,
+      chargeThresholdUsdMicros: null,
+      resolvedBehavior: null,
+      capabilityCount: 0,
+      isStarterDefault: true,
+    },
+    ...catalogPlans,
+  ];
+}
+
+/** Paid (non-Starter) plan ids — used to gate Cancel subscription. */
+export function paidCatalogPlanIds(
+  plans: ReadonlyArray<{ id: string; isStarterDefault?: boolean }>
+): string[] {
+  return plans.filter((p) => !p.isStarterDefault).map((p) => p.id);
+}
+
 export function billingPlanActionLabel(
   action: BillingPlanAction,
-  opts?: { usagePlan?: boolean },
+  opts?: { usagePlan?: boolean; starterPlan?: boolean },
 ): string {
   switch (action) {
     case "current":
       return "Current plan";
     case "change_plan":
+      if (opts?.starterPlan) return "Switch to Starter";
       return opts?.usagePlan ? "Enable pay-per-use" : "Switch";
     case "retry_checkout":
       return "Complete payment";
     case "subscribe":
+      if (opts?.starterPlan) return "Choose Starter";
       return opts?.usagePlan ? "Enable pay-per-use" : "Subscribe";
   }
 }
diff --git a/lib/dashboard/pymthouse-billing-bff.ts b/lib/dashboard/pymthouse-billing-bff.ts
index 3664521..a88705a 100644
--- a/lib/dashboard/pymthouse-billing-bff.ts
+++ b/lib/dashboard/pymthouse-billing-bff.ts
@@ -88,9 +88,13 @@ export type DashboardBillingPlan = {
   priceAmount: string;
   priceCurrency: string;
   billingCycle: string | null;
+  /** Plan rate-card discounts.usage allowance (USD micros), when set. */
+  includedUsdMicros: string | null;
   chargeThresholdUsdMicros: string | null;
   resolvedBehavior: string | null;
   capabilityCount: number;
+  /** App Starter default — shown for upgrade/downgrade, not cancelable. */
+  isStarterDefault: boolean;
 };
 
 function readOptionalString(value: unknown): string | null {
@@ -106,34 +110,48 @@ function mapProduct(product: BillingProduct): DashboardBillingPlan {
     chargeThresholdUsdMicros?: unknown;
     resolvedBehavior?: unknown;
   };
+  const isStarterDefault = product.isStarterDefault === true;
+  const name = isStarterDefault
+    ? "Starter"
+    : product.name?.trim() || product.id;
 
   return {
     id: product.id,
-    name: product.name,
-    type: product.type,
+    name,
+    // Starter is stored as type=usage upstream but is the free floor plan —
+    // surface it as free so the UI does not treat Switch as pay-per-use.
+    type: isStarterDefault ? "free" : product.type,
     status: product.status,
     priceAmount: product.priceAmount,
     priceCurrency: product.priceCurrency,
     billingCycle: product.allowance?.billingCycle ?? null,
-    chargeThresholdUsdMicros: readOptionalString(
-      dynamicProduct.chargeThresholdUsdMicros
+    includedUsdMicros: readOptionalString(
+      product.allowance?.includedUsdMicros,
     ),
-    resolvedBehavior: readOptionalString(dynamicProduct.resolvedBehavior),
+    chargeThresholdUsdMicros: isStarterDefault
+      ? null
+      : readOptionalString(dynamicProduct.chargeThresholdUsdMicros),
+    resolvedBehavior: isStarterDefault
+      ? null
+      : readOptionalString(dynamicProduct.resolvedBehavior),
     capabilityCount: product.capabilities?.length ?? 0,
+    isStarterDefault,
   };
 }
 
-/** Active (non-starter / non-network-default) products available for subscribe. */
+/**
+ * Active products for the billing catalog: paid plans + Starter (for
+ * upgrade/downgrade). Network-default (platform) products stay hidden.
+ */
 export async function listDashboardBillingPlans(): Promise<
   DashboardBillingPlan[]
 > {
   const client = createPmtHouseClientForPublicApp(readPublicClientId());
   const { products } = await client.listBillingProducts();
   const plans = (products ?? [])
-    .filter(
-      (p) => p.status === "active" && !p.isNetworkDefault && !p.isStarterDefault
-    )
-    .map(mapProduct);
+    .filter((p) => p.status === "active" && !p.isNetworkDefault)
+    .map(mapProduct)
+    .sort((a, b) => Number(b.isStarterDefault) - Number(a.isStarterDefault));
 
   // The apiVersion=2 billing-product shape omits chargeThresholdUsdMicros /
   // resolvedBehavior (pymthouse toBillingProduct). The owner wallet summary
diff --git a/lib/dashboard/useBillingAccount.test.ts b/lib/dashboard/useBillingAccount.test.ts
new file mode 100644
index 0000000..5348c54
--- /dev/null
+++ b/lib/dashboard/useBillingAccount.test.ts
@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { isSoftBillingListUnavailable } from "./useBillingAccount";
+
+test("503 Billing unavailable is a soft empty list, not a hard UI failure", () => {
+  assert.equal(isSoftBillingListUnavailable(503, "Billing unavailable"), true);
+  assert.equal(isSoftBillingListUnavailable(503, undefined), true);
+  assert.equal(isSoftBillingListUnavailable(503, "  Billing unavailable  "), true);
+});
+
+test("other statuses and messages remain hard failures", () => {
+  assert.equal(isSoftBillingListUnavailable(500, "Billing unavailable"), false);
+  assert.equal(isSoftBillingListUnavailable(502, "upstream timeout"), false);
+  assert.equal(isSoftBillingListUnavailable(404, "not found"), false);
+  assert.equal(isSoftBillingListUnavailable(503, "rate limited"), false);
+});
diff --git a/lib/dashboard/useBillingAccount.ts b/lib/dashboard/useBillingAccount.ts
index bbf907a..2a7b3f9 100644
--- a/lib/dashboard/useBillingAccount.ts
+++ b/lib/dashboard/useBillingAccount.ts
@@ -34,6 +34,20 @@ function billingUpstreamMessage(
   return upstreamError ?? `${surface} failed (${status})`;
 }
 
+/**
+ * List endpoints may answer 503 "Billing unavailable" for expected empty
+ * conditions (no Stripe customer yet, sandbox Connect not ready, OM admin
+ * client offline). Those are empty states, not hard UI failures.
+ */
+export function isSoftBillingListUnavailable(
+  status: number,
+  upstreamError?: string,
+): boolean {
+  if (status !== 503) return false;
+  const msg = upstreamError?.trim().toLowerCase() ?? "";
+  return !msg || msg === "billing unavailable";
+}
+
 export type BillingAccountState =
   | { status: "idle" }
   | { status: "loading" }
@@ -41,8 +55,77 @@ export type BillingAccountState =
       status: "ready";
       paymentMethods: DashboardPaymentMethod[];
       invoices: DashboardInvoice[];
+      paymentMethodsError: string | null;
+      invoicesError: string | null;
+    };
+
+type ListLoadResult<T> = {
+  items: T[];
+  error: string | null;
+};
+
+async function loadPaymentMethods(
+  externalUserId: string,
+): Promise<ListLoadResult<DashboardPaymentMethod>> {
+  try {
+    const response = await fetch(
+      `/api/pymthouse/payment-methods?externalUserId=${encodeURIComponent(externalUserId)}`,
+    );
+    const body = await readResponseJson<{
+      paymentMethods?: DashboardPaymentMethod[];
+      error?: string;
+    }>(response);
+    if (!response.ok) {
+      if (isSoftBillingListUnavailable(response.status, body.error)) {
+        return { items: [], error: null };
+      }
+      return {
+        items: [],
+        error: billingUpstreamMessage(
+          "payment methods",
+          response.status,
+          body.error,
+        ),
+      };
+    }
+    return { items: body.paymentMethods ?? [], error: null };
+  } catch (error) {
+    return {
+      items: [],
+      error:
+        error instanceof Error ? error.message : "Failed to load payment methods",
+    };
+  }
+}
+
+async function loadInvoices(
+  externalUserId: string,
+): Promise<ListLoadResult<DashboardInvoice>> {
+  try {
+    const response = await fetch(
+      `/api/pymthouse/invoices?externalUserId=${encodeURIComponent(externalUserId)}&pageSize=20`,
+    );
+    const body = await readResponseJson<{
+      items?: DashboardInvoice[];
+      error?: string;
+    }>(response);
+    if (!response.ok) {
+      if (isSoftBillingListUnavailable(response.status, body.error)) {
+        return { items: [], error: null };
+      }
+      return {
+        items: [],
+        error: billingUpstreamMessage("invoices", response.status, body.error),
+      };
     }
-  | { status: "error"; message: string };
+    return { items: body.items ?? [], error: null };
+  } catch (error) {
+    return {
+      items: [],
+      error: error instanceof Error ? error.message : "Failed to load invoices",
+    };
+  }
+}
 
 export function useBillingAccount(externalUserId: string | undefined) {
   const [state, setState] = useState<BillingAccountState>({ status: "idle" });
@@ -54,60 +137,25 @@ export function useBillingAccount(externalUserId: string | undefined) {
         status: "ready",
         paymentMethods: [],
         invoices: [],
+        paymentMethodsError: null,
+        invoicesError: null,
       });
       return;
     }
 
     setState({ status: "loading" });
-    try {
-      const q = encodeURIComponent(trimmed);
-      const [pmResponse, invResponse] = await Promise.all([
-        fetch(`/api/pymthouse/payment-methods?externalUserId=${q}`),
-        fetch(`/api/pymthouse/invoices?externalUserId=${q}&pageSize=20`),
-      ]);
-
-      const pmBody = await readResponseJson<{
-        paymentMethods?: DashboardPaymentMethod[];
-        error?: string;
-        code?: string;
-      }>(pmResponse);
-      if (!pmResponse.ok) {
-        throw new Error(
-          billingUpstreamMessage(
-            "payment methods",
-            pmResponse.status,
-            pmBody.error,
-          ),
-        );
-      }
-
-      const invBody = await readResponseJson<{
-        items?: DashboardInvoice[];
-        error?: string;
-        code?: string;
-      }>(invResponse);
-      if (!invResponse.ok) {
-        throw new Error(
-          billingUpstreamMessage(
-            "invoices",
-            invResponse.status,
-            invBody.error,
-          ),
-        );
-      }
-
-      setState({
-        status: "ready",
-        paymentMethods: pmBody.paymentMethods ?? [],
-        invoices: invBody.items ?? [],
-      });
-    } catch (error) {
-      setState({
-        status: "error",
-        message:
-          error instanceof Error ? error.message : "Failed to load billing",
-      });
-    }
+    // Independent loads — invoice soft-503 must not poison payment methods UI.
+    const [pm, inv] = await Promise.all([
+      loadPaymentMethods(trimmed),
+      loadInvoices(trimmed),
+    ]);
+    setState({
+      status: "ready",
+      paymentMethods: pm.items,
+      invoices: inv.items,
+      paymentMethodsError: pm.error,
+      invoicesError: inv.error,
+    });
   }, [externalUserId]);
 
   useEffect(() => {
diff --git a/lib/dashboard/wallet-settlement-display.test.ts b/lib/dashboard/wallet-settlement-display.test.ts
index 7c28269..0e07f6a 100644
--- a/lib/dashboard/wallet-settlement-display.test.ts
+++ b/lib/dashboard/wallet-settlement-display.test.ts
@@ -3,10 +3,11 @@ import { describe, it } from "node:test";
 
 import type { BillingState } from "@pymthouse/builder-sdk";
 import {
+  availableRunway,
   collectionSchedule,
-  overageBufferMeter,
+  overageLimitNote,
   spendPostureBadge,
-} from "@/lib/dashboard/wallet-settlement-display";
+} from "./wallet-settlement-display";
 
 function money(usdMicros: string, usd: string) {
   return { usdMicros, usd, currency: "USD" };
@@ -14,6 +15,8 @@ function money(usdMicros: string, usd: string) {
 
 function makeState(overrides: {
   status?: BillingState["status"];
+  includedRemaining?: { usdMicros: string; usd: string };
+  prepaid?: { usdMicros: string; usd: string };
   ceiling?: { usdMicros: string; usd: string };
   unbilledDebt?: { usdMicros: string; usd: string } | null;
   remaining?: { usdMicros: string; usd: string } | null;
@@ -31,11 +34,17 @@ function makeState(overrides: {
     canSpend: true,
     reason: null,
     funding: {
-      prepaid: money("0", "0.00"),
+      prepaid: {
+        ...money("0", "0.00"),
+        ...(overrides.prepaid ?? {}),
+      },
       included: money("0", "0.00"),
       includedUsage: {
-        total: money("0", "0.00"),
-        remaining: money("0", "0.00"),
+        total: money("10000000", "10.00"),
+        remaining: {
+          ...money("0", "0.00"),
+          ...(overrides.includedRemaining ?? {}),
+        },
         consumed: money("0", "0.00"),
         resetsAt: "2026-09-01T00:00:00.000Z",
         sourcePlan: null,
@@ -99,42 +108,105 @@ describe("spendPostureBadge", () => {
   });
 });
 
-describe("overageBufferMeter", () => {
-  it("reports debt against the ceiling with remaining headroom", () => {
-    const meter = overageBufferMeter(makeState({}));
-    assert.equal(meter?.primary, "$0.50 / $2.00");
-    assert.equal(meter?.status, "$1.50 of buffer left");
-    assert.equal(meter?.percent, 25);
+describe("availableRunway", () => {
+  it("sums included and prepaid when funded", () => {
+    const runway = availableRunway(
+      makeState({
+        status: "active",
+        includedRemaining: { usdMicros: "8000000", usd: "8.00" },
+        prepaid: { usdMicros: "2500000", usd: "2.50" },
+        unbilledDebt: null,
+      }),
+    );
+    assert.equal(runway.usd, "$10.50");
+    assert.equal(runway.usdMicros, "10500000");
+    assert.equal(runway.tone, "ok");
+    assert.equal(runway.detail, "Included $8.00 · Credits $2.50");
+  });
+
+  it("omits zero sides from the funded breakdown", () => {
+    const runway = availableRunway(
+      makeState({
+        status: "active",
+        includedRemaining: { usdMicros: "5000000", usd: "5.00" },
+        prepaid: { usdMicros: "0", usd: "0.00" },
+        unbilledDebt: null,
+      }),
+    );
+    assert.equal(runway.usd, "$5.00");
+    assert.equal(runway.detail, "Included $5.00");
+  });
+
+  it("goes negative once unbilled debt exceeds funding", () => {
+    const runway = availableRunway(
+      makeState({
+        status: "overage",
+        includedRemaining: { usdMicros: "0", usd: "0.00" },
+        prepaid: { usdMicros: "0", usd: "0.00" },
+        unbilledDebt: { usdMicros: "1250000", usd: "1.25" },
+      }),
+    );
+    assert.equal(runway.usd, "-$1.25");
+    assert.equal(runway.usdMicros, "-1250000");
+    assert.equal(runway.tone, "info");
+    assert.equal(runway.detail, "Unbilled $1.25");
+  });
+
+  it("treats null debt as zero", () => {
+    const runway = availableRunway(
+      makeState({
+        status: "active",
+        includedRemaining: { usdMicros: "1000000", usd: "1.00" },
+        unbilledDebt: null,
+      }),
+    );
+    assert.equal(runway.usd, "$1.00");
   });
 
-  it("says the buffer is used up when blocked", () => {
-    const meter = overageBufferMeter(
+  it("uses danger tone when blocked below zero", () => {
+    const runway = availableRunway(
       makeState({
         status: "blocked",
+        includedRemaining: { usdMicros: "0", usd: "0.00" },
         unbilledDebt: { usdMicros: "2000000", usd: "2.00" },
-        remaining: { usdMicros: "0", usd: "0.00" },
-        utilizationBps: 10_000,
       }),
     );
-    assert.equal(meter?.status, "Buffer used up");
-    assert.equal(meter?.percent, 100);
+    assert.equal(runway.usd, "-$2.00");
+    assert.equal(runway.tone, "danger");
   });
+});
 
-  it("clamps utilization above the ceiling to a full bar", () => {
-    const meter = overageBufferMeter(makeState({ utilizationBps: 14_000 }));
-    assert.equal(meter?.percent, 100);
+describe("overageLimitNote", () => {
+  it("shows ceiling and remaining headroom while spendable", () => {
+    const note = overageLimitNote(makeState({}));
+    assert.equal(note, "Overage limit $2.00 · $1.50 left");
   });
 
-  it("hides the meter when there is no ceiling", () => {
-    const meter = overageBufferMeter(
-      makeState({ ceiling: { usdMicros: "0", usd: "0.00" } }),
+  it("drops headroom when remaining is zero but not blocked", () => {
+    const note = overageLimitNote(
+      makeState({
+        remaining: { usdMicros: "0", usd: "0.00" },
+      }),
+    );
+    assert.equal(note, "Overage limit $2.00");
+  });
+
+  it("says the limit is reached when blocked", () => {
+    const note = overageLimitNote(
+      makeState({
+        status: "blocked",
+        unbilledDebt: { usdMicros: "2000000", usd: "2.00" },
+        remaining: { usdMicros: "0", usd: "0.00" },
+      }),
     );
-    assert.equal(meter, null);
+    assert.equal(note, "Overage limit reached");
   });
 
-  it("hides the meter when debt could not be read", () => {
-    const meter = overageBufferMeter(makeState({ unbilledDebt: null }));
-    assert.equal(meter, null);
+  it("hides the note when there is no ceiling", () => {
+    const note = overageLimitNote(
+      makeState({ ceiling: { usdMicros: "0", usd: "0.00" } }),
+    );
+    assert.equal(note, null);
   });
 });
 
diff --git a/lib/dashboard/wallet-settlement-display.ts b/lib/dashboard/wallet-settlement-display.ts
index c94d3a0..a2562ba 100644
--- a/lib/dashboard/wallet-settlement-display.ts
+++ b/lib/dashboard/wallet-settlement-display.ts
@@ -1,5 +1,5 @@
 import type { BillingState, BillingStatus } from "@pymthouse/builder-sdk";
-import { microsToUsd } from "@/lib/dashboard/usage-capability-display";
+import { microsToUsd } from "./usage-capability-display";
 
 /** Wallet strip amounts: always two decimals (matches prepaid `$0.00`). */
 export function formatWalletUsd(micros: string | null | undefined): string {
@@ -7,6 +7,24 @@ export function formatWalletUsd(micros: string | null | undefined): string {
   return microsToUsd(micros).toFixed(2);
 }
 
+function parseUsdMicros(raw: string | null | undefined): bigint {
+  const trimmed = raw?.trim();
+  if (!trimmed || !/^-?\d+$/.test(trimmed)) return BigInt(0);
+  try {
+    return BigInt(trimmed);
+  } catch {
+    return BigInt(0);
+  }
+}
+
+/** Signed wallet dollars with an explicit minus (`-$1.25` / `$0.00`). */
+export function formatSignedWalletUsd(micros: bigint): string {
+  const negative = micros < BigInt(0);
+  const abs = negative ? -micros : micros;
+  const formatted = (Number(abs) / 1_000_000).toFixed(2);
+  return negative ? `-$${formatted}` : `$${formatted}`;
+}
+
 export type SpendPostureTone = "ok" | "info" | "warn" | "danger";
 
 /**
@@ -30,35 +48,71 @@ export function spendPostureBadge(status: BillingStatus): {
   }
 }
 
+export type AvailableRunway = {
+  usdMicros: string;
+  /** Display with `$` / `-$`. */
+  usd: string;
+  tone: SpendPostureTone;
+  /** Breakdown under the big number, or null when both sides are zero. */
+  detail: string | null;
+};
+
 /**
- * Buffer consumption for the progress meter. Null when there is no ceiling to
- * fill, or when debt could not be read — the meter is hidden in both cases
- * rather than drawn at a made-up value.
+ * Signed runway: included remaining + prepaid − unbilled debt.
+ * Goes negative once spend accrues against the overage ceiling.
  */
-export function overageBufferMeter(state: BillingState): {
-  primary: string;
-  status: string;
-  percent: number;
-} | null {
-  const { overage } = state.funding;
-  const debt = overage.unbilledDebt;
-  if (!debt || overage.ceiling.usdMicros === "0") return null;
-
-  const percent = Math.min(
-    100,
-    Math.max(0, Math.round((overage.utilizationBps ?? 0) / 100)),
+export function availableRunway(state: BillingState): AvailableRunway {
+  const included = parseUsdMicros(
+    state.funding.includedUsage?.remaining.usdMicros ??
+      state.funding.included.usdMicros,
   );
-  const remaining = overage.remaining?.usd ?? "0.00";
+  const prepaid = parseUsdMicros(state.funding.prepaid.usdMicros);
+  const debt = parseUsdMicros(state.funding.overage.unbilledDebt?.usdMicros);
+  const available = included + prepaid - debt;
+
+  let tone: SpendPostureTone = "ok";
+  if (available < BigInt(0)) {
+    if (state.status === "blocked") tone = "danger";
+    else if (state.status === "at_risk") tone = "warn";
+    else tone = "info";
+  }
+
+  let detail: string | null = null;
+  if (available < BigInt(0)) {
+    detail = `Unbilled $${formatWalletUsd(debt.toString())}`;
+  } else {
+    const parts: string[] = [];
+    if (included > BigInt(0)) {
+      parts.push(`Included $${formatWalletUsd(included.toString())}`);
+    }
+    if (prepaid > BigInt(0)) {
+      parts.push(`Credits $${formatWalletUsd(prepaid.toString())}`);
+    }
+    detail = parts.length > 0 ? parts.join(" · ") : null;
+  }
+
   return {
-    primary: `$${debt.usd} / $${overage.ceiling.usd}`,
-    status:
-      state.status === "blocked"
-        ? "Buffer used up"
-        : `$${remaining} of buffer left`,
-    percent,
+    usdMicros: available.toString(),
+    usd: formatSignedWalletUsd(available),
+    tone,
+    detail,
   };
 }
 
+/**
+ * Small footnote for the soft overage ceiling. Null when unlimited (ceiling 0).
+ */
+export function overageLimitNote(state: BillingState): string | null {
+  const ceiling = state.funding.overage.ceiling;
+  if (!ceiling?.usdMicros || ceiling.usdMicros === "0") return null;
+  if (state.status === "blocked") return "Overage limit reached";
+  const remaining = state.funding.overage.remaining;
+  if (remaining && remaining.usdMicros !== "0") {
+    return `Overage limit $${ceiling.usd} · $${remaining.usd} left`;
+  }
+  return `Overage limit $${ceiling.usd}`;
+}
+
 /** When the next invoice goes out, in the customer's terms. */
 export function collectionSchedule(state: BillingState): string {
   const lead = state.collection.leadThreshold;

From 27e27185ade49981ac395b4eee409134627203e9 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Mon, 10 Aug 2026 22:55:11 -0400
Subject: [PATCH 12/13] feat(subscriptions): implement user subscription
 retrieval API and enhance billing UI

- Added a new API route for retrieving user subscriptions, ensuring externalUserId is validated.
- Introduced a `TimingChoicePanel` component for selecting subscription change timing options.
- Enhanced `PlansPanel` and `BillingSection` components to support subscription timing changes and conflicts.
- Updated billing state management to include subscription history and error handling for subscription-related actions.
- Refactored existing billing functions to accommodate new subscription logic and improve user experience.
---
 app/api/pymthouse/subscriptions/route.ts      |  33 +++
 components/dashboard/PlansPanel.tsx           | 176 +++++++++++--
 components/dashboard/TimingChoicePanel.tsx    | 103 ++++++++
 .../dashboard/settings/BillingSection.tsx     | 243 ++++++++++--------
 .../billing-subscription-state.test.ts        |   4 +-
 lib/dashboard/billing-subscription-state.ts   |   2 +-
 lib/dashboard/pymthouse-billing-bff.ts        |  13 +
 lib/dashboard/useBillingAccount.ts            |  56 +++-
 8 files changed, 502 insertions(+), 128 deletions(-)
 create mode 100644 app/api/pymthouse/subscriptions/route.ts
 create mode 100644 components/dashboard/TimingChoicePanel.tsx

diff --git a/app/api/pymthouse/subscriptions/route.ts b/app/api/pymthouse/subscriptions/route.ts
new file mode 100644
index 0000000..72d16c9
--- /dev/null
+++ b/app/api/pymthouse/subscriptions/route.ts
@@ -0,0 +1,33 @@
+import { NextRequest, NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+import { listDashboardUserSubscriptions } from "@/lib/dashboard/pymthouse-billing-bff";
+
+export const runtime = "nodejs";
+
+export async function GET(request: NextRequest) {
+  const externalUserId =
+    request.nextUrl.searchParams.get("externalUserId")?.trim() || "";
+  if (!externalUserId) {
+    return NextResponse.json(
+      { error: "externalUserId is required" },
+      { status: 400 },
+    );
+  }
+
+  try {
+    const result = await listDashboardUserSubscriptions(externalUserId);
+    return NextResponse.json(result);
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status },
+      );
+    }
+    const message =
+      error instanceof Error
+        ? error.message
+        : "Failed to load subscription history";
+    return NextResponse.json({ error: message }, { status: 502 });
+  }
+}
diff --git a/components/dashboard/PlansPanel.tsx b/components/dashboard/PlansPanel.tsx
index 7c8e84b..ecc5845 100644
--- a/components/dashboard/PlansPanel.tsx
+++ b/components/dashboard/PlansPanel.tsx
@@ -2,11 +2,23 @@
 
 import { useEffect, useState } from "react";
 import Button from "@/components/design-system/Button";
-import type { DashboardBillingPlan } from "@/lib/dashboard/pymthouse-billing-bff";
+import Dialog from "@/components/design-system/Dialog";
+import TimingChoicePanel from "@/components/dashboard/TimingChoicePanel";
+import type {
+  DashboardBillingPlan,
+  DashboardScheduledChangeConflict,
+} from "@/lib/dashboard/pymthouse-billing-bff";
 import {
+  defaultCancelTimingChoice,
   formatBillingPlanPrice,
+  resolveTimingPayload,
+  toDateInputValue,
+  type SubscriptionTimingChoice,
 } from "@/lib/dashboard/billing-subscription-state";
-import { useBillingPlans } from "@/lib/dashboard/useBillingPlans";
+import {
+  ScheduledChangeConflictError,
+  useBillingPlans,
+} from "@/lib/dashboard/useBillingPlans";
 
 function isUsagePlan(
   plan: Pick<DashboardBillingPlan, "type" | "isStarterDefault">
@@ -66,6 +78,14 @@ export default function PlansPanel({
   const [busyPlanId, setBusyPlanId] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [flash, setFlash] = useState<"success" | "cancel" | null>(null);
+  const [changeDialog, setChangeDialog] = useState<{
+    planId: string;
+    conflict: DashboardScheduledChangeConflict | null;
+  } | null>(null);
+  const [changeChoice, setChangeChoice] = useState<SubscriptionTimingChoice>(
+    defaultCancelTimingChoice()
+  );
+  const [changeCustomDate, setChangeCustomDate] = useState("");
 
   useEffect(() => {
     const next = readCheckoutFlash();
@@ -109,6 +129,53 @@ export default function PlansPanel({
     // eslint-disable-next-line react-hooks/exhaustive-deps -- resume once from return URL
   }, [reload, changePlan, externalUserId]);
 
+  function openChangeTimingDialog(
+    planId: string,
+    conflict: DashboardScheduledChangeConflict | null = null
+  ) {
+    setChangeChoice(defaultCancelTimingChoice());
+    setChangeCustomDate(
+      toDateInputValue(
+        conflict?.timingOptions?.minEffectiveAt ??
+          (state.status === "ready"
+            ? state.subscription?.timingOptions?.change.minEffectiveAt
+            : undefined)
+      )
+    );
+    setChangeDialog({ planId, conflict });
+  }
+
+  async function runChangePlan(
+    planId: string,
+    timing?: {
+      timing?: string;
+      effectiveAt?: string;
+      confirmReplaceScheduled?: boolean;
+    }
+  ) {
+    if (!externalUserId?.trim()) return;
+    const userId = externalUserId.trim();
+    const result = await changePlan({
+      planId,
+      externalUserId: userId,
+      successUrl: `${window.location.origin}/usage?checkout=success&changePlan=${encodeURIComponent(planId)}`,
+      cancelUrl: `${window.location.origin}/usage?checkout=cancel`,
+      ...timing,
+    });
+    if (result.checkoutUrl) {
+      window.location.assign(result.checkoutUrl);
+      return;
+    }
+    await reload();
+    const plans = state.status === "ready" ? state.plans : [];
+    const targetPlan = plans.find((p) => p.id === planId);
+    setError(
+      targetPlan && isUsagePlan(targetPlan)
+        ? "Plan updated. Add a payment method in Settings → Billing for pay-per-use auto-debit."
+        : "Plan updated.",
+    );
+  }
+
   async function onSubscribe(planId: string) {
     if (!externalUserId?.trim()) {
       setError("Sign in to subscribe.");
@@ -133,36 +200,72 @@ export default function PlansPanel({
           activeStatus === "trialing" ||
           activeStatus === "scheduled");
 
+      if (hasActiveSubscription && targetPlan?.isStarterDefault === true) {
+        setBusyPlanId(null);
+        openChangeTimingDialog(planId);
+        return;
+      }
+
       // Starter/default users already have a subscription — switch instead of
       // create, so pay-per-use can still collect a setup Checkout card.
-      const result = hasActiveSubscription
-        ? await changePlan({
-            planId,
-            externalUserId: userId,
-            successUrl: `${window.location.origin}/usage?checkout=success&changePlan=${encodeURIComponent(planId)}`,
-            cancelUrl: `${window.location.origin}/usage?checkout=cancel`,
-          })
-        : await subscribe({
+      try {
+        if (hasActiveSubscription) {
+          await runChangePlan(planId);
+        } else {
+          const result = await subscribe({
             planId,
             externalUserId: userId,
             successUrl: `${window.location.origin}/usage?checkout=success&changePlan=${encodeURIComponent(planId)}`,
             cancelUrl: `${window.location.origin}/usage?checkout=cancel`,
           });
+          if (result.checkoutUrl) {
+            window.location.assign(result.checkoutUrl);
+            return;
+          }
+          await reload();
+          setError(
+            targetPlan && isUsagePlan(targetPlan)
+              ? "Plan updated. Add a payment method in Settings → Billing for pay-per-use auto-debit."
+              : "Plan updated.",
+          );
+        }
+      } catch (err) {
+        if (err instanceof ScheduledChangeConflictError) {
+          openChangeTimingDialog(planId, err.conflict);
+          return;
+        }
+        throw err;
+      }
+      setBusyPlanId(null);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Checkout failed");
+      setBusyPlanId(null);
+    }
+  }
 
-      if (result.checkoutUrl) {
-        window.location.assign(result.checkoutUrl);
+  async function onConfirmChangeTiming() {
+    if (!externalUserId?.trim() || !changeDialog) return;
+    setError(null);
+    setBusyPlanId(changeDialog.planId);
+    try {
+      const payload = resolveTimingPayload({
+        choice: changeChoice,
+        customDateYmd: changeCustomDate,
+      });
+      await runChangePlan(changeDialog.planId, {
+        ...payload,
+        ...(changeDialog.conflict ? { confirmReplaceScheduled: true } : {}),
+      });
+      setChangeDialog(null);
+    } catch (err) {
+      if (err instanceof ScheduledChangeConflictError) {
+        openChangeTimingDialog(changeDialog.planId, err.conflict);
         return;
       }
-
-      await reload();
       setError(
-        targetPlan && isUsagePlan(targetPlan)
-          ? "Plan updated. Add a payment method in Settings → Billing for pay-per-use auto-debit."
-          : "Plan updated.",
+        err instanceof Error ? err.message : "Could not change subscription"
       );
-      setBusyPlanId(null);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : "Checkout failed");
+    } finally {
       setBusyPlanId(null);
     }
   }
@@ -272,6 +375,39 @@ export default function PlansPanel({
       {error ? (
         <p className="border-t border-hairline px-4 py-2 text-xs text-rose-400">{error}</p>
       ) : null}
+
+      <Dialog
+        open={changeDialog !== null}
+        onClose={() => {
+          if (busyPlanId === null) setChangeDialog(null);
+        }}
+        maxWidth="max-w-[420px]"
+      >
+        <TimingChoicePanel
+          title={
+            changeDialog?.conflict
+              ? "Replace scheduled plan change?"
+              : "Switch to Starter"
+          }
+          description={
+            changeDialog?.conflict
+              ? "A plan change is already scheduled. Choosing a start time replaces that schedule with your new plan."
+              : "Choose when the switch to Starter should take effect."
+          }
+          options={
+            changeDialog?.conflict?.timingOptions ??
+            state.subscription?.timingOptions?.change
+          }
+          choice={changeChoice}
+          customDate={changeCustomDate}
+          confirmLabel="Confirm switch"
+          busy={busyPlanId !== null}
+          onChoice={setChangeChoice}
+          onCustomDate={setChangeCustomDate}
+          onConfirm={() => void onConfirmChangeTiming()}
+          onClose={() => setChangeDialog(null)}
+        />
+      </Dialog>
     </div>
   );
 }
diff --git a/components/dashboard/TimingChoicePanel.tsx b/components/dashboard/TimingChoicePanel.tsx
new file mode 100644
index 0000000..84d6b6a
--- /dev/null
+++ b/components/dashboard/TimingChoicePanel.tsx
@@ -0,0 +1,103 @@
+"use client";
+
+import {
+  formatPendingCancelDate,
+  toDateInputValue,
+  type SubscriptionTimingChoice,
+  type SubscriptionTimingOptions,
+} from "@/lib/dashboard/billing-subscription-state";
+
+export default function TimingChoicePanel(props: {
+  title: string;
+  description: string;
+  options: SubscriptionTimingOptions | null | undefined;
+  choice: SubscriptionTimingChoice;
+  customDate: string;
+  confirmLabel: string;
+  busy: boolean;
+  onChoice: (choice: SubscriptionTimingChoice) => void;
+  onCustomDate: (ymd: string) => void;
+  onConfirm: () => void;
+  onClose: () => void;
+}) {
+  const min = toDateInputValue(props.options?.minEffectiveAt);
+  const max = toDateInputValue(props.options?.maxEffectiveAt);
+  return (
+    <div className="p-5">
+      <h2 className="text-base font-semibold text-fg">{props.title}</h2>
+      <p className="mt-1 text-[13px] text-fg-muted">{props.description}</p>
+      <div className="mt-4 space-y-2">
+        {(
+          [
+            {
+              id: "immediate" as const,
+              label: "Immediately",
+              hint: "Takes effect right away",
+            },
+            {
+              id: "next_billing_cycle" as const,
+              label: "End of current period",
+              hint: props.options?.maxEffectiveAt
+                ? formatPendingCancelDate(props.options.maxEffectiveAt)
+                : "Keep access until the period ends",
+            },
+            {
+              id: "custom" as const,
+              label: "Pick a date",
+              hint: min && max ? `${min} – ${max}` : "Choose a date in range",
+            },
+          ] as const
+        ).map((opt) => (
+          <label
+            key={opt.id}
+            className="flex cursor-pointer items-start gap-3 rounded-lg border border-hairline px-3 py-2.5 hover:bg-white/[0.02]"
+          >
+            <input
+              type="radio"
+              className="mt-1"
+              name="timing-choice"
+              checked={props.choice === opt.id}
+              onChange={() => props.onChoice(opt.id)}
+            />
+            <span>
+              <span className="block text-[13px] font-medium text-fg">
+                {opt.label}
+              </span>
+              <span className="block text-[12px] text-fg-muted">{opt.hint}</span>
+            </span>
+          </label>
+        ))}
+      </div>
+      {props.choice === "custom" ? (
+        <input
+          type="date"
+          className="mt-3 w-full rounded-md border border-hairline bg-transparent px-3 py-2 text-[13px] text-fg focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-green-bright/30"
+          min={min || undefined}
+          max={max || undefined}
+          value={props.customDate}
+          onChange={(e) => props.onCustomDate(e.target.value)}
+        />
+      ) : null}
+      <div className="mt-5 flex justify-end gap-2">
+        <button
+          type="button"
+          className="rounded-md px-3 py-1.5 text-[12.5px] text-fg-muted hover:text-fg"
+          onClick={props.onClose}
+          disabled={props.busy}
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          className="rounded-md bg-green-bright px-3 py-1.5 text-[12.5px] font-medium text-black disabled:opacity-50"
+          disabled={
+            props.busy || (props.choice === "custom" && !props.customDate)
+          }
+          onClick={props.onConfirm}
+        >
+          {props.busy ? "Working…" : props.confirmLabel}
+        </button>
+      </div>
+    </div>
+  );
+}
diff --git a/components/dashboard/settings/BillingSection.tsx b/components/dashboard/settings/BillingSection.tsx
index 0ced4e6..a7e67b0 100644
--- a/components/dashboard/settings/BillingSection.tsx
+++ b/components/dashboard/settings/BillingSection.tsx
@@ -12,6 +12,7 @@ import {
 } from "lucide-react";
 import { useAuth } from "@/components/dashboard/AuthContext";
 import Dialog from "@/components/design-system/Dialog";
+import TimingChoicePanel from "@/components/dashboard/TimingChoicePanel";
 import {
   IconButton,
   SettingsCard,
@@ -49,7 +50,6 @@ import {
   withCurrentPlanInDisplayList,
   type BillingPlanAction,
   type SubscriptionTimingChoice,
-  type SubscriptionTimingOptions,
 } from "@/lib/dashboard/billing-subscription-state";
 
 function isUsagePlan(
@@ -89,6 +89,19 @@ function formatInvoiceDate(iso: string | undefined): string {
   });
 }
 
+function formatSubscriptionHistoryStatus(input: {
+  status: string;
+  current: boolean;
+}): string {
+  if (input.current) return "Current";
+  const status = input.status.trim().toLowerCase();
+  if (status === "scheduled" || status === "pending") return "Scheduled";
+  if (status === "inactive" || status === "canceled" || status === "cancelled") {
+    return "Ended";
+  }
+  return input.status || "—";
+}
+
 function readCheckoutFlash(): "success" | "cancel" | null {
   if (typeof window === "undefined") return null;
   const value = new URLSearchParams(window.location.search).get("checkout");
@@ -135,99 +148,6 @@ function billingChangePlanCancelUrl(): string {
   return `${window.location.origin}/settings?tab=billing&checkout=cancel`;
 }
 
-function TimingChoicePanel(props: {
-  title: string;
-  description: string;
-  options: SubscriptionTimingOptions | null | undefined;
-  choice: SubscriptionTimingChoice;
-  customDate: string;
-  confirmLabel: string;
-  busy: boolean;
-  onChoice: (choice: SubscriptionTimingChoice) => void;
-  onCustomDate: (ymd: string) => void;
-  onConfirm: () => void;
-  onClose: () => void;
-}) {
-  const min = toDateInputValue(props.options?.minEffectiveAt);
-  const max = toDateInputValue(props.options?.maxEffectiveAt);
-  return (
-    <div className="p-5">
-      <h2 className="text-base font-semibold text-fg">{props.title}</h2>
-      <p className="mt-1 text-[13px] text-fg-muted">{props.description}</p>
-      <div className="mt-4 space-y-2">
-        {(
-          [
-            {
-              id: "immediate" as const,
-              label: "Immediately",
-              hint: "Takes effect right away",
-            },
-            {
-              id: "next_billing_cycle" as const,
-              label: "End of current period",
-              hint: props.options?.maxEffectiveAt
-                ? formatPendingCancelDate(props.options.maxEffectiveAt)
-                : "Keep access until the period ends",
-            },
-            {
-              id: "custom" as const,
-              label: "Pick a date",
-              hint: min && max ? `${min} – ${max}` : "Choose a date in range",
-            },
-          ] as const
-        ).map((opt) => (
-          <label
-            key={opt.id}
-            className="flex cursor-pointer items-start gap-3 rounded-lg border border-hairline px-3 py-2.5 hover:bg-white/[0.02]"
-          >
-            <input
-              type="radio"
-              className="mt-1"
-              name="timing-choice"
-              checked={props.choice === opt.id}
-              onChange={() => props.onChoice(opt.id)}
-            />
-            <span>
-              <span className="block text-[13px] font-medium text-fg">
-                {opt.label}
-              </span>
-              <span className="block text-[12px] text-fg-muted">{opt.hint}</span>
-            </span>
-          </label>
-        ))}
-      </div>
-      {props.choice === "custom" ? (
-        <input
-          type="date"
-          className="mt-3 w-full rounded-md border border-hairline bg-transparent px-3 py-2 text-[13px] text-fg focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-green-bright/30"
-          min={min || undefined}
-          max={max || undefined}
-          value={props.customDate}
-          onChange={(e) => props.onCustomDate(e.target.value)}
-        />
-      ) : null}
-      <div className="mt-5 flex justify-end gap-2">
-        <button
-          type="button"
-          className="rounded-md px-3 py-1.5 text-[12.5px] text-fg-muted hover:text-fg"
-          onClick={props.onClose}
-          disabled={props.busy}
-        >
-          Cancel
-        </button>
-        <button
-          type="button"
-          className="rounded-md bg-green-bright px-3 py-1.5 text-[12.5px] font-medium text-black disabled:opacity-50"
-          disabled={props.busy || (props.choice === "custom" && !props.customDate)}
-          onClick={props.onConfirm}
-        >
-          {props.busy ? "Working…" : props.confirmLabel}
-        </button>
-      </div>
-    </div>
-  );
-}
-
 /**
  * Organization · Billing — live plan, payment method, and invoices.
  * Fake company/tax/address “Billing details” removed (no API).
@@ -371,6 +291,20 @@ export default function BillingSection() {
     await ensurePaymentMethodForUsagePlan(planId);
   }
 
+  function openChangeTimingDialog(
+    planId: string,
+    conflict: DashboardScheduledChangeConflict | null = null
+  ) {
+    setChangeChoice(defaultCancelTimingChoice());
+    setChangeCustomDate(
+      toDateInputValue(
+        conflict?.timingOptions?.minEffectiveAt ??
+          subscription?.timingOptions?.change.minEffectiveAt
+      )
+    );
+    setChangeDialog({ planId, conflict });
+  }
+
   async function onPlanAction(planId: string, action: BillingPlanAction) {
     if (!externalUserId) {
       setError("Sign in to subscribe.");
@@ -385,15 +319,25 @@ export default function BillingSection() {
     setBusyPlanId(planId);
     try {
       if (action === "change_plan") {
+        const catalog =
+          plansState.status === "ready" ? plansState.plans : [];
+        const liveSubscription =
+          plansState.status === "ready" ? plansState.subscription : null;
+        const targetPlan = withCurrentPlanInDisplayList(
+          catalog,
+          liveSubscription
+        ).find((p) => p.id === planId);
+        // Starter downgrades schedule silently without timing — prompt first.
+        if (targetPlan?.isStarterDefault === true) {
+          setBusyPlanId(null);
+          openChangeTimingDialog(planId);
+          return;
+        }
         try {
           await runChangePlan(planId);
         } catch (err) {
           if (err instanceof ScheduledChangeConflictError) {
-            setChangeChoice("immediate");
-            setChangeCustomDate(
-              toDateInputValue(err.conflict.timingOptions?.minEffectiveAt)
-            );
-            setChangeDialog({ planId, conflict: err.conflict });
+            openChangeTimingDialog(planId, err.conflict);
             return;
           }
           throw err;
@@ -492,10 +436,16 @@ export default function BillingSection() {
       });
       await runChangePlan(changeDialog.planId, {
         ...payload,
-        confirmReplaceScheduled: true,
+        ...(changeDialog.conflict
+          ? { confirmReplaceScheduled: true }
+          : {}),
       });
       setChangeDialog(null);
     } catch (err) {
+      if (err instanceof ScheduledChangeConflictError) {
+        openChangeTimingDialog(changeDialog.planId, err.conflict);
+        return;
+      }
       setError(
         err instanceof Error ? err.message : "Could not change subscription"
       );
@@ -636,10 +586,14 @@ export default function BillingSection() {
   const paymentMethods =
     accountState.status === "ready" ? accountState.paymentMethods : [];
   const invoices = accountState.status === "ready" ? accountState.invoices : [];
+  const subscriptions =
+    accountState.status === "ready" ? accountState.subscriptions : [];
   const paymentMethodsError =
     accountState.status === "ready" ? accountState.paymentMethodsError : null;
   const invoicesError =
     accountState.status === "ready" ? accountState.invoicesError : null;
+  const subscriptionsError =
+    accountState.status === "ready" ? accountState.subscriptionsError : null;
 
   const cancelingPlanName = resolveCancelingPlanName(subscription);
   const cancelingEndsAt = resolveCancelingEffectiveAt(subscription);
@@ -929,6 +883,83 @@ export default function BillingSection() {
         )}
       </SettingsCard>
 
+      <SettingsHeader
+        title="Plan history"
+        sub="Every plan this account has been on, newest first"
+      />
+      <SettingsCard>
+        {accountLoading ? (
+          <div className="animate-pulse p-5">
+            <div className="h-4 w-full rounded bg-white/5" />
+          </div>
+        ) : subscriptionsError ? (
+          <div className="px-5 py-6 text-center">
+            <p className="text-[13px] text-fg-muted">
+              Could not load plan history.
+            </p>
+            <p className="mt-1 font-mono text-[12px] text-fg-faint">
+              {subscriptionsError}
+            </p>
+            <button
+              type="button"
+              className="mt-2 text-[12.5px] text-fg-strong underline"
+              onClick={() => void reloadAccount()}
+            >
+              Retry
+            </button>
+          </div>
+        ) : subscriptions.length === 0 ? (
+          <div className="px-5 py-9 text-center">
+            <p className="text-[13.5px] text-fg-muted">
+              No subscription history yet.
+            </p>
+          </div>
+        ) : (
+          <>
+            <div
+              className={`grid items-center gap-3 px-[18px] py-3 grid-cols-[1.6fr_0.7fr_0.9fr_0.9fr] ${ST_HEAD_CLASS}`}
+            >
+              <span>Plan</span>
+              <span>Status</span>
+              <span>Started</span>
+              <span>Ended</span>
+            </div>
+            {subscriptions.map((sub) => (
+              <div
+                key={sub.id}
+                className="grid items-center gap-3 border-b border-hairline px-[18px] py-3 grid-cols-[1.6fr_0.7fr_0.9fr_0.9fr] last:border-b-0 transition-colors hover:bg-zebra"
+              >
+                <div className="min-w-0">
+                  <div className="truncate text-[13px] text-fg">
+                    {sub.planName?.trim() || sub.planKey?.trim() || "Plan"}
+                  </div>
+                  <div className="mt-0.5 truncate font-mono text-[11px] text-fg-faint">
+                    {sub.id}
+                  </div>
+                </div>
+                <div
+                  className={
+                    sub.current
+                      ? "text-[12px] font-medium text-green-bright"
+                      : "text-[12px] capitalize text-fg-faint"
+                  }
+                >
+                  {formatSubscriptionHistoryStatus(sub)}
+                </div>
+                <div className="text-[12.5px] text-fg-faint">
+                  {formatInvoiceDate(sub.activeFrom ?? undefined)}
+                </div>
+                <div className="text-[12.5px] text-fg-faint">
+                  {sub.current
+                    ? "—"
+                    : formatInvoiceDate(sub.activeTo ?? undefined)}
+                </div>
+              </div>
+            ))}
+          </>
+        )}
+      </SettingsCard>
+
       <SettingsHeader
         title="Billing history"
         sub="Stripe invoices and auto top-ups for this account"
@@ -1054,8 +1085,16 @@ export default function BillingSection() {
         maxWidth="max-w-[420px]"
       >
         <TimingChoicePanel
-          title="Replace scheduled plan change?"
-          description="A plan change is already scheduled. Choosing a start time replaces that schedule with your new plan."
+          title={
+            changeDialog?.conflict
+              ? "Replace scheduled plan change?"
+              : "Switch to Starter"
+          }
+          description={
+            changeDialog?.conflict
+              ? "A plan change is already scheduled. Choosing a start time replaces that schedule with your new plan."
+              : "Choose when the switch to Starter should take effect."
+          }
           options={
             changeDialog?.conflict?.timingOptions ??
             subscription?.timingOptions?.change
diff --git a/lib/dashboard/billing-subscription-state.test.ts b/lib/dashboard/billing-subscription-state.test.ts
index cfb7d9d..b82a485 100644
--- a/lib/dashboard/billing-subscription-state.test.ts
+++ b/lib/dashboard/billing-subscription-state.test.ts
@@ -310,8 +310,8 @@ test("formatPendingCancelDate formats UTC calendar day", () => {
   );
 });
 
-test("cancel timing helpers default to end of cycle and map date inputs", () => {
-  assert.equal(defaultCancelTimingChoice(), "next_billing_cycle");
+test("cancel timing helpers default to immediate and map date inputs", () => {
+  assert.equal(defaultCancelTimingChoice(), "immediate");
   assert.equal(toDateInputValue("2026-08-08T00:00:00.000Z"), "2026-08-08");
   assert.equal(
     dateInputToEffectiveAtIso("2026-08-15"),
diff --git a/lib/dashboard/billing-subscription-state.ts b/lib/dashboard/billing-subscription-state.ts
index a61d1c1..247acaf 100644
--- a/lib/dashboard/billing-subscription-state.ts
+++ b/lib/dashboard/billing-subscription-state.ts
@@ -390,7 +390,7 @@ export function dateInputToEffectiveAtIso(dateYmd: string): string {
 }
 
 export function defaultCancelTimingChoice(): SubscriptionTimingChoice {
-  return "next_billing_cycle";
+  return "immediate";
 }
 
 export function resolveTimingPayload(input: {
diff --git a/lib/dashboard/pymthouse-billing-bff.ts b/lib/dashboard/pymthouse-billing-bff.ts
index a88705a..0a96f54 100644
--- a/lib/dashboard/pymthouse-billing-bff.ts
+++ b/lib/dashboard/pymthouse-billing-bff.ts
@@ -3,6 +3,7 @@ import {
   type AppUserInvoice,
   type AppUserInvoiceHostedUrlResult,
   type AppUserPaymentMethod,
+  type AppUserSubscriptionHistoryItem,
   type BillingProduct,
   type BillingState,
   type CreateAppUserPaymentMethodCheckoutResult,
@@ -362,6 +363,18 @@ export async function listDashboardUserInvoices(
   return client.listUserInvoices(externalUserId, opts);
 }
 
+export type DashboardSubscriptionHistoryItem = AppUserSubscriptionHistoryItem;
+
+export async function listDashboardUserSubscriptions(
+  externalUserId: string
+): Promise<{
+  items: DashboardSubscriptionHistoryItem[];
+  externalUserId: string;
+}> {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  return client.listUserSubscriptions(externalUserId);
+}
+
 export async function getDashboardUserInvoiceHostedUrl(
   externalUserId: string,
   invoiceId: string
diff --git a/lib/dashboard/useBillingAccount.ts b/lib/dashboard/useBillingAccount.ts
index 2a7b3f9..2dc9591 100644
--- a/lib/dashboard/useBillingAccount.ts
+++ b/lib/dashboard/useBillingAccount.ts
@@ -4,6 +4,7 @@ import { useCallback, useEffect, useState } from "react";
 import type {
   DashboardInvoice,
   DashboardPaymentMethod,
+  DashboardSubscriptionHistoryItem,
 } from "@/lib/dashboard/pymthouse-billing-bff";
 
 async function readResponseJson<T>(response: Response): Promise<T> {
@@ -20,11 +21,17 @@ async function readResponseJson<T>(response: Response): Promise<T> {
 
 /** Map missing/unroutable upstream billing APIs to an actionable message. */
 function billingUpstreamMessage(
-  surface: "payment methods" | "invoices",
+  surface: "payment methods" | "invoices" | "subscriptions",
   status: number,
   upstreamError?: string,
 ): string {
   if (status === 404 || status === 405) {
+    if (surface === "subscriptions") {
+      return (
+        `PymtHouse end-user subscriptions API is unavailable (${status}). ` +
+        "Deploy the /users/{id}/subscriptions route to this environment."
+      );
+    }
     return (
       `PymtHouse end-user ${surface} API is unavailable (${status}). ` +
       "Deploy the /users/{id}/payment-methods and /users/{id}/invoices routes " +
@@ -55,8 +62,10 @@ export type BillingAccountState =
       status: "ready";
       paymentMethods: DashboardPaymentMethod[];
       invoices: DashboardInvoice[];
+      subscriptions: DashboardSubscriptionHistoryItem[];
       paymentMethodsError: string | null;
       invoicesError: string | null;
+      subscriptionsError: string | null;
     };
 
 type ListLoadResult<T> = {
@@ -127,6 +136,42 @@ async function loadInvoices(
   }
 }
 
+async function loadSubscriptions(
+  externalUserId: string,
+): Promise<ListLoadResult<DashboardSubscriptionHistoryItem>> {
+  try {
+    const response = await fetch(
+      `/api/pymthouse/subscriptions?externalUserId=${encodeURIComponent(externalUserId)}`,
+    );
+    const body = await readResponseJson<{
+      items?: DashboardSubscriptionHistoryItem[];
+      error?: string;
+    }>(response);
+    if (!response.ok) {
+      if (isSoftBillingListUnavailable(response.status, body.error)) {
+        return { items: [], error: null };
+      }
+      return {
+        items: [],
+        error: billingUpstreamMessage(
+          "subscriptions",
+          response.status,
+          body.error,
+        ),
+      };
+    }
+    return { items: body.items ?? [], error: null };
+  } catch (error) {
+    return {
+      items: [],
+      error:
+        error instanceof Error
+          ? error.message
+          : "Failed to load subscription history",
+    };
+  }
+}
+
 export function useBillingAccount(externalUserId: string | undefined) {
   const [state, setState] = useState<BillingAccountState>({ status: "idle" });
 
@@ -137,24 +182,29 @@ export function useBillingAccount(externalUserId: string | undefined) {
         status: "ready",
         paymentMethods: [],
         invoices: [],
+        subscriptions: [],
         paymentMethodsError: null,
         invoicesError: null,
+        subscriptionsError: null,
       });
       return;
     }
 
     setState({ status: "loading" });
-    // Independent loads — invoice soft-503 must not poison payment methods UI.
-    const [pm, inv] = await Promise.all([
+    // Independent loads — soft failures must not poison sibling surfaces.
+    const [pm, inv, subs] = await Promise.all([
       loadPaymentMethods(trimmed),
       loadInvoices(trimmed),
+      loadSubscriptions(trimmed),
     ]);
     setState({
       status: "ready",
       paymentMethods: pm.items,
       invoices: inv.items,
+      subscriptions: subs.items,
       paymentMethodsError: pm.error,
       invoicesError: inv.error,
+      subscriptionsError: subs.error,
     });
   }, [externalUserId]);
 

From 3189cd1147895679f525c93796599e52ca01acfc Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Mon, 10 Aug 2026 23:13:05 -0400
Subject: [PATCH 13/13] chore(dependencies): update @pymthouse/builder-sdk to
 version 0.6.4

- Changed dependency from local file reference to versioned package for better stability and compatibility.
- Updated pnpm-lock.yaml to reflect the new versioning for @pymthouse/builder-sdk.
---
 package.json   |  2 +-
 pnpm-lock.yaml | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/package.json b/package.json
index f9bf759..ef3846b 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,7 @@
     "format:check": "prettier . --check"
   },
   "dependencies": {
-    "@pymthouse/builder-sdk": "file:../builder-sdk",
+    "@pymthouse/builder-sdk": "^0.6.4",
     "framer-motion": "^11.15.0",
     "geist": "^1.7.0",
     "jmuxer": "^2.1.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f92ba5d..8e4d7ba 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -9,8 +9,8 @@ importers:
   .:
     dependencies:
       '@pymthouse/builder-sdk':
-        specifier: file:../builder-sdk
-        version: file:../builder-sdk
+        specifier: ^0.6.4
+        version: 0.6.4
       framer-motion:
         specifier: ^11.15.0
         version: 11.18.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -401,8 +401,8 @@ packages:
     resolution: {integrity: sha512-nn5ozdjYQpUCZlWGuxcJY/KpxkWQs4DcbMCmKojjyrYDEAGy4Ce19NN4v5MduafTwJlbKc99UA8YhSVqq9yPZA==}
     engines: {node: '>=12.4.0'}
 
-  '@pymthouse/builder-sdk@file:../builder-sdk':
-    resolution: {directory: ../builder-sdk, type: directory}
+  '@pymthouse/builder-sdk@0.6.4':
+    resolution: {integrity: sha512-bB55HzmW9Ud1Bl7VrC0vCRfAcXaeW8o6Ilf910B2rVTX/k1mXkUKT+BWrFMo0WVzC4gYhcQePBmTiXXPvZEMoQ==}
     engines: {node: '>=20'}
 
   '@reduxjs/toolkit@2.11.2':
@@ -2331,7 +2331,7 @@ snapshots:
 
   '@nolyfill/is-core-module@1.0.39': {}
 
-  '@pymthouse/builder-sdk@file:../builder-sdk':
+  '@pymthouse/builder-sdk@0.6.4':
     dependencies:
       oauth4webapi: 3.8.6