diff --git a/.env.example b/.env.example
index 920b0b8..1b4fb8e 100644
--- a/.env.example
+++ b/.env.example
@@ -6,20 +6,18 @@ 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
-# 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/(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/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/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/app/api/pymthouse/payment-methods/route.ts b/app/api/pymthouse/payment-methods/route.ts
new file mode 100644
index 0000000..f7d3965
--- /dev/null
+++ b/app/api/pymthouse/payment-methods/route.ts
@@ -0,0 +1,215 @@
+import { NextRequest, NextResponse } from "next/server";
+import { PmtHouseError } from "@pymthouse/builder-sdk";
+import {
+  listDashboardUserPaymentMethods,
+  removeDashboardUserPaymentMethod,
+  ensureDashboardUserDefaultPaymentMethod,
+  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) {
+  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(
+        externalUserId,
+        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/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..7ad2416
--- /dev/null
+++ b/app/api/pymthouse/subscribe/route.ts
@@ -0,0 +1,79 @@
+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 },
+    );
+  }
+
+  // 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 =
+    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/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
new file mode 100644
index 0000000..1869b47
--- /dev/null
+++ b/app/api/pymthouse/subscription/change/route.ts
@@ -0,0 +1,60 @@
+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;
+    timing?: string;
+    effectiveAt?: string;
+    confirmReplaceScheduled?: boolean;
+  };
+  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(),
+      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.details && typeof error.details === "object"
+            ? (error.details as Record<string, unknown>)
+            : {}),
+        },
+        { 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/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/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/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/app/api/pymthouse/wallet/invoices/route.ts b/app/api/pymthouse/wallet/invoices/route.ts
new file mode 100644
index 0000000..ae2d938
--- /dev/null
+++ b/app/api/pymthouse/wallet/invoices/route.ts
@@ -0,0 +1,39 @@
+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 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({
+      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
new file mode 100644
index 0000000..38a8b2e
--- /dev/null
+++ b/app/api/pymthouse/wallet/payment-methods/route.ts
@@ -0,0 +1,114 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  listDashboardWalletPaymentMethods,
+  startDashboardWalletPaymentMethodCheckout,
+  ensureDashboardWalletDefaultPaymentMethod,
+} 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(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(externalUserId);
+    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: {
+    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`;
+  const cancelUrl = body.cancelUrl?.trim() || `${origin}/usage?topup=canceled`;
+
+  try {
+    const result = await startDashboardWalletPaymentMethodCheckout({
+      externalUserId,
+      successUrl,
+      cancelUrl,
+    });
+    return NextResponse.json(result);
+  } catch (error) {
+    return walletErrorResponse(
+      error,
+      "Failed to start payment method checkout",
+    );
+  }
+}
+
+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
new file mode 100644
index 0000000..e2592d0
--- /dev/null
+++ b/app/api/pymthouse/wallet/route.ts
@@ -0,0 +1,39 @@
+import { NextRequest, 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(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(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
new file mode 100644
index 0000000..20552de
--- /dev/null
+++ b/app/api/pymthouse/wallet/top-up/route.ts
@@ -0,0 +1,58 @@
+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;
+    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)
+      : 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,
+      externalUserId,
+      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/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/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/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/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
new file mode 100644
index 0000000..ecc5845
--- /dev/null
+++ b/components/dashboard/PlansPanel.tsx
@@ -0,0 +1,413 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import Button from "@/components/design-system/Button";
+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 {
+  ScheduledChangeConflictError,
+  useBillingPlans,
+} from "@/lib/dashboard/useBillingPlans";
+
+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 { price, priceSub } = formatBillingPlanPrice(plan);
+  return `${price}${priceSub}`;
+}
+
+function resolvedPayPerUseBehavior(plan: DashboardBillingPlan): string {
+  const resolved = plan.resolvedBehavior?.trim();
+  if (resolved) return resolved;
+
+  return "Usage draws down included usage first, then prepaid credits, then is invoiced automatically as it accrues.";
+}
+
+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 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);
+  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}`);
+}
+
+export default function PlansPanel({
+  externalUserId,
+}: {
+  externalUserId: string | undefined;
+}) {
+  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);
+  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();
+    const resumePlanId = readResumePlanChange();
+    if (!next && !resumePlanId) return;
+    if (resumePlanId && !externalUserId?.trim()) return;
+
+    if (next) setFlash(next);
+    clearCheckoutQueryParam();
+    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();
+    })();
+    // 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.");
+      return;
+    }
+    setError(null);
+    setBusyPlanId(planId);
+    try {
+      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");
+
+      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.
+      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);
+    }
+  }
+
+  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;
+      }
+      setError(
+        err instanceof Error ? err.message : "Could not change subscription"
+      );
+    } finally {
+      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;
+  }
+
+  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">
+        <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>
+        {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) => {
+          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"
+            >
+              <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…"
+                    : plan.isStarterDefault
+                      ? hasActiveSubscription && !isCurrent
+                        ? "Switch to Starter"
+                        : "Choose Starter"
+                      : 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>
+      ) : 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/SidebarUsageCard.tsx b/components/dashboard/SidebarUsageCard.tsx
index 207e5dc..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 ? "Starter" : "Usage";
+  const planLabel = showUsdAllowance ? "Included usage" : "Usage";
 
   let primaryUsed: number;
   let primaryLimit: number | null;
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/UsageView.tsx b/components/dashboard/UsageView.tsx
index 182a04d..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,
@@ -14,6 +13,8 @@ import {
   type UsageCapabilityRow,
 } 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;
 
@@ -83,7 +84,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 ? "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">
@@ -264,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 (
@@ -288,6 +289,17 @@ export default function UsageView() {
         resetsAt={resetsAt}
       />
 
+      <WalletPanel
+        externalUserId={externalUserId}
+        periodBillableUsdMicros={
+          data.current.endUserBillableUsdMicros ||
+          data.current.networkFeeUsdMicros ||
+          null
+        }
+      />
+
+      <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>
@@ -516,7 +528,7 @@ function LimitsPanel({
   const limits = balance
     ? [
         {
-          label: "Included 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
new file mode 100644
index 0000000..8c4b939
--- /dev/null
+++ b/components/dashboard/WalletPanel.tsx
@@ -0,0 +1,362 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import Button from "@/components/design-system/Button";
+import { useOwnerWallet } from "@/lib/dashboard/useOwnerWallet";
+import {
+  availableRunway,
+  collectionSchedule,
+  formatWalletUsd,
+  overageLimitNote,
+  spendPostureBadge,
+  type SpendPostureTone,
+} from "@/lib/dashboard/wallet-settlement-display";
+
+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;
+
+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 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. */
+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({
+  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);
+  const [error, setError] = useState<string | null>(null);
+  const [flash, setFlash] = useState<TopUpFlash | null>(null);
+
+  useEffect(() => {
+    const next = readTopUpFlash();
+    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);
+    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 usageUsd = formatWalletUsd(periodBillableUsdMicros);
+  const billingState = wallet.billingState;
+  const posture = spendPostureBadge(billingState.status);
+  const runway = availableRunway(billingState);
+  const limitNote = overageLimitNote(billingState);
+  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 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>
+
+          <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">
+                Available
+              </p>
+              <p
+                className={`mt-1 font-mono text-[28px] font-medium tabular-nums tracking-[-0.01em] ${AVAILABLE_TONE_CLASS[runway.tone]}`}
+              >
+                {runway.usd}
+              </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">
+                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)}
+          </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">
+            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 — progressive invoices cannot charge 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 or top-ups 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.invoiceType === "auto_topup"
+                    ? "top-up"
+                    : 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 d46eb20..a7e67b0 100644
--- a/components/dashboard/settings/BillingSection.tsx
+++ b/components/dashboard/settings/BillingSection.tsx
@@ -1,292 +1,1179 @@
 "use client";
 
-import { ArrowRight, Box, Check, Download, Plus } 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 Dialog from "@/components/design-system/Dialog";
+import TimingChoicePanel from "@/components/dashboard/TimingChoicePanel";
 import {
   IconButton,
   SettingsCard,
-  SettingsField,
   SettingsHeader,
-  SettingsInput,
-  SettingsTextarea,
   ST_COLS_5,
   ST_HEAD_CLASS,
 } from "./SettingsPrimitives";
+import {
+  ResumeSubscriptionError,
+  ScheduledChangeConflictError,
+  useBillingPlans,
+} from "@/lib/dashboard/useBillingPlans";
+import { useBillingAccount } from "@/lib/dashboard/useBillingAccount";
+import type {
+  DashboardBillingPlan,
+  DashboardScheduledChangeConflict,
+} 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,
+} from "@/lib/dashboard/billing-subscription-state";
+
+function isUsagePlan(
+  plan: Pick<DashboardBillingPlan, "type" | "isStarterDefault">
+): boolean {
+  if (plan.isStarterDefault) return false;
+  return plan.type.trim().toLowerCase() === "usage";
+}
+
+function resolvedPayPerUseBehavior(plan: DashboardBillingPlan): string {
+  const resolved = plan.resolvedBehavior?.trim();
+  if (resolved) {
+    return resolved;
+  }
+
+  return "Pay-per-use — usage draws down prepaid credits first, then is invoiced automatically as it accrues.";
+}
+
+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",
+  }).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",
+  });
+}
+
+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");
+  if (value === "success" || value === "cancel") return value;
+  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);
+  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}`
+  );
+}
+
+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`;
+}
 
 /**
- * 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
+ * Organization · Billing — live plan, payment method, and invoices.
+ * Fake company/tax/address “Billing details” removed (no API).
  */
 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: plansState,
+    reload: reloadPlans,
+    subscribe,
+    changePlan,
+    cancelSubscription,
+    resumeSubscription,
+  } = useBillingPlans(externalUserId);
+  const {
+    state: accountState,
+    reload: reloadAccount,
+    startPaymentMethodCheckout,
+    openInvoice,
+    setDefaultPaymentMethod,
+    ensureDefaultPaymentMethod,
+    removePaymentMethod,
+  } = useBillingAccount(externalUserId);
+
+  const [busyPlanId, setBusyPlanId] = useState<string | null>(null);
+  const [pmBusy, setPmBusy] = useState(false);
+  const [lifecycleBusy, setLifecycleBusy] = useState(false);
+  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);
+
+  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();
+    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 () => {
+        if (externalUserId) {
+          try {
+            await ensureDefaultPaymentMethod({ externalUserId });
+          } catch {
+            // 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,
+    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: billingChangePlanSuccessUrl(planId),
+      cancelUrl: billingChangePlanCancelUrl(),
+      ...timing,
+    });
+    if (result.checkoutUrl) {
+      window.location.assign(result.checkoutUrl);
+      return;
+    }
+    await reloadPlans();
+    setBillingNotice("Your plan has been updated.");
+    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.");
+      return;
+    }
+    if (action === "current") {
+      return;
+    }
+
+    setError(null);
+    setBillingNotice(null);
+    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) {
+            openChangeTimingDialog(planId, err.conflict);
+            return;
+          }
+          throw err;
+        }
+        return;
+      }
+
+      const input = {
+        planId:
+          action === "retry_checkout"
+            ? (subscriptionUiState.planId ?? planId)
+            : planId,
+        externalUserId,
+        successUrl: billingChangePlanSuccessUrl(
+          action === "retry_checkout"
+            ? (subscriptionUiState.planId ?? planId)
+            : planId
+        ),
+        cancelUrl: billingChangePlanCancelUrl(),
+      };
+      const result = 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);
+    }
+  }
+
+  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,
+        ...(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"
+      );
+    } 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.");
+      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(
+          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) {
+      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 plansLoading =
+    plansState.status === "loading" || plansState.status === "idle";
+  const accountLoading =
+    accountState.status === "loading" || accountState.status === "idle";
+
+  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 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);
+  const cancelingEndsLabel = formatPendingCancelDate(cancelingEndsAt);
+
+  const planSub =
+    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");
+
+  // 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));
+  const showCancelingBanner = subscriptionUiState.kind === "canceling";
+
   return (
-    <div className="relative">
-      <div
-        className="pointer-events-none select-none blur-sm"
-        aria-hidden="true"
-      >
+    <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}
+
+      {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="You're on the free tier · 10,000 jobs/month"
+        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>
-        <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. */}
-          <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>
-
-          {/* Pro — upgrade option */}
-          <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"
-          />
-
-          {/* Scale — enterprise */}
-          <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 } = 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}
+                  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 usage above the free tier"
+        sub="Card on file for subscription charges and pay-per-use auto-debit"
         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>
+        {accountLoading ? (
+          <div className="animate-pulse px-5 py-9">
+            <div className="mx-auto h-5 w-40 rounded bg-white/5" />
+          </div>
+        ) : 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">
+              {paymentMethodsError}
+            </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 for subscription and usage charges.
+              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="Billing details"
-        sub="Used on invoices and receipts"
+        title="Plan history"
+        sub="Every plan this account has been on, newest first"
       />
       <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 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="Invoices"
-        action={
-          <IconButton>
-            <Download className="h-3 w-3" aria-hidden="true" />
-            Download all
-          </IconButton>
-        }
+        title="Billing history"
+        sub="Stripe invoices and auto top-ups 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>
-        ))}
+        ) : 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">
+              {invoicesError}
+            </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 or top-ups yet.
+            </p>
+          </div>
+        ) : (
+          <>
+            <div className={`${ST_COLS_5} ${ST_HEAD_CLASS}`}>
+              <span>Item</span>
+              <span>Date</span>
+              <span>Amount</span>
+              <span>Status</span>
+              <span aria-hidden="true" />
+            </div>
+            {invoices.map((inv) => {
+              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}
+                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">
+                  {statusLabel}
+                </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")}
+                  >
+                    {isReceiptOnly ? "Receipt" : "View"}
+                  </button>
+                  {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"
+                    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>
+
+      <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={
+            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
+          }
+          choice={changeChoice}
+          customDate={changeCustomDate}
+          confirmLabel="Confirm switch"
+          busy={busyPlanId !== null}
+          onChoice={setChangeChoice}
+          onCustomDate={setChangeCustomDate}
+          onConfirm={() => void onConfirmChangeTiming()}
+          onClose={() => setChangeDialog(null)}
+        />
+      </Dialog>
     </div>
   );
 }
 
-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}
@@ -309,16 +1196,23 @@ 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, {
+              usagePlan: isUsagePlan(plan),
+              starterPlan: plan.isStarterDefault === true,
+            })}
+        {action !== "current" && !busy ? (
           <ArrowRight className="h-2.5 w-2.5" aria-hidden="true" />
-        )}
+        ) : null}
       </button>
     </div>
   );
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/billing-subscription-state.test.ts b/lib/dashboard/billing-subscription-state.test.ts
new file mode 100644
index 0000000..b82a485
--- /dev/null
+++ b/lib/dashboard/billing-subscription-state.test.ts
@@ -0,0 +1,376 @@
+import assert from "node:assert/strict";
+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", () => {
+  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("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",
+    status: "pending",
+  });
+
+  assert.deepEqual(state, { kind: "pending", planId: "pro" });
+  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 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"),
+    "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" },
+  );
+});
+
+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
new file mode 100644
index 0000000..247acaf
--- /dev/null
+++ b/lib/dashboard/billing-subscription-state.ts
@@ -0,0 +1,405 @@
+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: "canceling"; planId: string };
+
+export type BillingPlanAction =
+  | "subscribe"
+  | "change_plan"
+  | "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",
+  "incomplete",
+  "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 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 };
+  }
+
+  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";
+  }
+  // canceling still treats current plan as current; other plans can switch/upgrade
+  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; 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";
+  }
+}
+
+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 "immediate";
+}
+
+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
new file mode 100644
index 0000000..0a96f54
--- /dev/null
+++ b/lib/dashboard/pymthouse-billing-bff.ts
@@ -0,0 +1,638 @@
+import {
+  PmtHouseError,
+  type AppUserInvoice,
+  type AppUserInvoiceHostedUrlResult,
+  type AppUserPaymentMethod,
+  type AppUserSubscriptionHistoryItem,
+  type BillingProduct,
+  type BillingState,
+  type CreateAppUserPaymentMethodCheckoutResult,
+  type CreateBillingCheckoutResult,
+  type UserSubscriptionResponse,
+} 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;
+}
+
+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;
+  type: string;
+  status: string;
+  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 {
+  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;
+  };
+  const isStarterDefault = product.isStarterDefault === true;
+  const name = isStarterDefault
+    ? "Starter"
+    : product.name?.trim() || product.id;
+
+  return {
+    id: product.id,
+    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,
+    includedUsdMicros: readOptionalString(
+      product.allowance?.includedUsdMicros,
+    ),
+    chargeThresholdUsdMicros: isStarterDefault
+      ? null
+      : readOptionalString(dynamicProduct.chargeThresholdUsdMicros),
+    resolvedBehavior: isStarterDefault
+      ? null
+      : readOptionalString(dynamicProduct.resolvedBehavior),
+    capabilityCount: product.capabilities?.length ?? 0,
+    isStarterDefault,
+  };
+}
+
+/**
+ * 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)
+    .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
+  // (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: {
+  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 } : {}),
+  });
+}
+
+export type DashboardSubscriptionChange = {
+  subscriptionId: string;
+  planId: string;
+  effectiveAt: string | null;
+  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(
+    `${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 } : {}),
+        ...(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);
+}
+
+export type DashboardUserSubscription = {
+  planId: string | null;
+  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(
+  externalUserId: string
+): Promise<DashboardUserSubscription> {
+  const client = createPmtHouseClientForPublicApp(readPublicClientId());
+  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() || 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;
+
+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 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
+): 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);
+}
+
+/** 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
+) {
+  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;
+  };
+  /** Canonical spend posture; the API owns the customer-facing copy. */
+  billingState: BillingState;
+  payPerUsePlans: DashboardWalletPayPerUsePlan[];
+};
+
+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>;
+    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${urlPath}`,
+    {
+      method: init?.method ?? "GET",
+      headers: {
+        Authorization: readM2mAuthHeader(),
+        Accept: "application/json",
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+      cache: "no-store",
+    }
+  );
+  return readPymthouseResponse<T>(response);
+}
+
+/** 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 } : {}),
+      ...(input.cancelUrl ? { cancelUrl: input.cancelUrl } : {}),
+    },
+  });
+}
+
+/** GET …/billing/wallet/invoices — past platform invoices, newest first. */
+export async function listDashboardWalletInvoices(opts?: {
+  externalUserId?: string;
+  page?: number;
+  pageSize?: number;
+}): Promise<{
+  items: DashboardWalletInvoice[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}> {
+  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(
+  externalUserId?: string
+): Promise<DashboardWalletPaymentMethod[]> {
+  const result = await walletFetch<{
+    paymentMethods?: DashboardWalletPaymentMethod[];
+  }>("/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> {
+  return walletFetch<DashboardWalletPaymentMethodCheckoutResult>(
+    "/payment-methods",
+    {
+      method: "POST",
+      externalUserId: input.externalUserId,
+      body: {
+        ...(input.successUrl ? { successUrl: input.successUrl } : {}),
+        ...(input.cancelUrl ? { cancelUrl: input.cancelUrl } : {}),
+      },
+    }
+  );
+}
+
+/** 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/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/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) {
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 };
 }
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
new file mode 100644
index 0000000..2dc9591
--- /dev/null
+++ b/lib/dashboard/useBillingAccount.ts
@@ -0,0 +1,326 @@
+"use client";
+
+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> {
+  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 billing APIs to an actionable message. */
+function billingUpstreamMessage(
+  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 " +
+      "(pymthouse PR #386) to this environment."
+    );
+  }
+  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" }
+  | {
+      status: "ready";
+      paymentMethods: DashboardPaymentMethod[];
+      invoices: DashboardInvoice[];
+      subscriptions: DashboardSubscriptionHistoryItem[];
+      paymentMethodsError: string | null;
+      invoicesError: string | null;
+      subscriptionsError: 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),
+      };
+    }
+    return { items: body.items ?? [], error: null };
+  } catch (error) {
+    return {
+      items: [],
+      error: error instanceof Error ? error.message : "Failed to load invoices",
+    };
+  }
+}
+
+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" });
+
+  const load = useCallback(async () => {
+    const trimmed = externalUserId?.trim();
+    if (!trimmed) {
+      setState({
+        status: "ready",
+        paymentMethods: [],
+        invoices: [],
+        subscriptions: [],
+        paymentMethodsError: null,
+        invoicesError: null,
+        subscriptionsError: null,
+      });
+      return;
+    }
+
+    setState({ status: "loading" });
+    // 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]);
+
+  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 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", {
+        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,
+    ensureDefaultPaymentMethod,
+    removePaymentMethod,
+  };
+}
diff --git a/lib/dashboard/useBillingPlans.ts b/lib/dashboard/useBillingPlans.ts
new file mode 100644
index 0000000..a21737b
--- /dev/null
+++ b/lib/dashboard/useBillingPlans.ts
@@ -0,0 +1,234 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import type {
+  DashboardBillingPlan,
+  DashboardScheduledChangeConflict,
+  DashboardUserSubscription,
+} from "@/lib/dashboard/pymthouse-billing-bff";
+
+export type BillingPlansState =
+  | { status: "idle" }
+  | { status: "loading" }
+  | {
+      status: "ready";
+      plans: DashboardBillingPlan[];
+      subscription: DashboardUserSubscription | null;
+    }
+  | { 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()) {
+    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(externalUserId: string | undefined) {
+  const [state, setState] = useState<BillingPlansState>({ status: "idle" });
+
+  const load = useCallback(async () => {
+    setState({ status: "loading" });
+    try {
+      const plansResponse = await fetch("/api/pymthouse/plans");
+      const plansBody = await readResponseJson<{
+        plans?: DashboardBillingPlan[];
+        error?: string;
+      }>(plansResponse);
+      if (!plansResponse.ok) {
+        throw new Error(
+          plansBody.error ?? `Plans fetch failed (${plansResponse.status})`
+        );
+      }
+
+      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",
+        message:
+          error instanceof Error ? error.message : "Failed to load plans",
+      });
+    }
+  }, [externalUserId]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const subscribe = useCallback(
+    async (input: {
+      planId: string;
+      externalUserId: string;
+      successUrl?: string;
+      cancelUrl?: 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,
+      };
+    },
+    []
+  );
+
+  const changePlan = useCallback(
+    async (input: {
+      planId: string;
+      externalUserId: string;
+      successUrl?: string;
+      cancelUrl?: string;
+      timing?: string;
+      effectiveAt?: string;
+      confirmReplaceScheduled?: boolean;
+    }) => {
+      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;
+        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})`
+        );
+      }
+      return {
+        checkoutUrl: body.checkoutUrl,
+        subscriptionId: body.subscriptionId,
+      };
+    },
+    []
+  );
+
+  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..eec985a
--- /dev/null
+++ b/lib/dashboard/useOwnerWallet.ts
@@ -0,0 +1,194 @@
+"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,
+  externalUserId: string | undefined,
+) {
+  const [state, setState] = useState<OwnerWalletState>({ status: "idle" });
+  const trimmedUserId = externalUserId?.trim() || "";
+
+  const load = useCallback(async () => {
+    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?${qs}`),
+        fetch(`/api/pymthouse/wallet/payment-methods?${qs}`),
+        fetch(`/api/pymthouse/wallet/invoices?${qs}&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, trimmedUserId]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  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({
+        externalUserId: trimmedUserId,
+        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 };
+  }, [trimmedUserId]);
+
+  const ensureDefaultPaymentMethod = useCallback(async () => {
+    if (!trimmedUserId) {
+      throw new Error("externalUserId is required");
+    }
+    const response = await fetch("/api/pymthouse/wallet/payment-methods", {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        externalUserId: trimmedUserId,
+        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();
+  }, [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..0e07f6a
--- /dev/null
+++ b/lib/dashboard/wallet-settlement-display.test.ts
@@ -0,0 +1,226 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import type { BillingState } from "@pymthouse/builder-sdk";
+import {
+  availableRunway,
+  collectionSchedule,
+  overageLimitNote,
+  spendPostureBadge,
+} from "./wallet-settlement-display";
+
+function money(usdMicros: string, usd: string) {
+  return { usdMicros, usd, currency: "USD" };
+}
+
+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;
+  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"),
+        ...(overrides.prepaid ?? {}),
+      },
+      included: money("0", "0.00"),
+      includedUsage: {
+        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,
+      },
+      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("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("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" },
+      }),
+    );
+    assert.equal(runway.usd, "-$2.00");
+    assert.equal(runway.tone, "danger");
+  });
+});
+
+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("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(note, "Overage limit reached");
+  });
+
+  it("hides the note when there is no ceiling", () => {
+    const note = overageLimitNote(
+      makeState({ ceiling: { usdMicros: "0", usd: "0.00" } }),
+    );
+    assert.equal(note, 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..a2562ba
--- /dev/null
+++ b/lib/dashboard/wallet-settlement-display.ts
@@ -0,0 +1,126 @@
+import type { BillingState, BillingStatus } from "@pymthouse/builder-sdk";
+import { microsToUsd } from "./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);
+}
+
+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";
+
+/**
+ * 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" };
+  }
+}
+
+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;
+};
+
+/**
+ * Signed runway: included remaining + prepaid − unbilled debt.
+ * Goes negative once spend accrues against the overage ceiling.
+ */
+export function availableRunway(state: BillingState): AvailableRunway {
+  const included = parseUsdMicros(
+    state.funding.includedUsage?.remaining.usdMicros ??
+      state.funding.included.usdMicros,
+  );
+  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 {
+    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;
+  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()}.`
+  );
+}
diff --git a/package.json b/package.json
index 75fe678..ef3846b 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": "^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 3c3d2cd..8e4d7ba 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: ^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@0.6.3':
-    resolution: {integrity: sha512-ex+qcGknv6gs+FqvmgoQgR5Trwy/yQ7UIO91jlGVPpgwSccFqTunP/Lmi+ABY9Gz1F0xN+U9C6AYOhkFSb/Nsw==}
+  '@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@0.6.3':
+  '@pymthouse/builder-sdk@0.6.4':
     dependencies:
       oauth4webapi: 3.8.6