Billing rework

src/app/[locale]/dashboard/new/page.tsx

@@ -4,7 +4,7 @@ import { redirect } from "next/navigation";
 import { OnboardingFlow } from "@/components/onboarding/onboarding-flow";
 import { BackLink } from "@/components/ui/back-link";
 import { listTenants } from "@/lib/k8s";
-import { listActiveTenantRequestsByOrgId } from "@/lib/db";
+import { listActiveTenantRequestsByOrgId, getOrgBilling } from "@/lib/db";
 import { personalAccountAtCapacity } from "@/lib/personal-org";
 
 /**
@@ -55,6 +55,8 @@ export default async function NewInstancePage() {
   }
 
   const t = await getTranslations("dashboard");
+  const orgBilling = await getOrgBilling(user.orgId);
+  const hasOrgBilling = orgBilling !== null;
 
   return (
     <div>
@@ -73,6 +75,7 @@ export default async function NewInstancePage() {
           orgName={user.orgName}
           userName={user.name}
           userEmail={user.email}
+          hasOrgBilling={hasOrgBilling}
         />
       </div>
     </div>

src/app/[locale]/dashboard/page.tsx

@@ -5,6 +5,7 @@ import { listTenants } from "@/lib/k8s";
 import {
   listActiveTenantRequestsByOrgId,
   syncProvisioningStatuses,
+  getOrgBilling,
 } from "@/lib/db";
 import {
   listVisibleTenants,
@@ -184,6 +185,14 @@ export default async function DashboardPage() {
     ? await listActiveTenantRequestsByOrgId(user.orgId)
     : [];
 
+  // Bug 35: orgs that already have a billing record skip the wizard's
+  // billing step. Fetched here so the dashboard's empty-state mount of
+  // OnboardingFlow knows what to do; for the additional-tenant flow at
+  // /dashboard/new we fetch the same flag in that route's own server
+  // component.
+  const orgBilling = await getOrgBilling(user.orgId);
+  const hasOrgBilling = orgBilling !== null;
+
   // Pending requests that don't yet have a tenant CR. Once the CR
   // exists, the tenant card carries the live phase, so a separate
   // "request" card would just duplicate it. We compare against
@@ -307,6 +316,7 @@ export default async function DashboardPage() {
             orgName={user.orgName}
             userName={user.name}
             userEmail={user.email}
+            hasOrgBilling={hasOrgBilling}
           />
         </div>
       </div>

src/app/[locale]/settings/billing/page.tsx

@@ -0,0 +1,47 @@
+import { getTranslations } from "next-intl/server";
+import { redirect, notFound } from "next/navigation";
+import { getSessionUser, canMutate } from "@/lib/session";
+import { getOrgBilling } from "@/lib/db";
+import { BillingSettingsForm } from "@/components/settings/billing-settings-form";
+
+/**
+ * /settings/billing — view and edit org-scoped billing (Bug 34/35).
+ *
+ * Server-side fetches the existing record (if any) and passes it to
+ * the client form. The form posts to PUT /api/billing on submit.
+ *
+ * Access: same gate as the API — owners and platform admins. `user`
+ * role redirects to /settings (which also wouldn't list billing for
+ * them). 403 here would be friendlier than redirect, but the most
+ * likely cause of a `user` landing on this URL is sharing a bookmark
+ * with their owner — silent redirect is gentle.
+ */
+export default async function BillingSettingsPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (!canMutate(user)) {
+    redirect("/settings");
+  }
+  const t = await getTranslations("settingsBilling");
+
+  const billing = await getOrgBilling(user.orgId);
+
+  return (
+    <main className="max-w-3xl mx-auto px-6 py-8">
+      <div className="mb-8 animate-in">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("title")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">{t("subtitle")}</p>
+      </div>
+
+      <BillingSettingsForm
+        initial={billing}
+        isPersonal={user.isPersonal}
+        orgName={user.orgName}
+        userName={user.name}
+        userEmail={user.email}
+      />
+    </main>
+  );
+}

src/app/[locale]/settings/page.tsx

@@ -0,0 +1,81 @@
+import { getTranslations } from "next-intl/server";
+import { redirect } from "next/navigation";
+import Link from "next/link";
+import { getSessionUser, canMutate } from "@/lib/session";
+import { Card } from "@/components/ui/card";
+
+/**
+ * /settings — landing page for user/org-level configuration (Bug 35
+ * intentionally landed billing here rather than at /billing because we
+ * expect more settings categories: notifications, API keys, default
+ * workspace templates, etc.). Currently lists a single category card;
+ * the layout scales to a sidebar nav once there are 3+.
+ *
+ * Access: any authenticated user (the cards themselves gate further;
+ * non-owner users would not see "Billing" as actionable, etc.).
+ */
+export default async function SettingsPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  const t = await getTranslations("settings");
+
+  // Build the list of settings cards. Each entry has a stable key, a
+  // route, and a visibility predicate. Currently only billing; this
+  // shape leaves headroom for adding more without restructuring.
+  const sections: Array<{
+    key: string;
+    href: string;
+    title: string;
+    description: string;
+    visible: boolean;
+  }> = [
+    {
+      key: "billing",
+      href: "/settings/billing",
+      title: t("billingTitle"),
+      // Personal customers (B2C) don't have a VAT number; the
+      // description shouldn't mention one. Same pattern used in the
+      // form itself (label/field gating).
+      description: user.isPersonal
+        ? t("billingDescriptionPersonal")
+        : t("billingDescription"),
+      // Owners and platform admins can edit billing. `user` role
+      // can't even view it — billing details aren't useful to them.
+      visible: canMutate(user),
+    },
+  ];
+
+  const visibleSections = sections.filter((s) => s.visible);
+
+  return (
+    <main className="max-w-4xl mx-auto px-6 py-8">
+      <div className="mb-8 animate-in">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("title")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">{t("subtitle")}</p>
+      </div>
+
+      {visibleSections.length === 0 && (
+        <Card className="animate-in animate-in-delay-1">
+          <p className="text-sm text-text-secondary">{t("nothingForYou")}</p>
+        </Card>
+      )}
+
+      <div className="grid gap-3 animate-in animate-in-delay-1">
+        {visibleSections.map((s) => (
+          <Link
+            key={s.key}
+            href={s.href}
+            className="block rounded-xl border border-border bg-surface-1 p-4 hover:border-text-secondary transition-colors"
+          >
+            <div className="font-medium text-text-primary">{s.title}</div>
+            <div className="text-xs text-text-secondary mt-1">
+              {s.description}
+            </div>
+          </Link>
+        ))}
+      </div>
+    </main>
+  );
+}

src/app/api/billing/route.ts

@@ -0,0 +1,128 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser, canMutate } from "@/lib/session";
+import { getOrgBilling, upsertOrgBilling } from "@/lib/db";
+import { safeError } from "@/lib/errors";
+
+/**
+ * Org-scoped billing API (Bug 35).
+ *
+ * GET — return the current billing record for the caller's org, or
+ * 404 if none has been captured yet. The /settings/billing page
+ * renders an empty form on 404 (first-time edit) and a pre-filled
+ * form on 200.
+ *
+ * PUT — upsert the billing record. Required for any subsequent tenant
+ * provisioning unless the caller is on a personal org. Validation:
+ *   - All address fields required.
+ *   - VAT number required for company orgs (where `user.isPersonal`
+ *     is false). Optional for personal orgs.
+ *   - billing_email validated as RFC-5322-ish.
+ *
+ * Authorization:
+ *   - GET: any authenticated user in the org. We expose only their
+ *     own org's billing — orgId is scoped from the session.
+ *   - PUT: owners and platform admins (canMutate check). Customers
+ *     in `user` role cannot edit billing.
+ */
+
+const billingSchema = z.object({
+  companyName: z.string().min(1).max(200),
+  streetAddress: z.string().min(1).max(200),
+  postalCode: z.string().min(1).max(20),
+  city: z.string().min(1).max(100),
+  country: z.string().min(2).max(3), // ISO 3166-1 alpha-2 or alpha-3
+  vatNumber: z
+    .string()
+    .max(50)
+    .nullable()
+    .optional()
+    .transform((v) => (v && v.trim() !== "" ? v.trim() : null)),
+  billingEmail: z.string().email().max(200),
+  notes: z
+    .string()
+    .max(2000)
+    .nullable()
+    .optional()
+    .transform((v) => (v && v.trim() !== "" ? v.trim() : null)),
+});
+
+export async function GET() {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const billing = await getOrgBilling(user.orgId);
+  if (!billing) {
+    // 404 carries semantic meaning here — "no record yet". Callers
+    // (settings page, wizard) treat this as the empty-form state.
+    return NextResponse.json(
+      { error: "No billing record for this org" },
+      { status: 404 }
+    );
+  }
+  return NextResponse.json({ billing });
+}
+
+export async function PUT(req: NextRequest) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  if (!canMutate(user)) {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  const body = await req.json().catch(() => null);
+  const parsed = billingSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid input", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+
+  // Company orgs (B2B) require companyName AND VAT. Personal orgs
+  // (B2C — private individuals) need neither; their /settings/billing
+  // form hides both fields and we don't ask the API to enforce them.
+  if (!user.isPersonal) {
+    const missing: Record<string, string[]> = {};
+    if (!parsed.data.companyName || parsed.data.companyName.trim().length === 0) {
+      missing.companyName = ["Required for companies"];
+    }
+    if (!parsed.data.vatNumber) {
+      missing.vatNumber = ["Required for companies"];
+    }
+    if (Object.keys(missing).length > 0) {
+      return NextResponse.json(
+        {
+          error:
+            "Company name and VAT number are required for company accounts.",
+          details: { fieldErrors: missing },
+        },
+        { status: 400 }
+      );
+    }
+  }
+
+  try {
+    const billing = await upsertOrgBilling({
+      zitadelOrgId: user.orgId,
+      companyName: parsed.data.companyName,
+      streetAddress: parsed.data.streetAddress,
+      postalCode: parsed.data.postalCode,
+      city: parsed.data.city,
+      country: parsed.data.country,
+      vatNumber: parsed.data.vatNumber,
+      billingEmail: parsed.data.billingEmail,
+      notes: parsed.data.notes,
+    });
+    return NextResponse.json({ billing });
+  } catch (e: any) {
+    console.error("Failed to upsert org billing:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Failed to save billing") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/onboarding/route.ts

@@ -6,6 +6,8 @@ import {
   listTenantRequestsByOrgId,
   listActiveTenantRequestsByOrgId,
   getMostRecentApprovedRequestForOrg,
+  getOrgBilling,
+  upsertOrgBilling,
 } from "@/lib/db";
 import { getTenant, listTenants } from "@/lib/k8s";
 import {
@@ -16,7 +18,7 @@ import {
 import { sendAdminNotificationEmail } from "@/lib/email";
 import { encryptSecrets } from "@/lib/crypto";
 import { isPersonalOrgName } from "@/lib/personal-org";
-import { onboardingSchema } from "@/lib/validation";
+import { onboardingSchema, billingAddressSchema } from "@/lib/validation";
 import type { OnboardingInput, PiecedTenant, TenantRequest } from "@/types";
 import { z } from "zod";
 
@@ -255,8 +257,137 @@ export async function POST(request: Request) {
   const companyName = prior?.companyName ?? user.orgName;
   const contactName = prior?.contactName ?? user.name;
   const contactEmail = prior?.contactEmail ?? user.email;
-  const billingAddress = prior?.billingAddress ?? input.billingAddress;
-  const billingNotes = input.billingNotes ?? prior?.billingNotes;
+
+  // Bug 35: org-scoped billing.
+  //
+  // Resolution rules:
+  //   1. If org_billing exists, use it (synthesise a BillingAddress
+  //      shape for the audit copy on tenant_requests). Wizard's
+  //      submitted billingAddress is ignored — the org has billing
+  //      on file, the wizard skipped that step.
+  //   2. If no org_billing AND wizard supplied billingAddress, use
+  //      the wizard's data and save to org_billing for next time.
+  //      VAT is enforced by billingAddressSchema (required for
+  //      everyone).
+  //   3. If no org_billing AND no wizard billingAddress: reject.
+  //      Billing is required for all customers regardless of
+  //      personal/company org structure — we're a commercial
+  //      product. Personal accounts (sole proprietors, individuals)
+  //      are still subject to billing capture.
+  //
+  // The synthetic BillingAddress for case 1 collapses fields that
+  // org_billing has more granularly; good enough for audit, since
+  // /settings/billing is the authoritative editor going forward.
+  const orgBilling = await getOrgBilling(user.orgId);
+  let billingAddress: TenantRequest["billingAddress"];
+  let billingNotes = input.billingNotes ?? prior?.billingNotes;
+
+  if (orgBilling) {
+    billingAddress = {
+      company: orgBilling.companyName,
+      street: orgBilling.streetAddress,
+      postalCode: orgBilling.postalCode,
+      city: orgBilling.city,
+      country: orgBilling.country,
+      vatNumber: orgBilling.vatNumber ?? undefined,
+    };
+  } else if (input.billingAddress) {
+    // Wizard supplied billing — re-validate the strict shape (the
+    // outer onboardingSchema marks it optional now, so we can't rely
+    // on its enforcement of the inner required fields).
+    const billingCheck = billingAddressSchema.safeParse(input.billingAddress);
+    if (!billingCheck.success) {
+      return NextResponse.json(
+        {
+          error: "Invalid billing address",
+          details: billingCheck.error.flatten(),
+        },
+        { status: 400 }
+      );
+    }
+
+    // Company orgs (B2B) require companyName AND vatNumber.
+    // Personal orgs (B2C — private individuals) require neither;
+    // the wizard hides both fields for them and the API doesn't
+    // enforce.
+    if (!isPersonal) {
+      const missing: Record<string, string[]> = {};
+      if (
+        !billingCheck.data.company ||
+        billingCheck.data.company.trim().length === 0
+      ) {
+        missing["billingAddress.company"] = ["Required for companies"];
+      }
+      if (
+        !billingCheck.data.vatNumber ||
+        billingCheck.data.vatNumber.length === 0
+      ) {
+        missing["billingAddress.vatNumber"] = ["Required for companies"];
+      }
+      if (Object.keys(missing).length > 0) {
+        return NextResponse.json(
+          {
+            error:
+              "Company name and VAT number are required for company accounts.",
+            details: { fieldErrors: missing },
+          },
+          { status: 400 }
+        );
+      }
+    }
+
+    billingAddress = billingCheck.data;
+
+    // Persist to org_billing. For personal customers (B2C, no
+    // company line), fall back to their display name from the
+    // session — invoices addressed to their actual name rather than
+    // an opaque org id like "personal-3f2a8b1c". For companies the
+    // wizard's company field is filled.
+    const personalDisplayName = (user.name || user.email || "").trim();
+    try {
+      await upsertOrgBilling({
+        zitadelOrgId: user.orgId,
+        companyName:
+          (billingCheck.data.company || "").trim() ||
+          (isPersonal ? personalDisplayName : user.orgName) ||
+          user.orgName,
+        streetAddress: billingCheck.data.street,
+        postalCode: billingCheck.data.postalCode,
+        city: billingCheck.data.city,
+        country: billingCheck.data.country,
+        // Personal: undefined (no VAT). Company: enforced non-empty
+        // by the check above.
+        vatNumber: isPersonal ? null : billingCheck.data.vatNumber!,
+        billingEmail: contactEmail,
+        notes: billingNotes ?? null,
+      });
+    } catch (e) {
+      // Non-fatal — the tenant_request still gets created with the
+      // billingAddress audit copy. The customer can re-save via
+      // /settings/billing if this failed.
+      console.warn(
+        "failed to save org_billing on first capture; tenant_request still created with audit copy",
+        e
+      );
+    }
+  } else {
+    // No billing supplied AND no org_billing record. Required for
+    // everyone — commercial product, no personal-orgs-skip
+    // shortcut. Customer must complete the wizard's billing step
+    // or set up /settings/billing first.
+    return NextResponse.json(
+      {
+        error:
+          "Billing information is required. Please complete the billing step or set it up at /settings/billing.",
+        details: {
+          fieldErrors: {
+            billingAddress: ["Required"],
+          },
+        },
+      },
+      { status: 400 }
+    );
+  }
 
   const tenantRequest = await createTenantRequest({
     zitadelOrgId: user.orgId,

src/components/layout/nav-shell.tsx

@@ -59,6 +59,21 @@ function NavBar() {
                   {t("team")}
                 </NavLink>
               )}
+            {/* Bug 35: /settings is shown to anyone who can mutate org-level
+                state — owners and platform admins. Personal accounts also
+                see it; their billing page is optional but the entry point
+                exists for consistency. `user`-role customers don't see it
+                (canMutate is false). */}
+            {user &&
+              (user.isPlatform ||
+                (Array.isArray(user.roles) && user.roles.includes("owner"))) && (
+                <NavLink
+                  href="/settings"
+                  active={pathname.startsWith("/settings")}
+                >
+                  {t("settings")}
+                </NavLink>
+              )}
             {user?.isPlatform && (
               <NavLink href="/admin" active={pathname === "/admin"}>
                 {t("admin")}

src/components/onboarding/onboarding-flow.tsx

@@ -12,6 +12,13 @@ interface OnboardingFlowProps {
    */
   userName?: string;
   userEmail?: string;
+  /**
+   * Bug 35: true if the org already has a billing record. The wizard
+   * uses this to skip the billing step on subsequent tenants — capture
+   * once at first onboarding, reuse afterwards. Editable later via
+   * /settings/billing.
+   */
+  hasOrgBilling?: boolean;
   /**
    * Bug 6: when present, the wizard is rendered in edit mode against
    * the given pending request. See `OnboardingWizard` for the full
@@ -37,6 +44,7 @@ export function OnboardingFlow({
   orgName,
   userName,
   userEmail,
+  hasOrgBilling,
   editingRequest,
 }: OnboardingFlowProps) {
   const router = useRouter();
@@ -46,6 +54,7 @@ export function OnboardingFlow({
       orgName={orgName}
       userName={userName}
       userEmail={userEmail}
+      hasOrgBilling={hasOrgBilling}
       editingRequest={editingRequest}
       onComplete={() => {
         // Navigate back to /dashboard and re-fetch on the server. The

src/components/onboarding/wizard.tsx

@@ -16,7 +16,26 @@ import {
 
 type Step = "welcome" | "configure" | "billing" | "confirm";
 
-const STEPS: Step[] = ["welcome", "configure", "billing", "confirm"];
+// The step list. Composed once and used to compute "next/prev" arrows
+// and progress indicator. Bug 35: the billing step is conditional —
+// orgs that already have billing on file (subsequent tenants, or
+// pre-filled via /settings/billing) skip it. The wizard's submit
+// payload omits billingAddress in that case; the API picks up the
+// existing org_billing row server-side.
+function makeSteps(opts: {
+  hasOrgBilling: boolean;
+  isEditing: boolean;
+}): Step[] {
+  const base: Step[] = ["welcome", "configure", "billing", "confirm"];
+  // Edit mode currently still shows the billing step because we want
+  // the customer to be able to fix billing on a still-pending request
+  // BEFORE it reaches admin. Once approved, edits go through
+  // /settings/billing instead. Same step set for editing as new for now.
+  if (opts.hasOrgBilling && !opts.isEditing) {
+    return base.filter((s) => s !== "billing");
+  }
+  return base;
+}
 
 // Inline fallbacks — only used if the API call to /api/workspace-defaults fails
 const FALLBACK_SOUL = `# AI Assistant
@@ -64,6 +83,18 @@ interface WizardProps {
    */
   userName?: string;
   userEmail?: string;
+  /**
+   * Bug 35: when true, the wizard skips the billing step. The org
+   * already has billing on file (captured during a previous tenant's
+   * onboarding, or set directly via /settings/billing), and we don't
+   * re-prompt for it. The submit payload omits billingAddress in that
+   * case; the API picks up the existing record server-side.
+   *
+   * In edit mode this is ignored — the wizard re-renders the step
+   * with the request's original billingAddress so the customer can
+   * fix it before admin approves.
+   */
+  hasOrgBilling?: boolean;
   /**
    * Bug 6: when present, the wizard renders in "edit" mode — fields
    * are pre-populated from the request, the SOUL.md auto-fetch is
@@ -90,6 +121,7 @@ interface WizardProps {
       city?: string;
       postalCode?: string;
       country?: string;
+      vatNumber?: string;
     };
     billingNotes: string;
   };
@@ -100,6 +132,7 @@ export function OnboardingWizard({
   orgName,
   userName,
   userEmail,
+  hasOrgBilling,
   editingRequest,
   onComplete,
 }: WizardProps) {
@@ -122,6 +155,13 @@ export function OnboardingWizard({
     isPersonal,
   });
   const isEditing = Boolean(editingRequest);
+  // STEPS is recomputed from props so toggling hasOrgBilling at the
+  // server level (e.g. between renders if the customer just saved
+  // billing on /settings/billing in another tab) flows through. Cheap.
+  const STEPS = makeSteps({
+    hasOrgBilling: Boolean(hasOrgBilling),
+    isEditing,
+  });
 
   // Edit mode jumps straight to the configure step — the welcome step
   // is a first-time onboarding affordance and only adds friction when
@@ -148,6 +188,7 @@ export function OnboardingWizard({
           city: editingRequest.billingAddress.city ?? "",
           postalCode: editingRequest.billingAddress.postalCode ?? "",
           country: editingRequest.billingAddress.country ?? "CH",
+          vatNumber: editingRequest.billingAddress.vatNumber ?? "",
         },
         billingNotes: editingRequest.billingNotes,
       };
@@ -167,6 +208,7 @@ export function OnboardingWizard({
         city: "",
         postalCode: "",
         country: "CH",
+        vatNumber: "",
       },
       billingNotes: "",
     };
@@ -372,11 +414,25 @@ export function OnboardingWizard({
         : "/api/onboarding";
       const method = editingRequest ? "PATCH" : "POST";
 
+      // Bug 35: when the org already has billing on file, the wizard
+      // skipped the billing step and `config.billingAddress` is the
+      // empty default. Strip it from the payload so the API picks up
+      // the existing org_billing record server-side rather than
+      // validating the empty form against billingStepSchema (which
+      // would reject for a company org).
+      const submitConfig = hasOrgBilling
+        ? (() => {
+            const { billingAddress: _bill, billingNotes: _notes, ...rest } =
+              config;
+            return rest;
+          })()
+        : config;
+
       const res = await fetch(url, {
         method,
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-          ...config,
+          ...submitConfig,
           packageSecrets:
             Object.keys(secretsPayload).length > 0
               ? secretsPayload
@@ -906,6 +962,39 @@ export function OnboardingWizard({
               </select>
             </FieldWithError>
 
+            {/* Bug 35: VAT identifier. Required for company customers
+                (B2B). Hidden entirely for personal customers (B2C —
+                private individuals don't have a VAT number); the API
+                enforces the same rule. Editable later via
+                /settings/billing for company customers if their VAT
+                id changes. */}
+            {!isPersonal && (
+              <FieldWithError error={errors["billingAddress.vatNumber"]}>
+                <label className="block text-xs font-semibold uppercase tracking-wider text-text-muted mb-1.5">
+                  {t("billingVatNumber")} <RequiredMark />
+                </label>
+                <input
+                  type="text"
+                  value={config.billingAddress.vatNumber ?? ""}
+                  onChange={(e) => {
+                    clearError("billingAddress.vatNumber");
+                    setConfig((prev) => ({
+                      ...prev,
+                      billingAddress: {
+                        ...prev.billingAddress,
+                        vatNumber: e.target.value,
+                      },
+                    }));
+                  }}
+                  placeholder="CHE-123.456.789 MWST"
+                  className={inputClass(errors["billingAddress.vatNumber"])}
+                />
+                <p className="text-xs text-text-muted mt-1">
+                  {t("billingVatHelp")}
+                </p>
+              </FieldWithError>
+            )}
+
             <div>
               <label className="block text-xs font-semibold uppercase tracking-wider text-text-muted mb-1.5">
                 {t("billingNotes")}
@@ -919,7 +1008,11 @@ export function OnboardingWizard({
                   }))
                 }
                 rows={3}
-                placeholder={t("billingNotesPlaceholder")}
+                placeholder={t(
+                  isPersonal
+                    ? "billingNotesPlaceholderPersonal"
+                    : "billingNotesPlaceholder"
+                )}
                 className="w-full px-3 py-2 bg-surface-2 border border-border rounded-lg text-sm text-text-primary placeholder:text-text-muted focus:outline-none focus:ring-1 focus:ring-accent focus:border-accent transition-colors resize-y"
               />
             </div>
@@ -1024,6 +1117,19 @@ export function OnboardingWizard({
                   </div>
                 }
               />
+              {/* Bug 35: VAT review row. Company customers see this so
+                  they can verify the VAT id they typed before submitting.
+                  Personal customers never see it — they don't have a
+                  VAT number, the form didn't ask, the review hides it. */}
+              {!isPersonal &&
+                config.billingAddress.vatNumber &&
+                config.billingAddress.vatNumber.trim().length > 0 && (
+                  <ReviewRow
+                    label={t("billingVatNumber")}
+                    value={config.billingAddress.vatNumber}
+                    mono
+                  />
+                )}
               <ReviewRow
                 label={t("reviewContactEmail")}
                 value={userEmail || ""}

src/components/settings/billing-settings-form.tsx

@@ -0,0 +1,279 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import type { OrgBilling } from "@/types";
+import { Card } from "@/components/ui/card";
+
+interface Props {
+  /** Existing billing record, or null on first edit. */
+  initial: OrgBilling | null;
+  /**
+   * True if the caller is on a personal org. Personal customers
+   * (B2C — private individuals) don't have a company name or VAT
+   * number; the form re-labels the company-name field as "Full name"
+   * and hides VAT.
+   */
+  isPersonal: boolean;
+  /** Default company name for company orgs on first edit. */
+  orgName: string;
+  /** Default full-name for personal orgs on first edit. */
+  userName: string;
+  /**
+   * Default billing email — the address the user registered with.
+   * Used on first edit (when `initial` is null). Customers can still
+   * type a different address (e.g. accounting@…) but the registration
+   * email is a sensible starting point.
+   */
+  userEmail: string;
+}
+
+/**
+ * Editable billing form. Used by /settings/billing; the wizard's
+ * inline billing step (Bug 35 phase 2) reuses the same shape but is
+ * implemented separately because of its different submit semantics
+ * (one combined wizard submit, vs. this page's standalone PUT).
+ *
+ * The form does NOT do client-side VAT format validation — too many
+ * country variations to get right, and the API will reject empty
+ * VAT for company orgs anyway. The asterisk on the field plus the
+ * server error suffices.
+ */
+export function BillingSettingsForm({
+  initial,
+  isPersonal,
+  orgName,
+  userName,
+  userEmail,
+}: Props) {
+  const t = useTranslations("settingsBilling");
+  const tCommon = useTranslations("common");
+  const router = useRouter();
+
+  const [companyName, setCompanyName] = useState(
+    initial?.companyName ?? (isPersonal ? userName : orgName)
+  );
+  const [streetAddress, setStreetAddress] = useState(
+    initial?.streetAddress ?? ""
+  );
+  const [postalCode, setPostalCode] = useState(initial?.postalCode ?? "");
+  const [city, setCity] = useState(initial?.city ?? "");
+  const [country, setCountry] = useState(initial?.country ?? "CH");
+  const [vatNumber, setVatNumber] = useState(initial?.vatNumber ?? "");
+  // Default billing email to the user's registration email when no
+  // record exists yet. They can change it (a separate accounting
+  // address is common); we just want sensible pre-fill on first edit.
+  const [billingEmail, setBillingEmail] = useState(
+    initial?.billingEmail ?? userEmail ?? ""
+  );
+  const [notes, setNotes] = useState(initial?.notes ?? "");
+
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+  const [success, setSuccess] = useState(false);
+
+  const onSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setSubmitting(true);
+    setError("");
+    setSuccess(false);
+    try {
+      const res = await fetch("/api/billing", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          companyName,
+          streetAddress,
+          postalCode,
+          city,
+          country,
+          vatNumber: vatNumber.trim() || null,
+          billingEmail,
+          notes: notes.trim() || null,
+        }),
+      });
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        throw new Error(data.error || t("saveFailed"));
+      }
+      setSuccess(true);
+      // Refresh server props so the form re-renders with the saved
+      // record's timestamps. Subtle but useful: the "last updated"
+      // line below ticks forward.
+      router.refresh();
+    } catch (e: any) {
+      setError(e.message);
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <Card className="animate-in animate-in-delay-1">
+      <form onSubmit={onSubmit} className="space-y-4">
+        {/* Bug 35: this field stores `company_name` in the DB but
+            the label changes by customer type:
+              - Company (B2B): "Company name" — the legal entity.
+              - Personal (B2C): "Full name" — the individual's
+                invoice name (may differ from their session display
+                name; e.g. legal name vs friendly name).
+            Required for both. The DB column is NOT NULL either way. */}
+        <div>
+          <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+            {isPersonal ? t("fullName") : t("companyName")}{" "}
+            <span className="text-red-400">*</span>
+          </label>
+          <input
+            type="text"
+            required
+            value={companyName}
+            onChange={(e) => setCompanyName(e.target.value)}
+            className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+          />
+        </div>
+
+        <div>
+          <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+            {t("streetAddress")} <span className="text-red-400">*</span>
+          </label>
+          <input
+            type="text"
+            required
+            value={streetAddress}
+            onChange={(e) => setStreetAddress(e.target.value)}
+            className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+          />
+        </div>
+
+        <div className="grid grid-cols-1 sm:grid-cols-3 gap-3">
+          <div>
+            <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+              {t("postalCode")} <span className="text-red-400">*</span>
+            </label>
+            <input
+              type="text"
+              required
+              value={postalCode}
+              onChange={(e) => setPostalCode(e.target.value)}
+              className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+            />
+          </div>
+          <div className="sm:col-span-2">
+            <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+              {t("city")} <span className="text-red-400">*</span>
+            </label>
+            <input
+              type="text"
+              required
+              value={city}
+              onChange={(e) => setCity(e.target.value)}
+              className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+            />
+          </div>
+        </div>
+
+        <div>
+          <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+            {t("country")} <span className="text-red-400">*</span>
+          </label>
+          <select
+            required
+            value={country}
+            onChange={(e) => setCountry(e.target.value)}
+            className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+          >
+            <option value="CH">Switzerland</option>
+            <option value="LI">Liechtenstein</option>
+            <option value="DE">Germany</option>
+            <option value="AT">Austria</option>
+            <option value="FR">France</option>
+            <option value="IT">Italy</option>
+          </select>
+        </div>
+
+        {/* Bug 35: VAT visible only for company customers (B2B).
+            Personal customers (B2C — private individuals) don't have
+            a VAT number; the API likewise doesn't require one for
+            them. */}
+        {!isPersonal && (
+          <div>
+            <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+              {t("vatNumber")} <span className="text-red-400">*</span>
+            </label>
+            <input
+              type="text"
+              required
+              value={vatNumber}
+              onChange={(e) => setVatNumber(e.target.value)}
+              placeholder="CHE-123.456.789 MWST"
+              className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+            />
+            <p className="text-xs text-text-muted mt-1">{t("vatHelp")}</p>
+          </div>
+        )}
+
+        <div>
+          <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+            {t("billingEmail")} <span className="text-red-400">*</span>
+          </label>
+          <input
+            type="email"
+            required
+            value={billingEmail}
+            onChange={(e) => setBillingEmail(e.target.value)}
+            placeholder="invoices@example.com"
+            className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+          />
+          <p className="text-xs text-text-muted mt-1">{t("billingEmailHelp")}</p>
+        </div>
+
+        <div>
+          <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+            {t("notes")}{" "}
+            <span className="text-text-muted normal-case">
+              ({tCommon("optional")})
+            </span>
+          </label>
+          <textarea
+            value={notes}
+            onChange={(e) => setNotes(e.target.value)}
+            rows={3}
+            className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+            placeholder={t(
+              isPersonal ? "notesPlaceholderPersonal" : "notesPlaceholder"
+            )}
+          />
+        </div>
+
+        {error && (
+          <div className="text-xs text-red-400 bg-red-400/10 border border-red-400/20 rounded-lg px-3 py-2">
+            {error}
+          </div>
+        )}
+        {success && !error && (
+          <div className="text-xs text-success bg-success/10 border border-success/20 rounded-lg px-3 py-2">
+            {t("saved")}
+          </div>
+        )}
+
+        <div className="flex items-center justify-between gap-3">
+          {initial?.updatedAt && (
+            <div className="text-xs text-text-muted">
+              {t("lastUpdated", {
+                when: new Date(initial.updatedAt).toLocaleString(),
+              })}
+            </div>
+          )}
+          <button
+            type="submit"
+            disabled={submitting}
+            className="ml-auto text-sm font-medium px-4 py-2 rounded-lg bg-accent text-white hover:bg-accent/90 transition-colors disabled:opacity-50"
+          >
+            {submitting ? tCommon("loading") : t("save")}
+          </button>
+        </div>
+      </form>
+    </Card>
+  );
+}

src/lib/db.ts

@@ -1,5 +1,5 @@
 import { Pool } from "pg";
-import type { BillingAddress, TenantRequest, TenantRequestStatus } from "@/types";
+import type { BillingAddress, OrgBilling, TenantRequest, TenantRequestStatus } from "@/types";
 import { listTenants, getTenant } from "./k8s";
 
 // ---------------------------------------------------------------------------
@@ -161,6 +161,35 @@ const MIGRATION_SQL = `
   );
   CREATE INDEX IF NOT EXISTS idx_tua_user ON tenant_user_assignments(zitadel_user_id);
   CREATE INDEX IF NOT EXISTS idx_tua_org  ON tenant_user_assignments(zitadel_org_id);
+
+  -- Bug 35: org-scoped billing. One row per ZITADEL org; captured by
+  -- the first tenant request inline, editable afterwards via
+  -- /settings/billing. Subsequent tenant requests in the same org read
+  -- this and skip the billing step entirely.
+  --
+  -- vat_number is nullable: required at write time for company orgs
+  -- (enforced by the API, not the schema, because "company-or-personal"
+  -- isn't expressible as a column constraint). Notes is free-form
+  -- accounting context — VAT exemption reasons, special invoicing
+  -- arrangements, etc.
+  --
+  -- We do NOT migrate data from tenant_requests.billing_address into
+  -- this table automatically. Existing customers re-enter on next
+  -- tenant or via settings — the data set is small (single-digit
+  -- customers in pilot) and re-entering is the simplest path.
+  CREATE TABLE IF NOT EXISTS org_billing (
+    zitadel_org_id   TEXT PRIMARY KEY,
+    company_name     TEXT NOT NULL,
+    street_address   TEXT NOT NULL,
+    postal_code      TEXT NOT NULL,
+    city             TEXT NOT NULL,
+    country          TEXT NOT NULL,
+    vat_number       TEXT,
+    billing_email    TEXT NOT NULL,
+    notes            TEXT,
+    created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at       TIMESTAMPTZ NOT NULL DEFAULT now()
+  );
 `;
 
 let migrated = false;
@@ -788,6 +817,88 @@ function mapRow(row: any): TenantRequest {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Bug 35: org-scoped billing
+// ---------------------------------------------------------------------------
+
+function rowToOrgBilling(row: any): OrgBilling {
+  return {
+    zitadelOrgId: row.zitadel_org_id,
+    companyName: row.company_name,
+    streetAddress: row.street_address,
+    postalCode: row.postal_code,
+    city: row.city,
+    country: row.country,
+    vatNumber: row.vat_number ?? null,
+    billingEmail: row.billing_email,
+    notes: row.notes ?? null,
+    createdAt: row.created_at?.toISOString?.() ?? row.created_at,
+    updatedAt: row.updated_at?.toISOString?.() ?? row.updated_at,
+  };
+}
+
+/**
+ * Fetch org billing if it exists. Returns null when the org has never
+ * captured billing — that's the signal the wizard uses to know
+ * whether to render the inline billing step on the first tenant
+ * request.
+ */
+export async function getOrgBilling(
+  zitadelOrgId: string
+): Promise<OrgBilling | null> {
+  await ensureSchema();
+  const result = await getPool().query(
+    "SELECT * FROM org_billing WHERE zitadel_org_id = $1",
+    [zitadelOrgId]
+  );
+  return result.rows.length > 0 ? rowToOrgBilling(result.rows[0]) : null;
+}
+
+/**
+ * Insert or update org billing. Single function for both because the
+ * UI flow makes the "first time vs editing" distinction in a single
+ * settings page that doesn't need to know which one it's doing.
+ *
+ * VAT-required-for-companies isn't enforced here — that's an API
+ * concern (the API knows whether the caller is a company org).
+ * Keeping the DB layer dumb.
+ */
+export async function upsertOrgBilling(
+  data: Omit<OrgBilling, "createdAt" | "updatedAt">
+): Promise<OrgBilling> {
+  await ensureSchema();
+  const result = await getPool().query(
+    `INSERT INTO org_billing (
+       zitadel_org_id, company_name, street_address, postal_code,
+       city, country, vat_number, billing_email, notes
+     )
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+     ON CONFLICT (zitadel_org_id) DO UPDATE SET
+       company_name   = EXCLUDED.company_name,
+       street_address = EXCLUDED.street_address,
+       postal_code    = EXCLUDED.postal_code,
+       city           = EXCLUDED.city,
+       country        = EXCLUDED.country,
+       vat_number     = EXCLUDED.vat_number,
+       billing_email  = EXCLUDED.billing_email,
+       notes          = EXCLUDED.notes,
+       updated_at     = now()
+     RETURNING *`,
+    [
+      data.zitadelOrgId,
+      data.companyName,
+      data.streetAddress,
+      data.postalCode,
+      data.city,
+      data.country,
+      data.vatNumber ?? null,
+      data.billingEmail,
+      data.notes ?? null,
+    ]
+  );
+  return rowToOrgBilling(result.rows[0]);
+}
+
 // ---------------------------------------------------------------------------
 // Slice 6: tenant ↔ user assignments
 // ---------------------------------------------------------------------------

src/lib/validation.ts

@@ -86,6 +86,13 @@ export const billingAddressSchema = z
     country: z.enum(SUPPORTED_COUNTRIES, {
       message: "Please choose a country from the list",
     }),
+    // Bug 35: VAT identifier. Required for company customers (B2B);
+    // omitted entirely for personal customers (B2C — private
+    // individuals don't have a VAT number). The schema marks it
+    // optional because the same schema is used for both flows;
+    // company-vs-personal enforcement happens at the API layer where
+    // `user.isPersonal` is known.
+    vatNumber: z.string().trim().max(50).optional(),
   })
   .superRefine((data, ctx) => {
     const pattern = POSTAL_CODE_PATTERNS[data.country];
@@ -123,6 +130,12 @@ export const billingStepSchema = z.object({
  * Full onboarding payload. Used by the API route and by the wizard's
  * submit handler. `packageSecrets` is a free-shape map that gets
  * encrypted by the server before it touches the DB.
+ *
+ * Bug 35: `billingAddress` is now optional at the schema level. The
+ * wizard omits it entirely when the org already has an `org_billing`
+ * record. The API enforces "billing must exist by the end" by either
+ * looking up the existing org_billing row OR validating the supplied
+ * payload — neither path can be skipped without a 400.
  */
 export const onboardingSchema = z.object({
   instanceName: z
@@ -139,7 +152,7 @@ export const onboardingSchema = z.object({
   packageSecrets: z
     .record(z.string(), z.record(z.string(), z.string()))
     .optional(),
-  billingAddress: billingAddressSchema,
+  billingAddress: billingAddressSchema.optional(),
   billingNotes: z.string().max(2_000).optional(),
 });
 

src/messages/de.json

@@ -12,7 +12,9 @@
     "save": "Speichern",
     "error": "Ein Fehler ist aufgetreten",
     "register": "Registrieren",
-    "team": "Team"
+    "team": "Team",
+    "settings": "Einstellungen",
+    "optional": "optional"
   },
   "login": {
     "title": "PieCed Portal",
@@ -114,7 +116,10 @@
     "dismiss": "Ausblenden",
     "dismissFailed": "Konnte nicht ausgeblendet werden.",
     "rejectionReason": "Angegebener Grund",
-    "saveChanges": "Änderungen speichern"
+    "saveChanges": "Änderungen speichern",
+    "billingVatNumber": "MWST-Nummer",
+    "billingVatHelp": "Ihre registrierte MWST-Nummer. Falls Ihre Firma von der MWST befreit ist, leer lassen und in den Notizen erläutern.",
+    "billingNotesPlaceholderPersonal": "Was wir wissen sollten — bevorzugte Zahlungsart, Rechnungsreferenz, etc."
   },
   "dashboard": {
     "title": "Dashboard",
@@ -379,5 +384,34 @@
   "warnings": {
     "oneTooltip": "1 Warnung",
     "manyTooltip": "{count} Warnungen"
+  },
+  "settings": {
+    "title": "Einstellungen",
+    "subtitle": "Organisationsweite Konfiguration, die für alle Ihre Tenants gilt.",
+    "billingTitle": "Abrechnung",
+    "billingDescription": "Adresse, MWST-Nummer und Rechnungs-E-Mail für alle Ihre Tenants.",
+    "nothingForYou": "Für Ihre Rolle gibt es hier noch nichts. Inhaber können Organisationseinstellungen verwalten.",
+    "billingDescriptionPersonal": "Adresse und Rechnungs-E-Mail für alle Ihre Tenants."
+  },
+  "settingsBilling": {
+    "title": "Abrechnung",
+    "subtitle": "Wird beim ersten Onboarding einmalig erfasst und für jeden Tenant Ihrer Organisation wiederverwendet. Aktualisieren Sie hier, wenn sich Ihre Abrechnungsdaten ändern.",
+    "companyName": "Firmenname",
+    "streetAddress": "Strasse",
+    "postalCode": "PLZ",
+    "city": "Ort",
+    "country": "Land",
+    "vatNumber": "MWST-Nummer",
+    "vatHelp": "Ihre registrierte MWST-Nummer (z. B. CHE-123.456.789 MWST für die Schweiz).",
+    "billingEmail": "Rechnungs-E-Mail",
+    "billingEmailHelp": "An diese Adresse werden Rechnungen und Abrechnungskommunikation gesendet.",
+    "notes": "Notizen",
+    "notesPlaceholder": "Alles, was die Buchhaltung wissen muss – MWST-Befreiung, besondere Rechnungsstellung usw.",
+    "save": "Speichern",
+    "saved": "Gespeichert.",
+    "saveFailed": "Konnte nicht gespeichert werden. Bitte erneut versuchen.",
+    "lastUpdated": "Zuletzt aktualisiert {when}",
+    "fullName": "Voller Name",
+    "notesPlaceholderPersonal": "Was wir wissen sollten — bevorzugte Zahlungsart, Rechnungsreferenz, etc."
   }
 }

src/messages/en.json

@@ -12,7 +12,9 @@
     "save": "Save",
     "error": "An error occurred",
     "register": "Register",
-    "team": "Team"
+    "team": "Team",
+    "settings": "Settings",
+    "optional": "optional"
   },
   "login": {
     "title": "PieCed Portal",
@@ -114,7 +116,10 @@
     "dismiss": "Dismiss",
     "dismissFailed": "Could not dismiss.",
     "rejectionReason": "Reason given",
-    "saveChanges": "Save changes"
+    "saveChanges": "Save changes",
+    "billingVatNumber": "VAT number",
+    "billingVatHelp": "Your registered VAT identifier. If your company is VAT-exempt, leave blank and explain in the notes field.",
+    "billingNotesPlaceholderPersonal": "Anything we should know — preferred payment method, billing reference, etc."
   },
   "dashboard": {
     "title": "Dashboard",
@@ -379,5 +384,34 @@
   "warnings": {
     "oneTooltip": "1 warning",
     "manyTooltip": "{count} warnings"
+  },
+  "settings": {
+    "title": "Settings",
+    "subtitle": "Manage org-level configuration that applies to all your tenants.",
+    "billingTitle": "Billing",
+    "billingDescription": "Address, VAT number, and invoice email used for all your tenants.",
+    "nothingForYou": "There's nothing here for your role yet. Owners can manage org settings.",
+    "billingDescriptionPersonal": "Address and invoice email used for all your tenants."
+  },
+  "settingsBilling": {
+    "title": "Billing",
+    "subtitle": "Captured once at first onboarding and reused for every tenant in your organization. Update here whenever your billing details change.",
+    "companyName": "Company name",
+    "streetAddress": "Street address",
+    "postalCode": "Postal code",
+    "city": "City",
+    "country": "Country",
+    "vatNumber": "VAT number",
+    "vatHelp": "Your registered VAT identifier (e.g. CHE-123.456.789 MWST for Switzerland).",
+    "billingEmail": "Billing email",
+    "billingEmailHelp": "Where invoices and billing communication will be sent.",
+    "notes": "Notes",
+    "notesPlaceholder": "Anything else accounting needs to know — VAT exemption, special invoicing arrangements, etc.",
+    "save": "Save",
+    "saved": "Saved.",
+    "saveFailed": "Could not save. Please try again.",
+    "lastUpdated": "Last updated {when}",
+    "fullName": "Full name",
+    "notesPlaceholderPersonal": "Anything we should know — preferred payment method, billing reference, etc."
   }
 }

src/messages/fr.json

@@ -12,7 +12,9 @@
     "save": "Enregistrer",
     "error": "Une erreur est survenue",
     "register": "S'inscrire",
-    "team": "Équipe"
+    "team": "Équipe",
+    "settings": "Paramètres",
+    "optional": "facultatif"
   },
   "login": {
     "title": "Portail PieCed",
@@ -114,7 +116,10 @@
     "dismiss": "Masquer",
     "dismissFailed": "Impossible de masquer.",
     "rejectionReason": "Motif indiqué",
-    "saveChanges": "Enregistrer les modifications"
+    "saveChanges": "Enregistrer les modifications",
+    "billingVatNumber": "Numéro de TVA",
+    "billingVatHelp": "Votre identifiant TVA enregistré. Si votre entreprise est exonérée de TVA, laissez vide et précisez dans les notes.",
+    "billingNotesPlaceholderPersonal": "Tout ce que nous devons savoir — moyen de paiement préféré, référence de facturation, etc."
   },
   "dashboard": {
     "title": "Tableau de bord",
@@ -379,5 +384,34 @@
   "warnings": {
     "oneTooltip": "1 avertissement",
     "manyTooltip": "{count} avertissements"
+  },
+  "settings": {
+    "title": "Paramètres",
+    "subtitle": "Gérez la configuration au niveau de l'organisation, qui s'applique à tous vos locataires.",
+    "billingTitle": "Facturation",
+    "billingDescription": "Adresse, numéro de TVA et e-mail de facturation utilisés pour tous vos locataires.",
+    "nothingForYou": "Il n'y a rien ici pour votre rôle pour le moment. Les propriétaires peuvent gérer les paramètres de l'organisation.",
+    "billingDescriptionPersonal": "Adresse et e-mail de facturation utilisés pour tous vos locataires."
+  },
+  "settingsBilling": {
+    "title": "Facturation",
+    "subtitle": "Saisie une fois lors de l'inscription et réutilisée pour chaque locataire de votre organisation. Mettez à jour ici dès que vos coordonnées de facturation changent.",
+    "companyName": "Nom de l'entreprise",
+    "streetAddress": "Adresse",
+    "postalCode": "Code postal",
+    "city": "Ville",
+    "country": "Pays",
+    "vatNumber": "Numéro de TVA",
+    "vatHelp": "Votre identifiant TVA enregistré (par ex. CHE-123.456.789 TVA pour la Suisse).",
+    "billingEmail": "E-mail de facturation",
+    "billingEmailHelp": "Adresse à laquelle les factures et la communication de facturation seront envoyées.",
+    "notes": "Notes",
+    "notesPlaceholder": "Tout ce que la comptabilité doit savoir – exonération de TVA, modalités de facturation particulières, etc.",
+    "save": "Enregistrer",
+    "saved": "Enregistré.",
+    "saveFailed": "Impossible d'enregistrer. Veuillez réessayer.",
+    "lastUpdated": "Dernière mise à jour {when}",
+    "fullName": "Nom complet",
+    "notesPlaceholderPersonal": "Tout ce que nous devons savoir — moyen de paiement préféré, référence de facturation, etc."
   }
 }

src/messages/it.json

@@ -12,7 +12,9 @@
     "save": "Salva",
     "error": "Si è verificato un errore",
     "register": "Registrati",
-    "team": "Team"
+    "team": "Team",
+    "settings": "Impostazioni",
+    "optional": "facoltativo"
   },
   "login": {
     "title": "Portale PieCed",
@@ -114,7 +116,10 @@
     "dismiss": "Nascondi",
     "dismissFailed": "Impossibile nascondere.",
     "rejectionReason": "Motivo indicato",
-    "saveChanges": "Salva modifiche"
+    "saveChanges": "Salva modifiche",
+    "billingVatNumber": "Partita IVA",
+    "billingVatHelp": "Il tuo identificativo IVA registrato. Se la tua azienda è esente IVA, lascia vuoto e spiega nelle note.",
+    "billingNotesPlaceholderPersonal": "Qualsiasi cosa dovremmo sapere — metodo di pagamento preferito, riferimento per fatturazione, ecc."
   },
   "dashboard": {
     "title": "Dashboard",
@@ -379,5 +384,34 @@
   "warnings": {
     "oneTooltip": "1 avviso",
     "manyTooltip": "{count} avvisi"
+  },
+  "settings": {
+    "title": "Impostazioni",
+    "subtitle": "Gestisci la configurazione a livello di organizzazione, valida per tutti i tuoi tenant.",
+    "billingTitle": "Fatturazione",
+    "billingDescription": "Indirizzo, numero di IVA ed e-mail di fatturazione usati per tutti i tuoi tenant.",
+    "nothingForYou": "Al momento non c'è nulla qui per il tuo ruolo. I proprietari possono gestire le impostazioni dell'organizzazione.",
+    "billingDescriptionPersonal": "Indirizzo ed e-mail di fatturazione usati per tutti i tuoi tenant."
+  },
+  "settingsBilling": {
+    "title": "Fatturazione",
+    "subtitle": "Acquisita una sola volta al primo onboarding e riutilizzata per ogni tenant della tua organizzazione. Aggiorna qui ogni volta che i dati di fatturazione cambiano.",
+    "companyName": "Ragione sociale",
+    "streetAddress": "Indirizzo",
+    "postalCode": "CAP",
+    "city": "Città",
+    "country": "Paese",
+    "vatNumber": "Partita IVA",
+    "vatHelp": "Il tuo identificativo IVA registrato (es. CHE-123.456.789 IVA per la Svizzera).",
+    "billingEmail": "E-mail di fatturazione",
+    "billingEmailHelp": "Indirizzo a cui verranno inviate le fatture e le comunicazioni di fatturazione.",
+    "notes": "Note",
+    "notesPlaceholder": "Qualsiasi cosa la contabilità debba sapere — esenzione IVA, modalità di fatturazione particolari, ecc.",
+    "save": "Salva",
+    "saved": "Salvato.",
+    "saveFailed": "Impossibile salvare. Riprova.",
+    "lastUpdated": "Ultimo aggiornamento {when}",
+    "fullName": "Nome completo",
+    "notesPlaceholderPersonal": "Qualsiasi cosa dovremmo sapere — metodo di pagamento preferito, riferimento per fatturazione, ecc."
   }
 }

src/types/index.ts

@@ -196,6 +196,41 @@ export interface BillingAddress {
   city?: string;
   postalCode?: string;
   country?: string;
+  /**
+   * VAT identifier. Required for new submissions (Bug 35); older
+   * tenant_requests rows in the audit table may have this absent.
+   */
+  vatNumber?: string;
+}
+
+/**
+ * Org-scoped billing record (Bug 35). One per ZITADEL org. Captured
+ * during the first tenant request, editable afterwards via the
+ * /settings/billing page. All future tenant requests in the same org
+ * reuse this without prompting again.
+ *
+ * Personal orgs (`isPersonal=true` in their context) currently don't
+ * fill this in — the wizard skips the step and the onboarding
+ * endpoint doesn't enforce it. If they later want billing on file
+ * (e.g. for invoices), they can fill the settings page manually.
+ *
+ * `vatNumber` is required for company orgs at write time, optional
+ * for personal. The API enforces this; the type itself keeps it
+ * optional because it's nullable in the DB and may be unset for
+ * personal orgs.
+ */
+export interface OrgBilling {
+  zitadelOrgId: string;
+  companyName: string;
+  streetAddress: string;
+  postalCode: string;
+  city: string;
+  country: string;
+  vatNumber?: string | null;
+  billingEmail: string;
+  notes?: string | null;
+  createdAt: string;
+  updatedAt: string;
 }
 
 export type TenantRequestStatus =
@@ -277,6 +312,13 @@ export interface OnboardingInput {
   soulMd?: string;
   agentsMd?: string;
   packages?: string[];
-  billingAddress: BillingAddress;
+  /**
+   * Bug 35: optional at the type level because the wizard skips the
+   * billing step entirely when the org already has an `org_billing`
+   * record. The onboarding API enforces "billing must be resolved by
+   * the end" — either from `org_billing` lookup or from this field —
+   * via runtime checks; the type just allows both paths.
+   */
+  billingAddress?: BillingAddress;
   billingNotes?: string;
 }