Phase7b: Manual Invoice

src/app/[locale]/admin/billing/invoice-drafts/[id]/page.tsx

@@ -0,0 +1,59 @@
+import { notFound, redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { getInvoiceDraftById, getOrgBilling } from "@/lib/db";
+import { BackLink } from "@/components/ui/back-link";
+import { CustomInvoiceEditor } from "@/components/admin/billing/custom-invoice-editor";
+
+/**
+ * /admin/billing/invoice-drafts/[id] — full editor for an
+ * in-progress custom invoice.
+ *
+ * Phase 8. Server-loads the draft + the org's billing snapshot
+ * (used to display the bill-to block preview), then hands off to
+ * the client editor for the interactive line-management UI.
+ *
+ * The snapshot is loaded read-only for display. The actual VAT
+ * computation happens server-side at issue time via
+ * computeCustomInvoiceTotals, which re-reads the same snapshot.
+ * That two-time read is intentional: the editor's preview math
+ * is a hint, the issue-time read is authoritative — if the
+ * customer updates their billing address between Draft and Issue,
+ * the invoice reflects the new address.
+ */
+export default async function InvoiceDraftEditorPage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (!user.isPlatform) redirect("/dashboard");
+  const t = await getTranslations("adminBilling");
+
+  const { id } = await params;
+  const draft = await getInvoiceDraftById(id);
+  if (!draft) notFound();
+  const orgBilling = await getOrgBilling(draft.zitadelOrgId).catch(() => null);
+
+  return (
+    <main className="max-w-5xl mx-auto px-6 py-8">
+      <BackLink
+        href="/admin/billing/invoice-drafts"
+        label={t("backToDrafts")}
+      />
+      <div className="mb-6">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("editorPageTitle")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">
+          {orgBilling?.companyName ?? draft.zitadelOrgId}
+        </p>
+      </div>
+      <CustomInvoiceEditor
+        draft={draft}
+        orgBilling={orgBilling}
+      />
+    </main>
+  );
+}

src/app/[locale]/admin/billing/invoice-drafts/page.tsx

@@ -0,0 +1,72 @@
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { getOrgBilling, listAllInvoiceDrafts } from "@/lib/db";
+import { listTenants } from "@/lib/k8s";
+import { BackLink } from "@/components/ui/back-link";
+import { DraftList } from "@/components/admin/billing/draft-list";
+
+/**
+ * /admin/billing/invoice-drafts — list of all open custom-invoice
+ * drafts across orgs.
+ *
+ * Phase 8. Each draft is a JSONB blob the admin is composing into
+ * an invoice; visible only to platform admins. From here the admin
+ * can resume editing or discard.
+ *
+ * Building an org-name map by reading tenant labels (for the set of
+ * known orgs) + getOrgBilling per org (for the actual company name)
+ * so the table can show "Customer X" instead of a raw ZITADEL org id.
+ */
+export default async function AdminInvoiceDraftsPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (!user.isPlatform) redirect("/dashboard");
+  const t = await getTranslations("adminBilling");
+
+  const [drafts, tenants] = await Promise.all([
+    listAllInvoiceDrafts(),
+    listTenants().catch(() => []),
+  ]);
+
+  // Build the set of distinct ZITADEL org ids from tenant labels,
+  // PLUS the set referenced by any current draft. Drafts may target
+  // orgs that don't have tenants yet (rare but possible), so we
+  // union both sources before fetching billing rows.
+  const orgIds = new Set<string>();
+  for (const tnt of tenants) {
+    const oid = tnt.metadata.labels?.["pieced.ch/zitadel-org-id"];
+    if (oid) orgIds.add(oid);
+  }
+  for (const d of drafts) {
+    orgIds.add(d.zitadelOrgId);
+  }
+  // Look up billing in parallel — same pattern as
+  // /api/admin/billing/orgs uses. Failure for any single org is
+  // non-fatal (falls back to the raw id in the table).
+  const orgNamePairs = await Promise.all(
+    Array.from(orgIds).map(async (oid) => {
+      const billing = await getOrgBilling(oid).catch(() => null);
+      return [oid, billing?.companyName ?? null] as const;
+    })
+  );
+  const orgNameMap: Record<string, string> = {};
+  for (const [oid, name] of orgNamePairs) {
+    if (name) orgNameMap[oid] = name;
+  }
+
+  return (
+    <main className="max-w-5xl mx-auto px-6 py-8">
+      <BackLink href="/admin/billing" label={t("backToBilling")} />
+      <div className="mb-6">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("draftsPageTitle")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">
+          {t("draftsPageSubtitle")}
+        </p>
+      </div>
+      <DraftList drafts={drafts} orgNameMap={orgNameMap} />
+    </main>
+  );
+}

src/app/[locale]/admin/billing/invoices/[id]/page.tsx

@@ -1,7 +1,7 @@
 import { notFound, redirect } from "next/navigation";
 import { getTranslations } from "next-intl/server";
 import { getSessionUser } from "@/lib/session";
-import { getInvoiceDetail } from "@/lib/db";
+import { getInvoiceDetail, listCreditNotesForInvoice } from "@/lib/db";
 import { BackLink } from "@/components/ui/back-link";
 import { InvoiceDetailView } from "@/components/admin/billing/invoice-detail-view";
 
@@ -9,8 +9,12 @@ import { InvoiceDetailView } from "@/components/admin/billing/invoice-detail-vie
  * /admin/billing/invoices/[id] — full detail of one invoice.
  *
  * Server-renders the static body (header, lines, totals, billing
- * snapshot); the action bar (mark-paid, delete, PDF download) is
- * a client component for the interactive bits.
+ * snapshot); the action bar (mark-paid, void, refund, delete, PDF
+ * download) is a client component for the interactive bits.
+ *
+ * Phase 7: also passes any linked credit notes so the detail view
+ * can show the "this invoice was voided / partially refunded" panel
+ * without an extra round-trip.
  */
 export default async function AdminInvoiceDetailPage({
   params,
@@ -25,11 +29,12 @@ export default async function AdminInvoiceDetailPage({
   const { id } = await params;
   const detail = await getInvoiceDetail(id);
   if (!detail) notFound();
+  const creditNotes = await listCreditNotesForInvoice(id);
 
   return (
     <main className="max-w-4xl mx-auto px-6 py-8">
       <BackLink href="/admin/billing/invoices" label={t("backToInvoices")} />
-      <InvoiceDetailView detail={detail} />
+      <InvoiceDetailView detail={detail} creditNotes={creditNotes} />
     </main>
   );
 }

src/app/[locale]/admin/billing/invoices/new/page.tsx

@@ -0,0 +1,72 @@
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { listTenants } from "@/lib/k8s";
+import { getOrgBilling } from "@/lib/db";
+import { BackLink } from "@/components/ui/back-link";
+import { NewInvoiceForm } from "@/components/admin/billing/new-invoice-form";
+
+/**
+ * /admin/billing/invoices/new — entry point for the custom-invoice
+ * flow. The admin picks an org, clicks Continue, and lands on the
+ * editor at /admin/billing/invoice-drafts/<new-id>.
+ *
+ * Phase 8. Org list is built from tenant labels + each org's
+ * billing config (we need the company name and the
+ * has-billing-snapshot flag to gate the picker — orgs without a
+ * snapshot can't be invoiced until they complete onboarding or
+ * admin sets the billing info manually).
+ */
+export default async function NewInvoicePage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (!user.isPlatform) redirect("/dashboard");
+  const t = await getTranslations("adminBilling");
+
+  // Tenants give us org membership; getOrgBilling per org gives us
+  // the snapshot status. We dedupe by org id since one org can own
+  // many tenants.
+  const tenants = await listTenants();
+  const orgIds = new Set<string>();
+  for (const tnt of tenants) {
+    const oid = tnt.metadata.labels?.["pieced.ch/zitadel-org-id"];
+    if (oid) orgIds.add(oid);
+  }
+  const orgs = await Promise.all(
+    Array.from(orgIds).map(async (oid) => {
+      const billing = await getOrgBilling(oid).catch(() => null);
+      return {
+        zitadelOrgId: oid,
+        companyName: billing?.companyName ?? null,
+        country: billing?.country ?? null,
+        hasBillingAddress: !!billing && !!billing.companyName,
+      };
+    })
+  );
+  // Sort: orgs with billing first (admin's most likely target),
+  // then alphabetically by company name.
+  orgs.sort((a, b) => {
+    if (a.hasBillingAddress !== b.hasBillingAddress) {
+      return a.hasBillingAddress ? -1 : 1;
+    }
+    return (a.companyName ?? "").localeCompare(b.companyName ?? "");
+  });
+
+  return (
+    <main className="max-w-2xl mx-auto px-6 py-8">
+      <BackLink
+        href="/admin/billing/invoices"
+        label={t("backToInvoices")}
+      />
+      <div className="mb-6">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("newInvoicePageTitle")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">
+          {t("newInvoicePageSubtitle")}
+        </p>
+      </div>
+      <NewInvoiceForm orgs={orgs} />
+    </main>
+  );
+}

src/app/[locale]/admin/cron/page.tsx

@@ -0,0 +1,44 @@
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import {
+  getLastSuccessfulCronRuns,
+  listRecentCronRuns,
+} from "@/lib/db";
+import { CronControls } from "@/components/admin/cron/cron-controls";
+
+/**
+ * /admin/cron — automation dashboard.
+ *
+ * Shows:
+ *   - Last successful run of each kind, with relative time
+ *   - Two "Run now" buttons (admin-triggered manual sweeps)
+ *   - Recent runs table (last 30)
+ *
+ * Platform-admin gated server-side.
+ */
+export default async function AdminCronPage() {
+  const user = await getSessionUser();
+  if (!user || !user.isPlatform) redirect("/login");
+  const t = await getTranslations("adminCron");
+
+  const [recent, lastSuccess] = await Promise.all([
+    listRecentCronRuns(30),
+    getLastSuccessfulCronRuns(),
+  ]);
+
+  return (
+    <main className="max-w-5xl 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>
+      <CronControls
+        initialRecent={recent}
+        initialLastSuccess={lastSuccess}
+      />
+    </main>
+  );
+}

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

@@ -61,6 +61,12 @@ export default async function AdminPage() {
           >
             {t("billingTool")}
           </a>
+          <a
+            href="/admin/cron"
+            className="text-sm px-4 py-2 rounded-lg border border-border text-text-secondary hover:text-text-primary hover:border-text-secondary transition-colors"
+          >
+            {t("cronTool")}
+          </a>
           <a
             href="/admin/openclaw"
             className="text-sm px-4 py-2 rounded-lg border border-border text-text-secondary hover:text-text-primary hover:border-text-secondary transition-colors"

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

@@ -1,23 +1,30 @@
 import { redirect } from "next/navigation";
 import { getTranslations } from "next-intl/server";
 import { getSessionUser } from "@/lib/session";
-import { listInvoices, syncOverdueInvoices } from "@/lib/db";
+import {
+  listCreditNotesForOrg,
+  listInvoices,
+  syncOverdueInvoices,
+} from "@/lib/db";
 import { CustomerInvoiceList } from "@/components/billing/customer-invoice-list";
+import { CustomerCreditNoteList } from "@/components/billing/customer-credit-note-list";
 import { RunningTotalWidget } from "@/components/billing/running-total-widget";
 
 /**
  * /billing — customer's billing home.
  *
- * Shows two things:
+ * Shows three things:
  *   1. RunningTotalWidget — current calendar month's accruing cost
  *      (or the already-issued invoice for the current month, if
  *      that ran early).
  *   2. CustomerInvoiceList — every issued invoice for this org,
  *      newest first. Status is reflected with a colored badge.
+ *   3. CustomerCreditNoteList — Phase 7. Credit notes (voids and
+ *      refunds) for this org, with PDF download links. Hidden
+ *      entirely when there are none (the common case).
  *
  * Anyone signed in can view this. The data is org-scoped; even
- * non-owner team members see the same view. Phase 4 will add a
- * "settings.payByInvoice" toggle visibility-gated to owners only.
+ * non-owner team members see the same view.
  */
 export default async function CustomerBillingPage() {
   const user = await getSessionUser();
@@ -31,10 +38,11 @@ export default async function CustomerBillingPage() {
     console.warn("syncOverdueInvoices failed in /billing:", e);
   }
 
-  const invoices = await listInvoices({
-    zitadelOrgId: user.orgId,
-    limit: 200,
-  });
+  // Parallel fetch — invoices + credit notes are independent.
+  const [invoices, creditNotes] = await Promise.all([
+    listInvoices({ zitadelOrgId: user.orgId, limit: 200 }),
+    listCreditNotesForOrg(user.orgId, 200),
+  ]);
 
   return (
     <main className="max-w-5xl mx-auto px-6 py-8">
@@ -49,15 +57,29 @@ export default async function CustomerBillingPage() {
         <h2 className="text-xs font-semibold uppercase tracking-wider text-text-muted mb-3">
           {t("currentPeriodHeading")}
         </h2>
-        <RunningTotalWidget />
+        {/* Phase 6: pass the owner flag so the no-config CTA shows
+            the right call-to-action vs the right hint. */}
+        <RunningTotalWidget isOwner={user.roles.includes("owner")} />
       </section>
 
-      <section className="animate-in animate-in-delay-2">
+      <section className="animate-in animate-in-delay-2 mb-8">
         <h2 className="text-xs font-semibold uppercase tracking-wider text-text-muted mb-3">
           {t("historyHeading")}
         </h2>
         <CustomerInvoiceList invoices={invoices} />
       </section>
+
+      {/* Phase 7: credit-note section. CustomerCreditNoteList itself
+          returns null when there are no credit notes, so this whole
+          section disappears for orgs in normal operation. */}
+      {creditNotes.length > 0 && (
+        <section className="animate-in animate-in-delay-3">
+          <h2 className="text-xs font-semibold uppercase tracking-wider text-text-muted mb-3">
+            {t("creditNotesHeading")}
+          </h2>
+          <CustomerCreditNoteList creditNotes={creditNotes} />
+        </section>
+      )}
     </main>
   );
 }

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

@@ -76,6 +76,7 @@ export default async function NewInstancePage() {
           userName={user.name}
           userEmail={user.email}
           hasOrgBilling={hasOrgBilling}
+          existingOrgBilling={orgBilling}
         />
       </div>
     </div>

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

@@ -317,6 +317,7 @@ export default async function DashboardPage() {
             userName={user.name}
             userEmail={user.email}
             hasOrgBilling={hasOrgBilling}
+            existingOrgBilling={orgBilling}
           />
         </div>
       </div>

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

@@ -1,30 +1,31 @@
-import { getTranslations } from "next-intl/server";
 import { redirect, notFound } from "next/navigation";
-import { getSessionUser, canMutate } from "@/lib/session";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
 import { getOrgBilling } from "@/lib/db";
-import { BillingSettingsForm } from "@/components/settings/billing-settings-form";
+import { BillingSettingsForm } from "@/components/settings/billing-form";
 
 /**
- * /settings/billing — view and edit org-scoped billing (Bug 34/35).
+ * /settings/billing — customer-side billing details management.
  *
- * Server-side fetches the existing record (if any) and passes it to
- * the client form. The form posts to PUT /api/billing on submit.
+ * Owner-only by visibility: non-owner members get a 404 (same
+ * response as if the page didn't exist). The link to this page
+ * is also hidden from non-owners on /billing and elsewhere, but
+ * the page itself enforces too — a non-owner who learns the URL
+ * still gets 404, not 403, so the page's existence doesn't leak.
  *
- * 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.
+ * First-time visitors see an empty form. Subsequent visits see
+ * the current values, editable. Save creates or updates via the
+ * shared upsert path; the row's existence drives whether the
+ * monthly issuance cron will pick this org up.
  */
 export default async function BillingSettingsPage() {
   const user = await getSessionUser();
   if (!user) redirect("/login");
-  if (!canMutate(user)) {
-    redirect("/settings");
-  }
-  const t = await getTranslations("settingsBilling");
+  // Non-owners get a 404 — see comment above.
+  if (!user.roles.includes("owner")) notFound();
 
-  const billing = await getOrgBilling(user.orgId);
+  const t = await getTranslations("settingsBilling");
+  const existing = await getOrgBilling(user.orgId);
 
   return (
     <main className="max-w-3xl mx-auto px-6 py-8">
@@ -32,16 +33,16 @@ export default async function BillingSettingsPage() {
         <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>
+        <p className="text-sm text-text-secondary mt-3">
+          {user.isPersonal ? t("subtitlePersonal") : t("subtitle")}
+        </p>
+      </div>
+      <div className="animate-in animate-in-delay-1">
+        <BillingSettingsForm
+          initial={existing}
+          isPersonal={user.isPersonal}
+        />
       </div>
-
-      <BillingSettingsForm
-        initial={billing}
-        isPersonal={user.isPersonal}
-        orgName={user.orgName}
-        userName={user.name}
-        userEmail={user.email}
-      />
     </main>
   );
 }

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

@@ -20,8 +20,9 @@ export default async function SettingsPage() {
   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.
+  // route, and a visibility predicate. Phase 6 fix5: profile is
+  // visible to every signed-in user (it's their own identity).
+  // Billing stays gated behind canMutate.
   const sections: Array<{
     key: string;
     href: string;
@@ -29,6 +30,14 @@ export default async function SettingsPage() {
     description: string;
     visible: boolean;
   }> = [
+    {
+      key: "profile",
+      href: "/settings/profile",
+      title: t("profileTitle"),
+      description: t("profileDescription"),
+      // Every signed-in user can edit their own first/last name.
+      visible: true,
+    },
     {
       key: "billing",
       href: "/settings/billing",

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

@@ -0,0 +1,68 @@
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { getHumanUserDetail } from "@/lib/zitadel";
+import { ProfileSettingsForm } from "@/components/settings/profile-form";
+
+/**
+ * /settings/profile — every authenticated user can edit their own
+ * first + last name. Email is shown read-only; changing it requires
+ * verification and is left to ZITADEL's own self-service flow.
+ *
+ * Personal vs company accounts:
+ *   - Both can edit their first/last name in ZITADEL.
+ *   - Personal accounts get an extra hint: editing the ZITADEL name
+ *     does NOT change how the customer's name appears on invoices.
+ *     Invoice identity is in org_billing.company_name (the "Full
+ *     name" field on /settings/billing) and is intentionally
+ *     editable separately, because legal/billing identity may not
+ *     match preferred display identity.
+ *   - Company accounts see an org-membership hint instead.
+ *
+ * Server-fetches the current profile from ZITADEL via the
+ * service-account PAT so the form starts with the canonical values
+ * rather than whatever happens to be in the JWT (the JWT name might
+ * be stale if the user updated their name in ZITADEL Console).
+ */
+export default async function ProfileSettingsPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+
+  const t = await getTranslations("settingsProfile");
+
+  let initial = { firstName: "", lastName: "", email: user.email };
+  try {
+    const profile = await getHumanUserDetail(user.id);
+    initial = {
+      firstName: profile.givenName,
+      lastName: profile.familyName,
+      email: profile.email || user.email,
+    };
+  } catch (e) {
+    // Identity provider unreachable: render the form with whatever
+    // we know from the session. The session has a combined `name`,
+    // not split parts, so we leave first/last empty and let the user
+    // re-enter. Server logs catch the underlying failure.
+    console.error("ProfileSettingsPage: getHumanUserDetail failed:", e);
+  }
+
+  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">
+          {user.isPersonal ? t("subtitlePersonal") : t("subtitle")}
+        </p>
+      </div>
+      <div className="animate-in animate-in-delay-1">
+        <ProfileSettingsForm
+          initial={initial}
+          isPersonal={user.isPersonal}
+          orgName={user.orgName}
+        />
+      </div>
+    </main>
+  );
+}

src/app/api/admin/billing/invoice-drafts/[id]/issue/route.ts

@@ -0,0 +1,64 @@
+import { NextResponse } from "next/server";
+import { getSessionUser, requirePlatformRole } from "@/lib/session";
+import {
+  CustomInvoiceValidationError,
+  issueCustomInvoiceDraft,
+} from "@/lib/billing";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/admin/billing/invoice-drafts/[id]/issue
+ *
+ * Phase 8. Convert a draft into a real invoice:
+ *   - Validate payload (must have lines, valid dates, billing snapshot)
+ *   - Allocate invoice number from the shared year-scoped counter
+ *   - Persist invoice with source='custom'
+ *   - Render PDF
+ *   - Email customer
+ *   - Delete the draft
+ *
+ * Returns the issued Invoice on success. Errors map cleanly to
+ * HTTP codes:
+ *   400 — validation failure (CustomInvoiceValidationError)
+ *   404 — draft id doesn't exist (also CustomInvoiceValidationError
+ *         since the orchestrator can't tell apart "draft missing"
+ *         from "invalid input" — the message string discriminates)
+ *   500 — anything else (DB error, Stripe error not applicable here)
+ *
+ * Idempotency: this endpoint is NOT idempotent. Issuing twice
+ * allocates two invoice numbers. The admin UI disables the submit
+ * button while in-flight, but for safety the backend handles
+ * double-submit by failing on the second call (the draft was
+ * deleted by the first).
+ */
+export async function POST(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  let user;
+  try {
+    await requirePlatformRole();
+    user = await getSessionUser();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { id } = await params;
+  try {
+    const invoice = await issueCustomInvoiceDraft({
+      draftId: id,
+      issuedBy: user.id,
+    });
+    return NextResponse.json({ invoice });
+  } catch (e) {
+    if (e instanceof CustomInvoiceValidationError) {
+      return NextResponse.json({ error: e.message }, { status: 400 });
+    }
+    return NextResponse.json(
+      { error: safeError(e, "Failed to issue custom invoice") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/billing/invoice-drafts/[id]/preview/route.ts

@@ -0,0 +1,52 @@
+import { NextResponse } from "next/server";
+import { requirePlatformRole } from "@/lib/session";
+import {
+  CustomInvoiceValidationError,
+  renderCustomDraftPreview,
+} from "@/lib/billing";
+import { safeError } from "@/lib/errors";
+
+/**
+ * GET /api/admin/billing/invoice-drafts/[id]/preview
+ *
+ * Phase 8. Render the current draft as a PDF without persisting an
+ * invoice. The bytes are returned inline so the browser displays
+ * the document in a new tab. The invoice number on the rendered
+ * PDF is the placeholder "DRAFT" — no real number is allocated.
+ *
+ * Useful for the admin's "Review" step in the draft → review →
+ * issue flow.
+ */
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const { id } = await params;
+  try {
+    const pdf = await renderCustomDraftPreview(id);
+    return new NextResponse(new Uint8Array(pdf), {
+      status: 200,
+      headers: {
+        "Content-Type": "application/pdf",
+        // Inline so the browser displays the PDF immediately. The
+        // filename is a guide — most browsers ignore it for inline
+        // disposition but it shows on the "Save as" dialog.
+        "Content-Disposition": `inline; filename="invoice-draft-${id}.pdf"`,
+        "Cache-Control": "no-store",
+      },
+    });
+  } catch (e) {
+    if (e instanceof CustomInvoiceValidationError) {
+      return NextResponse.json({ error: e.message }, { status: 400 });
+    }
+    return NextResponse.json(
+      { error: safeError(e, "Failed to render preview") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/billing/invoice-drafts/[id]/route.ts

@@ -0,0 +1,120 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { requirePlatformRole } from "@/lib/session";
+import {
+  deleteInvoiceDraft,
+  getInvoiceDraftById,
+  updateInvoiceDraft,
+} from "@/lib/db";
+import { safeError } from "@/lib/errors";
+import type { CustomInvoiceDraftPayload } from "@/types";
+
+/**
+ * /api/admin/billing/invoice-drafts/[id]
+ *
+ * Phase 8.
+ *
+ *   GET    — fetch one draft
+ *   PUT    — overwrite the payload (full replace, not patch)
+ *   DELETE — discard the draft
+ *
+ * All require platform admin. The org boundary is *not* enforced
+ * here: a platform admin can edit any draft regardless of which
+ * org it targets. If we ever introduce a per-org admin role,
+ * scope filtering would go in this file.
+ */
+
+const lineSchema = z.object({
+  description: z.string().trim().min(1).max(500),
+  quantity: z.number().finite(),
+  unitPriceChf: z.number().finite(),
+});
+
+const payloadSchema = z.object({
+  issueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+  dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+  locale: z.enum(["de", "en", "fr", "it"]),
+  paymentMethod: z.enum(["invoice", "card"]),
+  adminNotes: z.string().max(2000).optional(),
+  lines: z.array(lineSchema).max(100),
+});
+
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const { id } = await params;
+  try {
+    const draft = await getInvoiceDraftById(id);
+    if (!draft) {
+      return NextResponse.json({ error: "Not found" }, { status: 404 });
+    }
+    return NextResponse.json({ draft });
+  } catch (e) {
+    return NextResponse.json(
+      { error: safeError(e, "Failed to load draft") },
+      { status: 500 }
+    );
+  }
+}
+
+export async function PUT(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const { id } = await params;
+  const body = await request.json().catch(() => ({}));
+  const parsed = payloadSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid request", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  try {
+    const updated = await updateInvoiceDraft(
+      id,
+      parsed.data as CustomInvoiceDraftPayload
+    );
+    if (!updated) {
+      return NextResponse.json({ error: "Not found" }, { status: 404 });
+    }
+    return NextResponse.json({ draft: updated });
+  } catch (e) {
+    return NextResponse.json(
+      { error: safeError(e, "Failed to update draft") },
+      { status: 500 }
+    );
+  }
+}
+
+export async function DELETE(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const { id } = await params;
+  try {
+    const deleted = await deleteInvoiceDraft(id);
+    return NextResponse.json({ deleted });
+  } catch (e) {
+    return NextResponse.json(
+      { error: safeError(e, "Failed to delete draft") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/billing/invoice-drafts/route.ts

@@ -0,0 +1,94 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { requirePlatformRole, getSessionUser } from "@/lib/session";
+import {
+  createInvoiceDraft,
+  listAllInvoiceDrafts,
+} from "@/lib/db";
+import { safeError } from "@/lib/errors";
+import type { CustomInvoiceDraftPayload } from "@/types";
+
+/**
+ * /api/admin/billing/invoice-drafts
+ *
+ * Phase 8. Drafts for the admin "New invoice" flow.
+ *
+ *   GET  — list all open drafts across all orgs, newest-touched first.
+ *   POST — create a new draft for an org with an initial (possibly
+ *          empty) payload. Returns the inserted draft.
+ *
+ * Both require platform admin. Drafts have no customer-facing
+ * surface: they aren't reachable from /billing or any non-admin
+ * route.
+ */
+
+const lineSchema = z.object({
+  description: z.string().trim().min(1).max(500),
+  quantity: z.number().finite(),
+  unitPriceChf: z.number().finite(),
+});
+
+const payloadSchema = z.object({
+  issueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+  dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+  locale: z.enum(["de", "en", "fr", "it"]),
+  paymentMethod: z.enum(["invoice", "card"]),
+  adminNotes: z.string().max(2000).optional(),
+  lines: z.array(lineSchema).max(100),
+});
+
+const createSchema = z.object({
+  zitadelOrgId: z.string().trim().min(1),
+  payload: payloadSchema,
+});
+
+export async function GET() {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  try {
+    const drafts = await listAllInvoiceDrafts();
+    return NextResponse.json({ drafts });
+  } catch (e) {
+    return NextResponse.json(
+      { error: safeError(e, "Failed to list drafts") },
+      { status: 500 }
+    );
+  }
+}
+
+export async function POST(request: Request) {
+  let user;
+  try {
+    await requirePlatformRole();
+    user = await getSessionUser();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const body = await request.json().catch(() => ({}));
+  const parsed = createSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid request", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  try {
+    const draft = await createInvoiceDraft({
+      zitadelOrgId: parsed.data.zitadelOrgId,
+      createdBy: user.id,
+      payload: parsed.data.payload as CustomInvoiceDraftPayload,
+    });
+    return NextResponse.json({ draft });
+  } catch (e) {
+    return NextResponse.json(
+      { error: safeError(e, "Failed to create draft") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/billing/invoices/[id]/refund/route.ts

@@ -0,0 +1,88 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { requirePlatformRole, getSessionUser } from "@/lib/session";
+import { refundInvoice, RefundNotAllowedError } from "@/lib/billing";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/admin/billing/invoices/[id]/refund
+ *
+ * Phase 7. Refunds a paid invoice (full or partial) and issues a
+ * credit note. For Stripe-paid invoices, calls Stripe's Refund API
+ * before any local recording. For invoice-paid customers (bank
+ * transfer), records the refund locally and assumes the admin
+ * handled the actual money movement out-of-band.
+ *
+ * Body:
+ *   {
+ *     amountChf: number,   // positive, <= remaining refundable
+ *     reason: string       // required, free-text, max 500
+ *   }
+ *
+ * Authorization: platform admin.
+ *
+ * Status codes:
+ *   200 — refund issued, credit note returned
+ *   400 — bad request (zero/negative amount, etc.)
+ *   401 / 403 — not authenticated / not platform admin
+ *   409 — invoice not in a refundable state, or amount exceeds remaining
+ *   500 — Stripe call failed or another internal error
+ *
+ * Idempotency caveats: this endpoint is NOT idempotent against
+ * client retries. Issuing two refunds quickly will result in two
+ * Stripe refund calls (and two credit notes). The admin UI should
+ * disable the submit button while the request is in flight to
+ * prevent accidental double-clicks. The Stripe charge.refunded
+ * webhook is idempotent and will not double-count if it fires
+ * after this endpoint already recorded the refund.
+ */
+
+const bodySchema = z.object({
+  amountChf: z.number().positive().multipleOf(0.01),
+  reason: z.string().trim().min(1).max(500),
+});
+
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  let user;
+  try {
+    await requirePlatformRole();
+    user = await getSessionUser();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { id } = await params;
+  const body = await request.json().catch(() => ({}));
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid request", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  try {
+    const creditNote = await refundInvoice({
+      invoiceId: id,
+      amountChf: parsed.data.amountChf,
+      reason: parsed.data.reason,
+      refundedBy: user.id,
+    });
+    return NextResponse.json({ creditNote });
+  } catch (e) {
+    if (e instanceof RefundNotAllowedError) {
+      return NextResponse.json(
+        { error: e.message, currentStatus: e.currentStatus },
+        { status: 409 }
+      );
+    }
+    return NextResponse.json(
+      { error: safeError(e, "Refund failed") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/billing/invoices/[id]/void/route.ts

@@ -0,0 +1,77 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { requirePlatformRole, getSessionUser } from "@/lib/session";
+import { voidInvoice, VoidNotAllowedError } from "@/lib/billing";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/admin/billing/invoices/[id]/void
+ *
+ * Phase 7. Voids an unpaid invoice and issues a credit note.
+ *
+ * Body:
+ *   {
+ *     reason: string  // required, free-text, max 500
+ *   }
+ *
+ * Authorization: platform admin (same as mark-paid, generate, etc.).
+ * The acting user's ID lands in invoices.voided_by and on the
+ * credit_notes.issued_by audit columns.
+ *
+ * Status codes:
+ *   200 — voided, credit note returned in body
+ *   400 — bad request (missing reason etc.)
+ *   401 / 403 — not authenticated / not platform admin
+ *   409 — invoice not in a voidable state
+ *   500 — anything else (Stripe shouldn't apply here, but if PDF
+ *         render fails the void still went through — see body
+ *         payload for the credit-note number to re-render later)
+ */
+
+const bodySchema = z.object({
+  reason: z.string().trim().min(1).max(500),
+});
+
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  let user;
+  try {
+    await requirePlatformRole();
+    user = await getSessionUser();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { id } = await params;
+  const body = await request.json().catch(() => ({}));
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid request", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  try {
+    const creditNote = await voidInvoice({
+      invoiceId: id,
+      reason: parsed.data.reason,
+      voidedBy: user.id,
+    });
+    return NextResponse.json({ creditNote });
+  } catch (e) {
+    if (e instanceof VoidNotAllowedError) {
+      return NextResponse.json(
+        { error: e.message, currentStatus: e.currentStatus },
+        { status: 409 }
+      );
+    }
+    return NextResponse.json(
+      { error: safeError(e, "Void failed") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/cron/issue-monthly/route.ts

@@ -0,0 +1,68 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser, requirePlatformRole } from "@/lib/session";
+import { runMonthlyIssuance } from "@/lib/cron";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/admin/cron/issue-monthly
+ *
+ * Admin-side manual trigger for the issuance sweep — same business
+ * logic as /api/cron/issue-monthly, different auth (session-based
+ * platform role check) and the option to override the target
+ * year/month from the request body.
+ *
+ * Body (all optional):
+ *   { year?: number, month?: number }
+ *
+ * Default target is the previous local month — matching what the
+ * automated cron would do. Override is useful for catching up after
+ * a failed run or re-billing a past month after fixing data.
+ */
+const bodySchema = z.object({
+  year: z.number().int().min(2000).max(3000).optional(),
+  month: z.number().int().min(1).max(12).optional(),
+});
+
+export async function POST(request: Request) {
+  let user;
+  try {
+    await requirePlatformRole();
+    user = await getSessionUser();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const body = await request.json().catch(() => ({}));
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid request", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  if (
+    (parsed.data.year && !parsed.data.month) ||
+    (parsed.data.month && !parsed.data.year)
+  ) {
+    return NextResponse.json(
+      { error: "year and month must both be provided, or neither" },
+      { status: 400 }
+    );
+  }
+  try {
+    const { runId, summary } = await runMonthlyIssuance({
+      triggeredBy: user.id,
+      year: parsed.data.year,
+      month: parsed.data.month,
+    });
+    return NextResponse.json({ runId, ...summary });
+  } catch (e) {
+    return NextResponse.json(
+      { error: safeError(e, "Issuance sweep failed.") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/cron/runs/route.ts

@@ -0,0 +1,27 @@
+import { NextResponse } from "next/server";
+import { requirePlatformRole } from "@/lib/session";
+import {
+  getLastSuccessfulCronRuns,
+  listRecentCronRuns,
+} from "@/lib/db";
+
+/**
+ * GET /api/admin/cron/runs
+ *
+ * Returns recent cron run history plus per-kind "last successful"
+ * summary for the admin /admin/cron dashboard.
+ *
+ * Response: { recent: CronRun[]; lastSuccess: { monthlyIssue, reminders } }
+ */
+export async function GET() {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const [recent, lastSuccess] = await Promise.all([
+    listRecentCronRuns(30),
+    getLastSuccessfulCronRuns(),
+  ]);
+  return NextResponse.json({ recent, lastSuccess });
+}

src/app/api/admin/cron/send-reminders/route.ts

@@ -0,0 +1,34 @@
+import { NextResponse } from "next/server";
+import { getSessionUser, requirePlatformRole } from "@/lib/session";
+import { runReminderSweep } from "@/lib/cron";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/admin/cron/send-reminders
+ *
+ * Admin-side manual trigger for the reminder sweep. Same logic
+ * as the machine path; session-based platform-role auth.
+ */
+export async function POST() {
+  let user;
+  try {
+    await requirePlatformRole();
+    user = await getSessionUser();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  try {
+    const { runId, summary } = await runReminderSweep({
+      triggeredBy: user.id,
+    });
+    return NextResponse.json({ runId, ...summary });
+  } catch (e) {
+    return NextResponse.json(
+      { error: safeError(e, "Reminder sweep failed.") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/credit-notes/[number]/pdf/route.ts

@@ -0,0 +1,64 @@
+import { NextResponse } from "next/server";
+import { getSessionUser } from "@/lib/session";
+import {
+  getCreditNoteByNumber,
+  getCreditNoteByNumberForOrg,
+  getCreditNotePdf,
+} from "@/lib/db";
+
+/**
+ * GET /api/credit-notes/[number]/pdf
+ *
+ * Phase 7. Customer-facing PDF download for a credit note. Returns
+ * the binary PDF with Content-Disposition: inline so the browser
+ * renders it in-tab (matching the invoice download behaviour). The
+ * customer's email links here.
+ *
+ * Authorization:
+ *   - The caller must be authenticated.
+ *   - For customer-org callers, the credit note must belong to their
+ *     org (orgId-scoped lookup).
+ *   - Platform admins can fetch any credit note (cross-org lookup).
+ *
+ * Returns 404 in both "doesn't exist" and "exists but not yours"
+ * cases — leak-safe identical to invoice lookup.
+ */
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ number: string }> }
+) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { number } = await params;
+  // URL-decoded number — the route param comes URL-encoded.
+  const decodedNumber = decodeURIComponent(number);
+  const cn = user.isPlatform
+    ? await getCreditNoteByNumber(decodedNumber)
+    : await getCreditNoteByNumberForOrg(decodedNumber, user.orgId);
+  if (!cn) {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+  const pdf = await getCreditNotePdf(cn.id);
+  if (!pdf) {
+    // The credit note exists but the PDF was never attached. Most
+    // likely a render failure during issuance — the credit note
+    // row is still authoritative, the PDF needs re-rendering.
+    return NextResponse.json(
+      {
+        error:
+          "Credit note exists but its PDF has not been rendered. Please contact support.",
+      },
+      { status: 502 }
+    );
+  }
+  return new NextResponse(new Uint8Array(pdf.data), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/pdf",
+      "Content-Disposition": `inline; filename="${pdf.filename}"`,
+      "Cache-Control": "private, no-cache",
+    },
+  });
+}

src/app/api/cron/issue-monthly/route.ts

@@ -0,0 +1,42 @@
+import { NextResponse } from "next/server";
+import { runMonthlyIssuance, verifyCronBearer } from "@/lib/cron";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/cron/issue-monthly
+ *
+ * Machine entry point for the monthly issuance sweep. Authentication
+ * is the shared bearer token in CRON_BEARER_TOKEN, injected from
+ * OpenBao via the portal-cron K8s Secret. The K8s CronJob sends:
+ *
+ *   curl -X POST -H "Authorization: Bearer $CRON_BEARER_TOKEN" \
+ *        https://app.pieced.ch/api/cron/issue-monthly
+ *
+ * The sweep targets the calendar month that ended just before
+ * "now" in Europe/Zurich. Running it on June 1st at 00:30 Swiss
+ * time bills May; running it on July 5th bills June; etc. The
+ * uniqueness constraint on (org, period_start) makes re-runs
+ * harmless — already-issued orgs are counted as skipped.
+ *
+ * Returns the summary {success, failure, skipped} JSON. The
+ * CronJob doesn't look at the response body (just the status
+ * code) but having a useful one helps debugging via curl.
+ */
+export const dynamic = "force-dynamic";
+
+export async function POST(request: Request) {
+  if (!verifyCronBearer(request.headers.get("authorization"))) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  try {
+    const { runId, summary } = await runMonthlyIssuance({
+      triggeredBy: "cron",
+    });
+    return NextResponse.json({ runId, ...summary });
+  } catch (e) {
+    return NextResponse.json(
+      { error: safeError(e, "Issuance sweep failed.") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/cron/send-reminders/route.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from "next/server";
+import { runReminderSweep, verifyCronBearer } from "@/lib/cron";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/cron/send-reminders
+ *
+ * Machine entry point for the daily reminder sweep. Same auth
+ * (bearer token in CRON_BEARER_TOKEN) and the same response
+ * contract as /api/cron/issue-monthly.
+ *
+ * Schedule: 09:00 Europe/Zurich daily. Picks invoices that are
+ * past their due date and haven't received the corresponding
+ * reminder level yet; sends one email per invoice per run.
+ */
+export const dynamic = "force-dynamic";
+
+export async function POST(request: Request) {
+  if (!verifyCronBearer(request.headers.get("authorization"))) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  try {
+    const { runId, summary } = await runReminderSweep({
+      triggeredBy: "cron",
+    });
+    return NextResponse.json({ runId, ...summary });
+  } catch (e) {
+    return NextResponse.json(
+      { error: safeError(e, "Reminder sweep failed.") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/onboarding/route.ts

@@ -252,11 +252,24 @@ export async function POST(request: Request) {
     }
   }
 
-  // For follow-up instances, prefer the on-file company name and contact
-  // details; the user can't change those by re-typing them in the wizard.
+  // The audit copy of company name on this request stays inherited
+  // from the first request in the org — it's a historical snapshot
+  // of the company name at the time the request was created, and
+  // org_billing is now the canonical source for current values.
+  //
+  // Phase 6 fix4: contactName and contactEmail are NOT inherited.
+  // They identify whoever submitted THIS specific request (drives
+  // admin display, support ticket routing, and email greetings).
+  // The previous "prior?.contactName ?? user.name" pattern locked
+  // the contact to whoever first onboarded the org, which broke for
+  // any subsequent submission by a different user — admin saw the
+  // wrong name, support emails went to the wrong person, and the
+  // actual submitter had no way to correct it because the wizard
+  // doesn't expose a contact-name input. The fix is simply to use
+  // the current session user every time.
   const companyName = prior?.companyName ?? user.orgName;
-  const contactName = prior?.contactName ?? user.name;
-  const contactEmail = prior?.contactEmail ?? user.email;
+  const contactName = user.name;
+  const contactEmail = user.email;
 
   // Bug 35: org-scoped billing.
   //

src/app/api/settings/billing/route.ts

@@ -0,0 +1,90 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser } from "@/lib/session";
+import { getOrgBilling, upsertOrgBilling } from "@/lib/db";
+
+/**
+ * GET /api/settings/billing — read the caller's org_billing row.
+ * Returns null if the org hasn't configured billing yet — the
+ * form renders empty and the PUT will create on first save.
+ *
+ * PUT /api/settings/billing — upsert the row.
+ *
+ * Authorization: caller must have role "owner" in their org.
+ * Non-owners get 403 (they shouldn't have reached the page UI
+ * anyway, which hides the link, but the API enforces too — a
+ * non-owner who hits this directly with curl gets refused).
+ *
+ * Personal accounts are inherently their own owner (single-user
+ * org), so user.roles.includes("owner") returns true and they
+ * can manage their own billing.
+ */
+
+const upsertSchema = z.object({
+  companyName: z.string().trim().min(1).max(200),
+  // Phase 6 fix: optional "z.Hd." / "Attn:" line. Personal accounts
+  // never send this (the UI hides the field); orgs may set or leave
+  // it empty.
+  contactName: z.string().trim().max(200).optional().nullable(),
+  streetAddress: z.string().trim().min(1).max(200),
+  postalCode: z.string().trim().min(1).max(20),
+  city: z.string().trim().min(1).max(100),
+  // ISO 3166-1 alpha-2. We normalise to uppercase server-side.
+  country: z
+    .string()
+    .trim()
+    .length(2)
+    .regex(/^[A-Za-z]{2}$/, "Use a 2-letter ISO country code (CH, DE, …)"),
+  vatNumber: z.string().trim().max(40).optional().nullable(),
+  billingEmail: z.string().trim().email().max(200),
+  notes: z.string().trim().max(2000).optional().nullable(),
+});
+
+function requireOwner(user: { roles: string[] } | null) {
+  if (!user) return false;
+  return user.roles.includes("owner");
+}
+
+export async function GET() {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  if (!requireOwner(user as any)) {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const billing = await getOrgBilling(user.orgId);
+  return NextResponse.json({ billing });
+}
+
+export async function PUT(request: Request) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  if (!requireOwner(user as any)) {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const body = await request.json().catch(() => ({}));
+  const parsed = upsertSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid request", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  const data = parsed.data;
+  const billing = await upsertOrgBilling({
+    zitadelOrgId: user.orgId,
+    companyName: data.companyName,
+    contactName: data.contactName ?? null,
+    streetAddress: data.streetAddress,
+    postalCode: data.postalCode,
+    city: data.city,
+    country: data.country.toUpperCase(),
+    vatNumber: data.vatNumber ?? null,
+    billingEmail: data.billingEmail,
+    notes: data.notes ?? null,
+  });
+  return NextResponse.json({ billing });
+}

src/app/api/settings/profile/route.ts

@@ -0,0 +1,81 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser } from "@/lib/session";
+import {
+  getHumanUserDetail,
+  updateHumanUserProfile,
+} from "@/lib/zitadel";
+
+/**
+ * GET /api/settings/profile — read the caller's ZITADEL profile.
+ * Returns first/last/display name and email. Used by the settings
+ * page server component to populate the form.
+ *
+ * PUT /api/settings/profile — update first + last name. Email is
+ * NOT mutable here — changing email needs verification flow that
+ * ZITADEL's own self-service UI already provides; we don't
+ * duplicate that.
+ *
+ * Authorization: any authenticated user can edit their own profile.
+ * The PAT (ZITADEL_SA_PAT) is used to call the ZITADEL v2 user
+ * service, but only against the caller's own userId. There is no
+ * userId field on the request — it's always derived from the
+ * session, so the route can't be abused to edit other users.
+ */
+
+const updateSchema = z.object({
+  firstName: z.string().trim().min(1).max(100),
+  lastName: z.string().trim().min(1).max(100),
+});
+
+export async function GET() {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  try {
+    const profile = await getHumanUserDetail(user.id);
+    return NextResponse.json({ profile });
+  } catch (e: any) {
+    // Surface ZITADEL-side failures (e.g. user not found, PAT expired)
+    // as 502 — the portal couldn't reach its identity provider, which
+    // is operationally different from a 4xx on the caller's input.
+    console.error("getHumanUserDetail failed:", e);
+    return NextResponse.json(
+      { error: "Could not load profile from identity provider" },
+      { status: 502 }
+    );
+  }
+}
+
+export async function PUT(request: Request) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const body = await request.json().catch(() => ({}));
+  const parsed = updateSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid request", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  try {
+    const result = await updateHumanUserProfile({
+      userId: user.id,
+      givenName: parsed.data.firstName,
+      familyName: parsed.data.lastName,
+    });
+    return NextResponse.json({
+      displayName: result.displayName,
+      changeDate: result.changeDate,
+    });
+  } catch (e: any) {
+    console.error("updateHumanUserProfile failed:", e);
+    return NextResponse.json(
+      { error: "Could not update profile in identity provider" },
+      { status: 502 }
+    );
+  }
+}

src/app/api/stripe/webhook/route.ts

@@ -2,11 +2,14 @@ import { NextResponse } from "next/server";
 import type Stripe from "stripe";
 import { getStripeClient, getWebhookSecret } from "@/lib/stripe";
 import {
+  getInvoiceByStripePaymentIntent,
+  isStripeRefundRecorded,
   markInvoicePaid,
   markStripeEventProcessed,
   setInvoiceStripePaymentIntent,
   tryRecordStripeEvent,
 } from "@/lib/db";
+import { refundInvoice, RefundNotAllowedError } from "@/lib/billing";
 
 /**
  * POST /api/stripe/webhook
@@ -209,13 +212,103 @@ async function handleCheckoutCompleted(
 }
 
 async function handleChargeRefunded(charge: Stripe.Charge): Promise<void> {
-  // v1 scope: log only. Refunds always go through Stripe → admin
-  // initiates them in the dashboard. Updating our invoice status
-  // to 'void' or partial-credit needs more product thinking
-  // (partial refunds? credit notes? VAT corrections?). Phase 7.
-  console.log(
-    `Charge ${charge.id} refunded (amount ${charge.amount_refunded} ${charge.currency}); no portal-side state change.`
-  );
+  // Phase 7: mirror Stripe refunds into the portal so credit notes
+  // are issued for refunds initiated in the Stripe Dashboard. For
+  // refunds initiated via /api/admin/.../refund, this handler is a
+  // no-op (each refund's stripe_refund_id is already recorded
+  // before the webhook lands — refundInvoice records it
+  // synchronously after the Stripe API call).
+  //
+  // A charge can have multiple refund objects (multiple partial
+  // refunds against the same charge accumulate here). We iterate
+  // and process any that aren't yet recorded in our DB.
+  const paymentIntentId =
+    typeof charge.payment_intent === "string"
+      ? charge.payment_intent
+      : charge.payment_intent?.id;
+  if (!paymentIntentId) {
+    console.error(
+      `charge.refunded for charge ${charge.id} has no payment_intent; cannot link to invoice.`
+    );
+    return;
+  }
+  const invoice = await getInvoiceByStripePaymentIntent(paymentIntentId);
+  if (!invoice) {
+    console.error(
+      `charge.refunded for payment_intent ${paymentIntentId} has no matching invoice; ignoring.`
+    );
+    return;
+  }
+  const refundsList = charge.refunds?.data ?? [];
+  if (refundsList.length === 0) {
+    // Some charge.refunded events fire with the refunds list
+    // collapsed (the object includes the aggregated amount_refunded
+    // but the data array can be omitted depending on Stripe's
+    // expansion choices). In that case there's nothing for us to
+    // iterate over here; the actual `refund.created` /
+    // `refund.updated` events carry per-refund detail and we'd need
+    // to enable those in Stripe to handle them. For v1 we log and
+    // rely on the in-portal admin path (refundInvoice) being the
+    // only refund initiator.
+    console.log(
+      `charge.refunded for charge ${charge.id} arrived without refund objects in data; in-portal flow assumed.`
+    );
+    return;
+  }
+  for (const refund of refundsList) {
+    try {
+      // Idempotency: skip refunds we already recorded (either via
+      // portal admin action or a prior webhook delivery).
+      if (await isStripeRefundRecorded(refund.id)) {
+        continue;
+      }
+      const amountChf = (refund.amount ?? 0) / 100;
+      if (amountChf <= 0) continue;
+      // Map Stripe refund status to ours. Anything other than the
+      // canonical four falls through to 'pending' so we don't lose
+      // the record entirely.
+      let status: "pending" | "succeeded" | "failed" | "canceled" = "pending";
+      if (refund.status === "succeeded") status = "succeeded";
+      else if (refund.status === "failed") status = "failed";
+      else if (refund.status === "canceled") status = "canceled";
+      // For refunds that originated in Stripe Dashboard we don't
+      // have a reason to display. Use a sentinel string so the
+      // credit note PDF has something to print. Admin can edit
+      // post-hoc if needed (no UI for that today, but the DB row
+      // is reachable).
+      const reason = refund.reason
+        ? `Stripe Dashboard: ${refund.reason}`
+        : "Refund issued via Stripe Dashboard";
+      // refundInvoice with existingStripeRefund: don't call Stripe
+      // again (we'd error since the refund already exists), just
+      // mirror the record into our DB and issue the credit note.
+      await refundInvoice({
+        invoiceId: invoice.id,
+        amountChf,
+        reason,
+        refundedBy: "stripe-webhook",
+        existingStripeRefund: { id: refund.id, status },
+      });
+      console.log(
+        `Mirrored Stripe refund ${refund.id} for invoice ${invoice.invoiceNumber} (CHF ${amountChf.toFixed(2)}).`
+      );
+    } catch (e) {
+      if (e instanceof RefundNotAllowedError) {
+        // The invoice was already fully refunded by an earlier
+        // webhook delivery or by an in-portal action. That's fine.
+        console.log(
+          `Stripe refund ${refund.id}: ${e.message} (already accounted for).`
+        );
+        continue;
+      }
+      // For any other error, log but continue to the next refund —
+      // we don't want one bad refund to block the rest.
+      console.error(
+        `Failed to mirror Stripe refund ${refund.id} for invoice ${invoice.invoiceNumber}:`,
+        e
+      );
+    }
+  }
 }
 
 async function handlePaymentFailed(

src/components/admin/billing/custom-invoice-editor.tsx

@@ -0,0 +1,537 @@
+"use client";
+
+import { useState, useMemo, useCallback } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { Card, CardHeader } from "@/components/ui/card";
+import type {
+  CustomInvoiceDraftLine,
+  CustomInvoiceDraftPayload,
+  InvoiceDraftRecord,
+  OrgBilling,
+} from "@/types";
+
+interface Props {
+  draft: InvoiceDraftRecord;
+  orgBilling: OrgBilling | null;
+}
+
+const LOCALE_OPTIONS = [
+  { value: "de", label: "Deutsch" },
+  { value: "en", label: "English" },
+  { value: "fr", label: "Français" },
+  { value: "it", label: "Italiano" },
+];
+
+/**
+ * Custom invoice editor — Phase 8.
+ *
+ * Local state mirrors the persisted payload. Save persists the
+ * current state via PUT. Preview re-renders the PDF in-memory (no
+ * persistence). Issue allocates the invoice number and emails the
+ * customer.
+ *
+ * VAT preview is computed client-side from the country in the org
+ * billing snapshot — it's an estimate for the admin's eye, not
+ * authoritative. The server recomputes at issue time using the
+ * same vatRateForAddress() helper to ensure consistency.
+ *
+ * Discount/Rabatt is supported via a row with a negative
+ * unitPriceChf. The "Add discount" button seeds a new row with
+ * quantity 1 and a -50 placeholder to nudge the admin toward the
+ * intended sign.
+ */
+export function CustomInvoiceEditor({ draft, orgBilling }: Props) {
+  const t = useTranslations("adminBilling");
+  const router = useRouter();
+
+  // Editable state — initialized from the draft payload.
+  const [issueDate, setIssueDate] = useState(draft.payload.issueDate);
+  const [dueDate, setDueDate] = useState(draft.payload.dueDate);
+  const [locale, setLocale] = useState<"de" | "en" | "fr" | "it">(
+    draft.payload.locale
+  );
+  const [paymentMethod, setPaymentMethod] = useState<"invoice" | "card">(
+    draft.payload.paymentMethod
+  );
+  const [adminNotes, setAdminNotes] = useState(draft.payload.adminNotes ?? "");
+  const [lines, setLines] = useState<CustomInvoiceDraftLine[]>(
+    draft.payload.lines.length > 0
+      ? draft.payload.lines
+      : [{ description: "", quantity: 1, unitPriceChf: 0 }]
+  );
+
+  const [busy, setBusy] = useState<null | "save" | "preview" | "issue" | "delete">(
+    null
+  );
+  const [error, setError] = useState("");
+  const [dirty, setDirty] = useState(false);
+
+  // Build current payload — used by every action.
+  const buildPayload = useCallback((): CustomInvoiceDraftPayload => {
+    return {
+      issueDate,
+      dueDate,
+      locale,
+      paymentMethod,
+      adminNotes: adminNotes.trim() ? adminNotes.trim() : undefined,
+      lines: lines.map((ln) => ({
+        description: ln.description,
+        quantity: Number(ln.quantity) || 0,
+        unitPriceChf: Number(ln.unitPriceChf) || 0,
+      })),
+    };
+  }, [issueDate, dueDate, locale, paymentMethod, adminNotes, lines]);
+
+  // Client-side VAT estimate. The auth-of-truth math runs server-side
+  // at issue time; this is just to show the admin what they're about
+  // to commit to.
+  const totals = useMemo(() => {
+    const subtotal = Math.round(
+      lines.reduce(
+        (s, ln) => s + (Number(ln.quantity) || 0) * (Number(ln.unitPriceChf) || 0),
+        0
+      ) * 100
+    ) / 100;
+    // Country-based VAT estimate. Mirrors vatRateForAddress() —
+    // simplified because the editor doesn't know the platform
+    // pricing config. Defaults to 8.1 for CH/LI; 0 otherwise.
+    const country = (orgBilling?.country ?? "").toUpperCase();
+    let vatRate = 0;
+    if (country === "CH" || country === "LI") {
+      vatRate = 8.1;
+    } else if (orgBilling?.vatNumber) {
+      vatRate = 0; // reverse charge
+    } else {
+      vatRate = 0; // out of scope OR consumer (server will fix)
+    }
+    const vatAmount = Math.round(subtotal * (vatRate / 100) * 100) / 100;
+    const total = Math.round((subtotal + vatAmount) * 100) / 100;
+    return { subtotal, vatRate, vatAmount, total };
+  }, [lines, orgBilling]);
+
+  // Line management
+  const updateLine = (idx: number, patch: Partial<CustomInvoiceDraftLine>) => {
+    setLines((prev) =>
+      prev.map((ln, i) => (i === idx ? { ...ln, ...patch } : ln))
+    );
+    setDirty(true);
+  };
+  const addLine = () => {
+    setLines((prev) => [
+      ...prev,
+      { description: "", quantity: 1, unitPriceChf: 0 },
+    ]);
+    setDirty(true);
+  };
+  const addDiscountLine = () => {
+    setLines((prev) => [
+      ...prev,
+      { description: t("editorRabattDefaultDescription"), quantity: 1, unitPriceChf: -50 },
+    ]);
+    setDirty(true);
+  };
+  const removeLine = (idx: number) => {
+    setLines((prev) => prev.filter((_, i) => i !== idx));
+    setDirty(true);
+  };
+
+  // Actions
+  const save = async (): Promise<boolean> => {
+    setError("");
+    setBusy("save");
+    try {
+      const res = await fetch(
+        `/api/admin/billing/invoice-drafts/${draft.id}`,
+        {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(buildPayload()),
+        }
+      );
+      const j = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error(j.error || `HTTP ${res.status}`);
+      setDirty(false);
+      return true;
+    } catch (e: any) {
+      setError(e.message);
+      return false;
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const preview = async () => {
+    // Save first if there are unsaved changes — otherwise the
+    // preview reflects stale data.
+    if (dirty) {
+      const ok = await save();
+      if (!ok) return;
+    }
+    // Open the preview in a new tab. The browser handles the PDF
+    // download/render natively; we don't need to fetch the bytes
+    // ourselves.
+    window.open(
+      `/api/admin/billing/invoice-drafts/${draft.id}/preview`,
+      "_blank",
+      "noopener"
+    );
+  };
+
+  const issue = async () => {
+    if (!confirm(t("editorIssueConfirm"))) return;
+    if (dirty) {
+      const ok = await save();
+      if (!ok) return;
+    }
+    setError("");
+    setBusy("issue");
+    try {
+      const res = await fetch(
+        `/api/admin/billing/invoice-drafts/${draft.id}/issue`,
+        { method: "POST" }
+      );
+      const j = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error(j.error || `HTTP ${res.status}`);
+      // The draft was deleted server-side; go look at the new invoice.
+      router.push(`/admin/billing/invoices/${j.invoice.id}`);
+    } catch (e: any) {
+      setError(e.message);
+      setBusy(null);
+    }
+  };
+
+  const deleteDraft = async () => {
+    if (!confirm(t("editorDeleteConfirm"))) return;
+    setError("");
+    setBusy("delete");
+    try {
+      const res = await fetch(
+        `/api/admin/billing/invoice-drafts/${draft.id}`,
+        { method: "DELETE" }
+      );
+      if (!res.ok) {
+        const j = await res.json().catch(() => ({}));
+        throw new Error(j.error || `HTTP ${res.status}`);
+      }
+      router.push("/admin/billing/invoice-drafts");
+    } catch (e: any) {
+      setError(e.message);
+      setBusy(null);
+    }
+  };
+
+  // No billing snapshot = can't issue. Save still works so admin
+  // can come back once the customer has completed onboarding.
+  const canIssue =
+    !!orgBilling &&
+    lines.length > 0 &&
+    lines.every((ln) => ln.description.trim().length > 0);
+
+  return (
+    <div className="flex flex-col gap-6">
+      {/* Bill-to preview — read-only, sourced from the org's billing
+          snapshot. Issued at issue time. */}
+      <Card>
+        <CardHeader>{t("editorBillToHeading")}</CardHeader>
+        <div className="p-4 text-sm">
+          {orgBilling ? (
+            <>
+              <p className="font-medium">{orgBilling.companyName}</p>
+              {orgBilling.contactName && (
+                <p className="text-text-secondary text-xs">
+                  {orgBilling.contactName}
+                </p>
+              )}
+              <p className="text-text-secondary text-xs">
+                {orgBilling.streetAddress}, {orgBilling.postalCode}{" "}
+                {orgBilling.city}, {orgBilling.country}
+              </p>
+              {orgBilling.vatNumber && (
+                <p className="text-text-muted text-xs mt-1">
+                  MWST/VAT: {orgBilling.vatNumber}
+                </p>
+              )}
+              <p className="text-text-muted text-xs">
+                {orgBilling.billingEmail}
+              </p>
+            </>
+          ) : (
+            <p className="text-error">{t("editorNoBillingSnapshot")}</p>
+          )}
+        </div>
+      </Card>
+
+      {/* Dates + locale + payment method */}
+      <Card>
+        <CardHeader>{t("editorMetadataHeading")}</CardHeader>
+        <div className="p-4 grid grid-cols-2 md:grid-cols-4 gap-4">
+          <div className="flex flex-col gap-1">
+            <label className="text-xs uppercase tracking-wider text-text-muted">
+              {t("editorIssueDateLabel")}
+            </label>
+            <input
+              type="date"
+              value={issueDate}
+              onChange={(e) => {
+                setIssueDate(e.target.value);
+                setDirty(true);
+              }}
+              className="px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+            />
+          </div>
+          <div className="flex flex-col gap-1">
+            <label className="text-xs uppercase tracking-wider text-text-muted">
+              {t("editorDueDateLabel")}
+            </label>
+            <input
+              type="date"
+              value={dueDate}
+              onChange={(e) => {
+                setDueDate(e.target.value);
+                setDirty(true);
+              }}
+              className="px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+            />
+          </div>
+          <div className="flex flex-col gap-1">
+            <label className="text-xs uppercase tracking-wider text-text-muted">
+              {t("editorLocaleLabel")}
+            </label>
+            <select
+              value={locale}
+              onChange={(e) => {
+                setLocale(e.target.value as "de" | "en" | "fr" | "it");
+                setDirty(true);
+              }}
+              className="px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+            >
+              {LOCALE_OPTIONS.map((o) => (
+                <option key={o.value} value={o.value}>
+                  {o.label}
+                </option>
+              ))}
+            </select>
+          </div>
+          <div className="flex flex-col gap-1">
+            <label className="text-xs uppercase tracking-wider text-text-muted">
+              {t("editorPaymentMethodLabel")}
+            </label>
+            <select
+              value={paymentMethod}
+              onChange={(e) => {
+                setPaymentMethod(e.target.value as "invoice" | "card");
+                setDirty(true);
+              }}
+              className="px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+            >
+              <option value="invoice">{t("editorPaymentInvoice")}</option>
+              <option value="card">{t("editorPaymentCard")}</option>
+            </select>
+          </div>
+        </div>
+      </Card>
+
+      {/* Line editor */}
+      <Card>
+        <CardHeader>{t("editorLinesHeading")}</CardHeader>
+        <div className="p-4">
+          <table className="w-full text-sm">
+            <thead className="text-xs text-text-muted text-left">
+              <tr>
+                <th className="pb-2 pr-3">{t("editorLineDescription")}</th>
+                <th className="pb-2 pr-3 w-20 text-right">
+                  {t("editorLineQty")}
+                </th>
+                <th className="pb-2 pr-3 w-32 text-right">
+                  {t("editorLineUnitPrice")}
+                </th>
+                <th className="pb-2 pr-3 w-32 text-right">
+                  {t("editorLineAmount")}
+                </th>
+                <th className="pb-2 w-12"></th>
+              </tr>
+            </thead>
+            <tbody>
+              {lines.map((ln, idx) => {
+                const amount =
+                  Math.round(
+                    (Number(ln.quantity) || 0) *
+                      (Number(ln.unitPriceChf) || 0) *
+                      100
+                  ) / 100;
+                return (
+                  <tr key={idx} className="border-t border-border">
+                    <td className="py-2 pr-3">
+                      <input
+                        type="text"
+                        value={ln.description}
+                        onChange={(e) =>
+                          updateLine(idx, { description: e.target.value })
+                        }
+                        placeholder={t("editorLineDescriptionPlaceholder")}
+                        className="w-full px-2 py-1.5 rounded border border-border bg-surface-2 text-sm"
+                        maxLength={500}
+                      />
+                    </td>
+                    <td className="py-2 pr-3">
+                      <input
+                        type="number"
+                        step="0.01"
+                        value={ln.quantity}
+                        onChange={(e) =>
+                          updateLine(idx, {
+                            quantity: parseFloat(e.target.value) || 0,
+                          })
+                        }
+                        className="w-full px-2 py-1.5 rounded border border-border bg-surface-2 text-sm font-mono text-right"
+                      />
+                    </td>
+                    <td className="py-2 pr-3">
+                      <input
+                        type="number"
+                        step="0.01"
+                        value={ln.unitPriceChf}
+                        onChange={(e) =>
+                          updateLine(idx, {
+                            unitPriceChf: parseFloat(e.target.value) || 0,
+                          })
+                        }
+                        className="w-full px-2 py-1.5 rounded border border-border bg-surface-2 text-sm font-mono text-right"
+                      />
+                    </td>
+                    <td className="py-2 pr-3 text-right font-mono text-sm whitespace-nowrap">
+                      <span className={amount < 0 ? "text-error" : ""}>
+                        CHF {amount.toFixed(2)}
+                      </span>
+                    </td>
+                    <td className="py-2 text-right">
+                      <button
+                        onClick={() => removeLine(idx)}
+                        className="text-text-muted hover:text-error text-lg leading-none"
+                        title={t("editorLineRemove")}
+                        type="button"
+                      >
+                        ×
+                      </button>
+                    </td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+          <div className="flex gap-2 mt-3">
+            <button
+              onClick={addLine}
+              type="button"
+              className="px-3 py-1.5 rounded-md border border-border text-sm hover:bg-surface-3"
+            >
+              + {t("editorAddLine")}
+            </button>
+            <button
+              onClick={addDiscountLine}
+              type="button"
+              className="px-3 py-1.5 rounded-md border border-border text-sm hover:bg-surface-3 text-text-secondary"
+              title={t("editorAddDiscountHint")}
+            >
+              − {t("editorAddDiscount")}
+            </button>
+          </div>
+        </div>
+      </Card>
+
+      {/* Admin notes */}
+      <Card>
+        <CardHeader>{t("editorNotesHeading")}</CardHeader>
+        <div className="p-4">
+          <textarea
+            value={adminNotes}
+            onChange={(e) => {
+              setAdminNotes(e.target.value);
+              setDirty(true);
+            }}
+            placeholder={t("editorNotesPlaceholder")}
+            rows={2}
+            maxLength={2000}
+            className="w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+          />
+          <p className="text-xs text-text-muted mt-1">
+            {t("editorNotesHint")}
+          </p>
+        </div>
+      </Card>
+
+      {/* Totals preview */}
+      <Card>
+        <CardHeader>{t("editorTotalsHeading")}</CardHeader>
+        <div className="p-4 max-w-sm ml-auto text-sm">
+          <div className="flex justify-between py-1">
+            <span className="text-text-muted">{t("editorSubtotal")}</span>
+            <span className="font-mono">CHF {totals.subtotal.toFixed(2)}</span>
+          </div>
+          <div className="flex justify-between py-1">
+            <span className="text-text-muted">
+              {t("editorVat")} ({totals.vatRate.toFixed(1)}%)
+            </span>
+            <span className="font-mono">CHF {totals.vatAmount.toFixed(2)}</span>
+          </div>
+          <div className="flex justify-between py-2 border-t border-border mt-1 font-medium">
+            <span>{t("editorTotal")}</span>
+            <span className="font-mono">CHF {totals.total.toFixed(2)}</span>
+          </div>
+          <p className="text-xs text-text-muted mt-2 italic">
+            {t("editorTotalsEstimateNote")}
+          </p>
+        </div>
+      </Card>
+
+      {/* Error + actions */}
+      {error && (
+        <div className="text-sm text-error border border-error/30 bg-error/10 rounded-md px-4 py-2">
+          {error}
+        </div>
+      )}
+
+      <div className="flex flex-wrap gap-2 justify-between items-center">
+        <button
+          onClick={deleteDraft}
+          disabled={busy !== null}
+          className="px-4 py-2 rounded-md border border-error text-error text-sm disabled:opacity-50 hover:bg-error/10"
+          type="button"
+        >
+          {busy === "delete" ? t("deleting") : t("editorDeleteBtn")}
+        </button>
+        <div className="flex gap-2 ml-auto">
+          <button
+            onClick={save}
+            disabled={busy !== null || !dirty}
+            className="px-4 py-2 rounded-md border border-border text-sm disabled:opacity-50"
+            type="button"
+          >
+            {busy === "save"
+              ? t("saving")
+              : dirty
+                ? t("editorSaveBtn")
+                : t("editorSavedBtn")}
+          </button>
+          <button
+            onClick={preview}
+            disabled={busy !== null || lines.length === 0}
+            className="px-4 py-2 rounded-md border border-border text-sm disabled:opacity-50"
+            type="button"
+          >
+            {busy === "preview" ? t("previewing") : t("editorPreviewBtn")}
+          </button>
+          <button
+            onClick={issue}
+            disabled={busy !== null || !canIssue}
+            className="px-4 py-2 rounded-md bg-accent text-white text-sm disabled:opacity-50"
+            type="button"
+          >
+            {busy === "issue" ? t("issuing") : t("editorIssueBtn")}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/admin/billing/draft-list.tsx

@@ -0,0 +1,145 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useTranslations, useFormatter } from "next-intl";
+import { Card } from "@/components/ui/card";
+import type { InvoiceDraftRecord } from "@/types";
+
+interface Props {
+  drafts: InvoiceDraftRecord[];
+  /** Map ZITADEL org id → company name for friendlier display. */
+  orgNameMap: Record<string, string>;
+}
+
+/**
+ * Renders the drafts table with per-row Edit / Delete actions.
+ *
+ * The total preview is the algebraic sum of line amounts (the same
+ * formula billing.computeCustomInvoiceTotals uses for the subtotal,
+ * minus VAT — which we don't know without the org's billing
+ * snapshot). It's a hint, not authoritative; the real total
+ * appears when the draft is issued.
+ *
+ * Empty state shows a clear CTA so a fresh admin knows where to
+ * start.
+ */
+export function DraftList({ drafts, orgNameMap }: Props) {
+  const t = useTranslations("adminBilling");
+  const fmt = useFormatter();
+  const router = useRouter();
+  const [busyId, setBusyId] = useState<string | null>(null);
+
+  const onDelete = async (id: string) => {
+    if (!confirm(t("draftDeleteConfirm"))) return;
+    setBusyId(id);
+    try {
+      const res = await fetch(`/api/admin/billing/invoice-drafts/${id}`, {
+        method: "DELETE",
+      });
+      if (!res.ok) {
+        const j = await res.json().catch(() => ({}));
+        throw new Error(j.error || `HTTP ${res.status}`);
+      }
+      router.refresh();
+    } catch (e: any) {
+      alert(e.message);
+    } finally {
+      setBusyId(null);
+    }
+  };
+
+  if (drafts.length === 0) {
+    return (
+      <Card>
+        <div className="p-6 text-center">
+          <p className="text-text-secondary mb-4">{t("draftsEmpty")}</p>
+          <Link
+            href="/admin/billing/invoices/new"
+            className="inline-block px-4 py-2 rounded-md bg-accent text-white text-sm"
+          >
+            {t("newInvoiceBtn")}
+          </Link>
+        </div>
+      </Card>
+    );
+  }
+
+  return (
+    <Card>
+      <div className="flex justify-end p-3 border-b border-border">
+        <Link
+          href="/admin/billing/invoices/new"
+          className="inline-block px-3 py-1.5 rounded-md bg-accent text-white text-sm"
+        >
+          {t("newInvoiceBtn")}
+        </Link>
+      </div>
+      <table className="w-full text-sm">
+        <thead className="text-xs text-text-muted text-left">
+          <tr>
+            <th className="pb-2 pl-3 pr-4">{t("draftOrgCol")}</th>
+            <th className="pb-2 pr-4">{t("draftIssueDateCol")}</th>
+            <th className="pb-2 pr-4 text-center">{t("draftLinesCol")}</th>
+            <th className="pb-2 pr-4 text-right">{t("draftSubtotalCol")}</th>
+            <th className="pb-2 pr-4">{t("draftUpdatedCol")}</th>
+            <th className="pb-2 pr-3 text-right">{t("draftActionsCol")}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {drafts.map((d) => {
+            const subtotal = d.payload.lines.reduce(
+              (s, ln) =>
+                s +
+                Math.round(ln.quantity * ln.unitPriceChf * 100) / 100,
+              0
+            );
+            return (
+              <tr key={d.id} className="border-t border-border">
+                <td className="py-2 pl-3 pr-4">
+                  <Link
+                    href={`/admin/billing/invoice-drafts/${d.id}`}
+                    className="hover:underline"
+                  >
+                    {orgNameMap[d.zitadelOrgId] ?? d.zitadelOrgId}
+                  </Link>
+                </td>
+                <td className="py-2 pr-4 text-xs font-mono text-text-secondary whitespace-nowrap">
+                  {d.payload.issueDate}
+                </td>
+                <td className="py-2 pr-4 text-center text-xs">
+                  {d.payload.lines.length}
+                </td>
+                <td className="py-2 pr-4 text-right font-mono text-xs whitespace-nowrap">
+                  CHF {subtotal.toFixed(2)}
+                </td>
+                <td className="py-2 pr-4 text-xs text-text-muted whitespace-nowrap">
+                  {fmt.dateTime(new Date(d.updatedAt), {
+                    dateStyle: "medium",
+                    timeStyle: "short",
+                  })}
+                </td>
+                <td className="py-2 pr-3 text-right">
+                  <Link
+                    href={`/admin/billing/invoice-drafts/${d.id}`}
+                    className="text-accent hover:underline text-xs mr-3"
+                  >
+                    {t("editBtn")}
+                  </Link>
+                  <button
+                    onClick={() => onDelete(d.id)}
+                    disabled={busyId === d.id}
+                    className="text-error hover:underline text-xs disabled:opacity-50"
+                  >
+                    {busyId === d.id ? t("deleting") : t("deleteBtn")}
+                  </button>
+                </td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </Card>
+  );
+}

src/components/admin/billing/invoice-detail-view.tsx

@@ -4,33 +4,61 @@ import { useState, Fragment } from "react";
 import { useRouter } from "next/navigation";
 import { useTranslations } from "next-intl";
 import { Card, CardHeader } from "@/components/ui/card";
-import type { InvoiceDetail, InvoiceStatus } from "@/types";
+import type { CreditNote, InvoiceDetail, InvoiceStatus } from "@/types";
 
 interface Props {
   detail: InvoiceDetail;
+  /**
+   * Phase 7: credit notes linked to this invoice (voids + refunds).
+   * Empty array when none. Passed from the server page; client
+   * doesn't re-fetch — router.refresh() rebuilds after actions.
+   */
+  creditNotes?: CreditNote[];
 }
 
 /**
  * Renders the invoice header (status, totals, action bar) then
  * line items grouped by tenant, then billing snapshot. Actions are
- * mark-paid (POST), delete (DELETE), PDF download (link to /pdf).
+ * mark-paid (POST), void (POST), refund (POST), delete (DELETE),
+ * PDF download (link to /pdf).
+ *
+ * Phase 7 adds void + refund. The action bar shows:
+ *   - status open/overdue → Mark paid, Void, Delete
+ *   - status paid          → Refund, Delete
+ *   - status partially_refunded → Refund (for remainder), Delete
+ *   - status fully_refunded / void → Delete only (read-only otherwise)
  *
  * On successful action we router.refresh() — the server-side page
- * re-renders against the new DB state. For delete we navigate
- * away first.
+ * re-renders against the new DB state, including any new credit
+ * notes.
  */
-export function InvoiceDetailView({ detail }: Props) {
+export function InvoiceDetailView({ detail, creditNotes = [] }: Props) {
   const t = useTranslations("adminBilling");
   const router = useRouter();
   const { invoice, lines } = detail;
 
-  const [busyAction, setBusyAction] = useState<null | "mark-paid" | "delete">(
-    null
-  );
+  const [busyAction, setBusyAction] = useState<
+    null | "mark-paid" | "delete" | "void" | "refund"
+  >(null);
   const [actionError, setActionError] = useState("");
   const [noteInput, setNoteInput] = useState("");
   const [noteOpen, setNoteOpen] = useState(false);
 
+  // Phase 7 — void modal state
+  const [voidOpen, setVoidOpen] = useState(false);
+  const [voidReason, setVoidReason] = useState("");
+
+  // Phase 7 — refund modal state. Amount defaults to the full
+  // remaining refundable on open.
+  const [refundOpen, setRefundOpen] = useState(false);
+  const [refundAmount, setRefundAmount] = useState("");
+  const [refundReason, setRefundReason] = useState("");
+
+  const remainingRefundable =
+    Math.round(
+      (invoice.totalChf - invoice.refundedTotalChf) * 100
+    ) / 100;
+
   const markPaid = async () => {
     setActionError("");
     setBusyAction("mark-paid");
@@ -75,6 +103,84 @@ export function InvoiceDetailView({ detail }: Props) {
     }
   };
 
+  // Phase 7 — void: marks an unpaid invoice as cancelled and issues
+  // a credit note. Backend rejects if the invoice is paid (use
+  // refund) or already voided/refunded.
+  const voidInvoice = async () => {
+    if (!voidReason.trim()) {
+      setActionError(t("voidReasonRequired"));
+      return;
+    }
+    setActionError("");
+    setBusyAction("void");
+    try {
+      const res = await fetch(
+        `/api/admin/billing/invoices/${invoice.id}/void`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ reason: voidReason }),
+        }
+      );
+      const j = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error(j.error || `HTTP ${res.status}`);
+      setVoidOpen(false);
+      setVoidReason("");
+      router.refresh();
+    } catch (e: any) {
+      setActionError(e.message);
+    } finally {
+      setBusyAction(null);
+    }
+  };
+
+  // Phase 7 — refund: paid invoices only. Amount may be partial;
+  // backend caps at remaining refundable.
+  const refundInvoice = async () => {
+    const amt = parseFloat(refundAmount);
+    if (!isFinite(amt) || amt <= 0) {
+      setActionError(t("refundAmountInvalid"));
+      return;
+    }
+    if (amt - remainingRefundable > 0.005) {
+      setActionError(
+        t("refundAmountExceeds", {
+          max: remainingRefundable.toFixed(2),
+        })
+      );
+      return;
+    }
+    if (!refundReason.trim()) {
+      setActionError(t("refundReasonRequired"));
+      return;
+    }
+    setActionError("");
+    setBusyAction("refund");
+    try {
+      const res = await fetch(
+        `/api/admin/billing/invoices/${invoice.id}/refund`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            amountChf: Math.round(amt * 100) / 100,
+            reason: refundReason,
+          }),
+        }
+      );
+      const j = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error(j.error || `HTTP ${res.status}`);
+      setRefundOpen(false);
+      setRefundAmount("");
+      setRefundReason("");
+      router.refresh();
+    } catch (e: any) {
+      setActionError(e.message);
+    } finally {
+      setBusyAction(null);
+    }
+  };
+
   // Group lines by tenant for display (matches PDF layout).
   const linesByTenant = new Map<string | null, typeof lines>();
   for (const ln of lines) {
@@ -97,10 +203,14 @@ export function InvoiceDetailView({ detail }: Props) {
           </h1>
           <div className="flex items-center gap-3 mt-3 text-sm">
             <StatusPill status={invoice.status} />
-            <span className="text-text-muted">
-              {invoice.periodStart} → {invoice.periodEnd}
-            </span>
-            <span className="text-text-muted">·</span>
+            {invoice.periodStart && invoice.periodEnd && (
+              <>
+                <span className="text-text-muted">
+                  {invoice.periodStart} → {invoice.periodEnd}
+                </span>
+                <span className="text-text-muted">·</span>
+              </>
+            )}
             <span className="text-text-muted">
               {t("dueOnLabel")}: {invoice.dueAt}
             </span>
@@ -171,6 +281,144 @@ export function InvoiceDetailView({ detail }: Props) {
               )}
             </>
           )}
+          {/* Phase 7 — Void: visible only for open/overdue invoices.
+              Same gating as Mark Paid but mutually exclusive with it
+              via the chosen action. Opens a small inline form so
+              the admin can enter a reason; reason is required and
+              lands on the credit-note PDF. */}
+          {(invoice.status === "open" || invoice.status === "overdue") && (
+            <>
+              {!voidOpen ? (
+                <button
+                  onClick={() => {
+                    setVoidOpen(true);
+                    setNoteOpen(false);
+                    setRefundOpen(false);
+                  }}
+                  disabled={busyAction !== null}
+                  className="px-4 py-2 rounded-md border border-error text-error text-sm disabled:opacity-50 hover:bg-error/10"
+                >
+                  {t("voidBtn")}
+                </button>
+              ) : (
+                <div className="flex items-center gap-2 flex-grow">
+                  <input
+                    type="text"
+                    placeholder={t("voidReasonPlaceholder")}
+                    value={voidReason}
+                    onChange={(e) => setVoidReason(e.target.value)}
+                    maxLength={500}
+                    className="flex-grow px-3 py-1.5 rounded-md border border-border bg-surface-2 text-sm"
+                    autoFocus
+                  />
+                  <button
+                    onClick={voidInvoice}
+                    disabled={busyAction !== null}
+                    className="px-3 py-1.5 rounded-md bg-error text-white text-sm disabled:opacity-50"
+                  >
+                    {busyAction === "void" ? t("saving") : t("confirmVoid")}
+                  </button>
+                  <button
+                    onClick={() => {
+                      setVoidOpen(false);
+                      setVoidReason("");
+                    }}
+                    className="px-3 py-1.5 rounded-md border border-border text-sm"
+                  >
+                    {t("cancel")}
+                  </button>
+                </div>
+              )}
+            </>
+          )}
+          {/* Phase 7 — Refund: paid invoices, including ones already
+              partially refunded (as long as some refundable amount
+              remains). Opens an inline form with amount + reason.
+              The remaining-refundable hint helps admin pick the
+              right number. */}
+          {(invoice.status === "paid" ||
+            invoice.status === "partially_refunded") &&
+            remainingRefundable > 0 && (
+              <>
+                {!refundOpen ? (
+                  <button
+                    onClick={() => {
+                      setRefundOpen(true);
+                      setNoteOpen(false);
+                      setVoidOpen(false);
+                      setRefundAmount(remainingRefundable.toFixed(2));
+                    }}
+                    disabled={busyAction !== null}
+                    className="px-4 py-2 rounded-md border border-error text-error text-sm disabled:opacity-50 hover:bg-error/10"
+                  >
+                    {t("refundBtn")}
+                  </button>
+                ) : (
+                  <div className="flex flex-col gap-2 flex-grow">
+                    <div className="text-xs text-text-muted">
+                      {t("refundRemainingHint", {
+                        max: remainingRefundable.toFixed(2),
+                      })}
+                    </div>
+                    <div className="flex items-center gap-4 flex-wrap">
+                      <div className="flex flex-col gap-1">
+                        <label className="text-[10px] uppercase tracking-wider text-text-muted">
+                          {t("refundAmountLabel")}
+                        </label>
+                        <input
+                          type="number"
+                          step="0.01"
+                          min="0.01"
+                          max={remainingRefundable}
+                          placeholder="CHF"
+                          value={refundAmount}
+                          onChange={(e) => setRefundAmount(e.target.value)}
+                          className="w-32 px-3 py-1.5 rounded-md border border-border bg-surface-2 text-sm font-mono"
+                          autoFocus
+                        />
+                        <span className="text-[10px] text-text-muted italic">
+                          {t("refundAmountInclVatHint")}
+                        </span>
+                      </div>
+                      <div className="flex flex-col gap-1 flex-grow min-w-[200px]">
+                        <label className="text-[10px] uppercase tracking-wider text-text-muted">
+                          {t("refundReasonLabel")}
+                        </label>
+                        <input
+                          type="text"
+                          placeholder={t("refundReasonPlaceholder")}
+                          value={refundReason}
+                          onChange={(e) => setRefundReason(e.target.value)}
+                          maxLength={500}
+                          className="w-full px-3 py-1.5 rounded-md border border-border bg-surface-2 text-sm"
+                        />
+                      </div>
+                      <div className="flex items-center gap-2 self-end">
+                        <button
+                          onClick={refundInvoice}
+                          disabled={busyAction !== null}
+                          className="px-3 py-1.5 rounded-md bg-error text-white text-sm disabled:opacity-50"
+                        >
+                          {busyAction === "refund"
+                            ? t("saving")
+                            : t("confirmRefund")}
+                        </button>
+                        <button
+                          onClick={() => {
+                            setRefundOpen(false);
+                            setRefundAmount("");
+                            setRefundReason("");
+                          }}
+                          className="px-3 py-1.5 rounded-md border border-border text-sm"
+                        >
+                          {t("cancel")}
+                        </button>
+                      </div>
+                    </div>
+                  </div>
+                )}
+              </>
+            )}
           <button
             onClick={deleteInvoice}
             disabled={busyAction !== null}
@@ -189,8 +437,90 @@ export function InvoiceDetailView({ detail }: Props) {
             {invoice.paidMethodDetail}
           </div>
         )}
+        {/* Phase 7 — void/refund summary lines, shown when applicable.
+            Surfaces the auditing context that the columns alone don't
+            (who voided, what the reason was, how much has been
+            refunded vs how much remains). */}
+        {invoice.voidedAt && (
+          <div className="mt-3 text-xs text-text-muted">
+            {t("voidedOnLabel")}: {invoice.voidedAt} · {invoice.voidedBy}
+            {invoice.voidReason ? ` · ${invoice.voidReason}` : ""}
+          </div>
+        )}
+        {invoice.refundedTotalChf > 0 && (
+          <div className="mt-3 text-xs text-text-muted">
+            {t("refundedTotalLabel")}: CHF{" "}
+            {invoice.refundedTotalChf.toFixed(2)} ·{" "}
+            {t("refundedRemainingLabel")}: CHF{" "}
+            {remainingRefundable.toFixed(2)}
+          </div>
+        )}
       </Card>
 
+      {/* Phase 7 — linked credit notes panel. Hidden when there are
+          none (most invoices). When present, lists each credit note
+          with kind, amount, reason, issued date, and PDF download. */}
+      {creditNotes.length > 0 && (
+        <Card>
+          <CardHeader>{t("creditNotesPanelTitle")}</CardHeader>
+          <table className="w-full text-sm">
+            <thead className="text-xs text-text-muted text-left">
+              <tr>
+                <th className="pb-2 pr-4">{t("creditNoteNumberHeader")}</th>
+                <th className="pb-2 pr-4">{t("creditNoteKindHeader")}</th>
+                <th className="pb-2 pr-4 text-right">
+                  {t("creditNoteAmountHeader")}
+                </th>
+                <th className="pb-2 pr-4">{t("creditNoteReasonHeader")}</th>
+                <th className="pb-2 pr-4">{t("creditNoteIssuedHeader")}</th>
+                <th className="pb-2 text-right">{t("creditNotePdfHeader")}</th>
+              </tr>
+            </thead>
+            <tbody>
+              {creditNotes.map((cn) => (
+                <tr key={cn.id} className="border-t border-border">
+                  <td className="py-2 pr-4 font-mono text-xs">
+                    {cn.creditNoteNumber}
+                  </td>
+                  <td className="py-2 pr-4">
+                    <span className="px-2 py-0.5 rounded text-xs text-error bg-error/10">
+                      {t(`creditNoteKind_${cn.kind}` as any)}
+                    </span>
+                  </td>
+                  <td className="py-2 pr-4 text-right font-mono whitespace-nowrap">
+                    CHF {cn.amountChf.toFixed(2)}
+                  </td>
+                  <td className="py-2 pr-4 text-text-secondary text-xs">
+                    {cn.reason ?? "—"}
+                  </td>
+                  <td className="py-2 pr-4 text-xs text-text-muted whitespace-nowrap">
+                    {cn.issuedAt.slice(0, 10)}
+                  </td>
+                  <td className="py-2 text-right">
+                    {cn.hasPdf ? (
+                      <a
+                        href={`/api/credit-notes/${encodeURIComponent(
+                          cn.creditNoteNumber
+                        )}/pdf`}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="text-accent hover:underline text-xs"
+                      >
+                        {t("downloadPdfBtn")}
+                      </a>
+                    ) : (
+                      <span className="text-text-muted text-xs italic">
+                        {t("creditNoteNoPdf")}
+                      </span>
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </Card>
+      )}
+
       {/* Lines */}
       <Card>
         <CardHeader>{t("lineItemsTitle")}</CardHeader>
@@ -296,7 +626,9 @@ function StatusPill({ status }: { status: InvoiceStatus }) {
         ? "bg-error/15 text-error"
         : status === "void" || status === "uncollectible"
           ? "bg-text-muted/15 text-text-muted"
-          : "bg-accent/15 text-accent";
+          : status === "partially_refunded" || status === "fully_refunded"
+            ? "bg-error/15 text-error"
+            : "bg-accent/15 text-accent";
   return (
     <span
       className={`inline-block px-2 py-0.5 rounded text-xs font-medium ${color}`}

src/components/admin/billing/invoices-table.tsx

@@ -100,6 +100,23 @@ export function InvoicesTable({ initialInvoices }: Props) {
               {t("loading")}
             </span>
           )}
+          {/* Phase 8: shortcuts to the custom-invoice flow. The
+              Drafts link is muted because most of the time it's
+              empty; New invoice is the prominent CTA. */}
+          <div className={`flex items-center gap-3 ${busy ? "" : "ml-auto"}`}>
+            <Link
+              href="/admin/billing/invoice-drafts"
+              className="text-xs text-text-muted hover:underline"
+            >
+              {t("draftsLink")}
+            </Link>
+            <Link
+              href="/admin/billing/invoices/new"
+              className="px-3 py-1.5 rounded-md bg-accent text-white text-sm"
+            >
+              + {t("newInvoiceBtn")}
+            </Link>
+          </div>
         </div>
       </Card>
 
@@ -142,7 +159,11 @@ export function InvoicesTable({ initialInvoices }: Props) {
                     </div>
                   </td>
                   <td className="py-2 text-xs font-mono">
-                    {inv.periodStart.slice(0, 7)}
+                    {inv.periodStart
+                      ? inv.periodStart.slice(0, 7)
+                      : inv.source === "custom"
+                        ? "—"
+                        : ""}
                   </td>
                   <td className="py-2">
                     <StatusPill status={inv.status} />

src/components/admin/billing/new-invoice-form.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { Card } from "@/components/ui/card";
+
+interface OrgEntry {
+  zitadelOrgId: string;
+  companyName: string | null;
+  country: string | null;
+  hasBillingAddress: boolean;
+}
+
+interface Props {
+  orgs: OrgEntry[];
+}
+
+const LOCALE_OPTIONS = [
+  { value: "de", label: "Deutsch" },
+  { value: "en", label: "English" },
+  { value: "fr", label: "Français" },
+  { value: "it", label: "Italiano" },
+];
+
+/**
+ * Step 1 of the custom-invoice flow: pick an org. Creating the
+ * draft on the backend allocates an id we redirect to; the editor
+ * page then loads the draft and lets the admin add lines.
+ *
+ * The dropdown shows the company name when known, falling back to
+ * the raw org id. Orgs without a billing snapshot are visually
+ * marked and warn the admin — they can still create the draft but
+ * won't be able to issue until billing info is set.
+ *
+ * Default issue date = today; due date = today + 30 days. These
+ * are sensible defaults the editor can override.
+ */
+export function NewInvoiceForm({ orgs }: Props) {
+  const t = useTranslations("adminBilling");
+  const router = useRouter();
+  const [orgId, setOrgId] = useState(
+    orgs.find((o) => o.hasBillingAddress)?.zitadelOrgId ??
+      orgs[0]?.zitadelOrgId ??
+      ""
+  );
+  const [locale, setLocale] = useState<"de" | "en" | "fr" | "it">("de");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+
+  const selected = orgs.find((o) => o.zitadelOrgId === orgId);
+
+  // Pick a locale default from the org's country if admin hasn't
+  // overridden — same heuristic the auto cron uses.
+  const onOrgChange = (newOrgId: string) => {
+    setOrgId(newOrgId);
+    const o = orgs.find((x) => x.zitadelOrgId === newOrgId);
+    const c = (o?.country ?? "").toUpperCase();
+    if (["CH", "LI", "AT", "DE"].includes(c)) setLocale("de");
+    else if (["FR", "BE", "LU"].includes(c)) setLocale("fr");
+    else if (c === "IT") setLocale("it");
+    else setLocale("en");
+  };
+
+  const onSubmit = async () => {
+    if (!orgId) {
+      setError(t("newInvoiceOrgRequired"));
+      return;
+    }
+    setError("");
+    setBusy(true);
+    try {
+      const today = new Date().toISOString().slice(0, 10);
+      const due = new Date();
+      due.setDate(due.getDate() + 30);
+      const dueIso = due.toISOString().slice(0, 10);
+      const res = await fetch("/api/admin/billing/invoice-drafts", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          zitadelOrgId: orgId,
+          payload: {
+            issueDate: today,
+            dueDate: dueIso,
+            locale,
+            paymentMethod: "invoice",
+            lines: [],
+          },
+        }),
+      });
+      const j = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error(j.error || `HTTP ${res.status}`);
+      router.push(`/admin/billing/invoice-drafts/${j.draft.id}`);
+    } catch (e: any) {
+      setError(e.message);
+      setBusy(false);
+    }
+  };
+
+  return (
+    <Card>
+      <div className="p-5 flex flex-col gap-4">
+        <div className="flex flex-col gap-1">
+          <label className="text-xs uppercase tracking-wider text-text-muted">
+            {t("newInvoiceOrgLabel")}
+          </label>
+          <select
+            value={orgId}
+            onChange={(e) => onOrgChange(e.target.value)}
+            className="px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+          >
+            <option value="">{t("newInvoiceOrgPlaceholder")}</option>
+            {orgs.map((o) => (
+              <option
+                key={o.zitadelOrgId}
+                value={o.zitadelOrgId}
+                disabled={!o.hasBillingAddress}
+              >
+                {o.companyName ?? o.zitadelOrgId}
+                {!o.hasBillingAddress
+                  ? ` (${t("newInvoiceOrgNoBilling")})`
+                  : ""}
+              </option>
+            ))}
+          </select>
+          {selected && !selected.hasBillingAddress && (
+            <p className="text-xs text-error mt-1">
+              {t("newInvoiceOrgBillingMissing")}
+            </p>
+          )}
+        </div>
+
+        <div className="flex flex-col gap-1">
+          <label className="text-xs uppercase tracking-wider text-text-muted">
+            {t("newInvoiceLocaleLabel")}
+          </label>
+          <select
+            value={locale}
+            onChange={(e) =>
+              setLocale(e.target.value as "de" | "en" | "fr" | "it")
+            }
+            className="px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+          >
+            {LOCALE_OPTIONS.map((o) => (
+              <option key={o.value} value={o.value}>
+                {o.label}
+              </option>
+            ))}
+          </select>
+        </div>
+
+        {error && <div className="text-sm text-error">{error}</div>}
+
+        <div className="flex justify-end gap-2 pt-2">
+          <button
+            onClick={onSubmit}
+            disabled={busy || !orgId || !selected?.hasBillingAddress}
+            className="px-4 py-2 rounded-md bg-accent text-white text-sm disabled:opacity-50"
+          >
+            {busy ? t("creating") : t("newInvoiceContinueBtn")}
+          </button>
+        </div>
+      </div>
+    </Card>
+  );
+}

src/components/admin/cron/cron-controls.tsx

@@ -0,0 +1,249 @@
+"use client";
+
+import { useState } from "react";
+import { useTranslations, useFormatter } from "next-intl";
+import { Card } from "@/components/ui/card";
+import type { CronRun } from "@/types";
+
+interface Props {
+  initialRecent: CronRun[];
+  initialLastSuccess: {
+    monthlyIssue: CronRun | null;
+    reminders: CronRun | null;
+  };
+}
+
+/**
+ * Admin cron dashboard. Server pre-loads `initialRecent` and
+ * `initialLastSuccess`; "Run now" clicks POST to the admin
+ * endpoints, then re-fetch the history via GET /api/admin/cron/runs.
+ *
+ * The trigger buttons disable while busy and surface the resulting
+ * counters inline so the admin gets immediate feedback without
+ * needing to scroll to the history table.
+ */
+export function CronControls({ initialRecent, initialLastSuccess }: Props) {
+  const t = useTranslations("adminCron");
+  const fmt = useFormatter();
+  const [recent, setRecent] = useState(initialRecent);
+  const [lastSuccess, setLastSuccess] = useState(initialLastSuccess);
+  const [busy, setBusy] = useState<null | "issue" | "reminders">(null);
+  const [flash, setFlash] = useState<null | {
+    kind: "issue" | "reminders";
+    ok: boolean;
+    summary: string;
+  }>(null);
+
+  const refresh = async () => {
+    try {
+      const res = await fetch("/api/admin/cron/runs");
+      if (!res.ok) return;
+      const data = await res.json();
+      setRecent(data.recent);
+      setLastSuccess(data.lastSuccess);
+    } catch {
+      // swallow — refresh is opportunistic
+    }
+  };
+
+  const triggerIssue = async () => {
+    setBusy("issue");
+    setFlash(null);
+    try {
+      const res = await fetch("/api/admin/cron/issue-monthly", {
+        method: "POST",
+      });
+      const j = await res.json();
+      if (!res.ok) {
+        setFlash({
+          kind: "issue",
+          ok: false,
+          summary: j.error ?? `HTTP ${res.status}`,
+        });
+      } else {
+        setFlash({
+          kind: "issue",
+          ok: true,
+          summary: t("flashIssueOk", {
+            success: j.successCount,
+            skipped: j.skippedCount,
+            failure: j.failureCount,
+          }),
+        });
+      }
+      await refresh();
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const triggerReminders = async () => {
+    setBusy("reminders");
+    setFlash(null);
+    try {
+      const res = await fetch("/api/admin/cron/send-reminders", {
+        method: "POST",
+      });
+      const j = await res.json();
+      if (!res.ok) {
+        setFlash({
+          kind: "reminders",
+          ok: false,
+          summary: j.error ?? `HTTP ${res.status}`,
+        });
+      } else {
+        setFlash({
+          kind: "reminders",
+          ok: true,
+          summary: t("flashRemindersOk", {
+            success: j.successCount,
+            skipped: j.skippedCount,
+            failure: j.failureCount,
+          }),
+        });
+      }
+      await refresh();
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const fmtRelative = (iso: string | null) => {
+    if (!iso) return t("never");
+    return fmt.dateTime(new Date(iso), {
+      dateStyle: "medium",
+      timeStyle: "short",
+    });
+  };
+
+  // Phase 6: surface failures prominently. Any run in the recent
+  // window with a non-zero failure_count drives a top-of-page
+  // banner — the row in the table is already red, but a banner
+  // means the admin doesn't have to scroll to notice.
+  const recentFailures = recent.filter((r) => r.failureCount > 0);
+  const hasRecentFailures = recentFailures.length > 0;
+
+  return (
+    <div className="space-y-8">
+      {hasRecentFailures && (
+        <div className="p-4 rounded-md border border-error bg-error/10 text-sm text-error">
+          <p className="font-medium mb-1">{t("failureBannerTitle")}</p>
+          <p className="text-xs">
+            {t("failureBannerBody", { count: recentFailures.length })}
+          </p>
+        </div>
+      )}
+      <section className="grid gap-4 md:grid-cols-2">
+        <Card>
+          <h2 className="text-xs uppercase tracking-wider text-text-muted mb-2">
+            {t("monthlyIssue")}
+          </h2>
+          <p className="text-xs text-text-secondary mb-1">
+            {t("scheduleIssueLabel")}: <span className="font-mono">{t("scheduleIssueValue")}</span>
+          </p>
+          <p className="text-xs text-text-secondary mb-3">
+            {t("lastSuccess")}: <span className="font-mono">{fmtRelative(lastSuccess.monthlyIssue?.startedAt ?? null)}</span>
+          </p>
+          <button
+            onClick={triggerIssue}
+            disabled={busy !== null}
+            className="px-4 py-2 rounded-md bg-accent text-white text-sm font-medium hover:bg-accent-dim transition-colors disabled:opacity-50 cursor-pointer"
+          >
+            {busy === "issue" ? t("running") : t("runIssueNow")}
+          </button>
+        </Card>
+        <Card>
+          <h2 className="text-xs uppercase tracking-wider text-text-muted mb-2">
+            {t("reminders")}
+          </h2>
+          <p className="text-xs text-text-secondary mb-1">
+            {t("scheduleReminderLabel")}: <span className="font-mono">{t("scheduleReminderValue")}</span>
+          </p>
+          <p className="text-xs text-text-secondary mb-3">
+            {t("lastSuccess")}: <span className="font-mono">{fmtRelative(lastSuccess.reminders?.startedAt ?? null)}</span>
+          </p>
+          <button
+            onClick={triggerReminders}
+            disabled={busy !== null}
+            className="px-4 py-2 rounded-md bg-accent text-white text-sm font-medium hover:bg-accent-dim transition-colors disabled:opacity-50 cursor-pointer"
+          >
+            {busy === "reminders" ? t("running") : t("runRemindersNow")}
+          </button>
+        </Card>
+      </section>
+
+      {flash && (
+        <div
+          className={`p-3 rounded-md border text-sm ${
+            flash.ok
+              ? "border-success bg-success/10 text-success"
+              : "border-error bg-error/10 text-error"
+          }`}
+        >
+          {flash.summary}
+        </div>
+      )}
+
+      <section>
+        <h2 className="text-xs uppercase tracking-wider text-text-muted mb-3">
+          {t("recentRuns")}
+        </h2>
+        <Card>
+          {recent.length === 0 ? (
+            <p className="text-sm text-text-muted italic py-4">
+              {t("noRunsYet")}
+            </p>
+          ) : (
+            <table className="w-full text-sm">
+              <thead className="text-xs text-text-muted text-left">
+                <tr>
+                  <th className="pb-2">{t("startedCol")}</th>
+                  <th className="pb-2">{t("kindCol")}</th>
+                  <th className="pb-2">{t("triggeredByCol")}</th>
+                  <th className="pb-2 text-right">{t("okCol")}</th>
+                  <th className="pb-2 text-right">{t("skipCol")}</th>
+                  <th className="pb-2 text-right">{t("failCol")}</th>
+                </tr>
+              </thead>
+              <tbody>
+                {recent.map((r) => (
+                  <tr
+                    key={r.id}
+                    className={`border-t border-border align-top ${
+                      r.failureCount > 0 ? "bg-error/5" : ""
+                    }`}
+                  >
+                    <td className="py-2 text-xs font-mono">
+                      {fmtRelative(r.startedAt)}
+                    </td>
+                    <td className="py-2 text-xs">
+                      {t(`kind.${r.runKind}` as any)}
+                    </td>
+                    <td className="py-2 text-xs text-text-secondary font-mono">
+                      {r.triggeredBy === "cron"
+                        ? t("triggeredByCron")
+                        : r.triggeredBy.slice(0, 8) + "…"}
+                    </td>
+                    <td className="py-2 text-right font-mono text-xs text-success">
+                      {r.successCount}
+                    </td>
+                    <td className="py-2 text-right font-mono text-xs text-text-secondary">
+                      {r.skippedCount}
+                    </td>
+                    <td
+                      className={`py-2 text-right font-mono text-xs ${
+                        r.failureCount > 0 ? "text-error" : "text-text-muted"
+                      }`}
+                    >
+                      {r.failureCount}
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          )}
+        </Card>
+      </section>
+    </div>
+  );
+}

src/components/billing/customer-credit-note-list.tsx

@@ -0,0 +1,101 @@
+import { useTranslations, useFormatter } from "next-intl";
+import { Card } from "@/components/ui/card";
+import type { CreditNote } from "@/types";
+
+interface Props {
+  creditNotes: CreditNote[];
+}
+
+const kindColors: Record<string, string> = {
+  // Voids = the invoice was cancelled; gentle red.
+  void: "text-error bg-error/10",
+  // Refunds = money returned; also red but slightly differentiated.
+  refund: "text-error bg-error/10",
+};
+
+/**
+ * Phase 7 — customer's credit-note history below the invoice list.
+ *
+ * Hidden entirely when the org has zero credit notes (most orgs in
+ * normal operation). When present, each row shows the credit-note
+ * number, the invoice it relates to, kind (void / refund), amount,
+ * and a download link to the PDF.
+ *
+ * No detail page — clicking the PDF link opens the document inline
+ * (browser PDF viewer), which IS the credit-note detail view. A
+ * separate per-credit-note web page would duplicate what's in the
+ * PDF and add no value.
+ */
+export function CustomerCreditNoteList({ creditNotes }: Props) {
+  const t = useTranslations("customerBilling");
+  const fmt = useFormatter();
+
+  if (creditNotes.length === 0) {
+    return null;
+  }
+
+  return (
+    <Card>
+      <table className="w-full text-sm">
+        <thead className="text-xs text-text-muted text-left">
+          <tr>
+            <th className="pb-2 pr-4">{t("creditNoteNumberCol")}</th>
+            <th className="pb-2 pr-4">{t("creditNoteInvoiceCol")}</th>
+            <th className="pb-2 pr-4">{t("creditNoteIssuedCol")}</th>
+            <th className="pb-2 pr-4 text-right">{t("creditNoteAmountCol")}</th>
+            <th className="pb-2 pr-4 text-right">{t("creditNoteKindCol")}</th>
+            <th className="pb-2 text-right">{t("creditNotePdfCol")}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {creditNotes.map((cn) => (
+            <tr
+              key={cn.id}
+              className="border-t border-border align-middle"
+            >
+              <td className="py-2 pr-4 font-mono text-xs">
+                {cn.creditNoteNumber}
+              </td>
+              <td className="py-2 pr-4 font-mono text-xs text-text-secondary">
+                {cn.invoiceNumber}
+              </td>
+              <td className="py-2 pr-4 text-text-secondary whitespace-nowrap">
+                {fmt.dateTime(new Date(cn.issuedAt), { dateStyle: "medium" })}
+              </td>
+              <td className="py-2 pr-4 text-right font-mono whitespace-nowrap">
+                CHF {cn.amountChf.toFixed(2)}
+              </td>
+              <td className="py-2 pr-4 text-right">
+                <span
+                  className={`px-2 py-0.5 rounded text-xs ${
+                    kindColors[cn.kind] ?? ""
+                  }`}
+                >
+                  {t(`creditNoteKind_${cn.kind}` as any)}
+                </span>
+              </td>
+              <td className="py-2 text-right">
+                {cn.hasPdf ? (
+                  <a
+                    href={`/api/credit-notes/${encodeURIComponent(
+                      cn.creditNoteNumber
+                    )}/pdf`}
+                    className="text-accent hover:underline text-xs"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                  >
+                    {t("downloadPdf")}
+                  </a>
+                ) : (
+                  <span className="text-text-muted text-xs italic">
+                    {t("creditNoteNoPdf")}
+                  </span>
+                )}
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </Card>
+  );
+}

src/components/billing/customer-invoice-detail.tsx

@@ -46,11 +46,17 @@ export function CustomerInvoiceDetail({ invoice, lines }: Props) {
               {t(`status.${invoice.status}` as any)}
             </span>
           </div>
-          <p className="text-sm text-text-secondary">
-            {fmt.dateTime(new Date(invoice.periodStart), { dateStyle: "long" })}
-            <span className="text-text-muted mx-1">→</span>
-            {fmt.dateTime(new Date(invoice.periodEnd), { dateStyle: "long" })}
-          </p>
+          {invoice.periodStart && invoice.periodEnd && (
+            <p className="text-sm text-text-secondary">
+              {fmt.dateTime(new Date(invoice.periodStart), {
+                dateStyle: "long",
+              })}
+              <span className="text-text-muted mx-1">→</span>
+              {fmt.dateTime(new Date(invoice.periodEnd), {
+                dateStyle: "long",
+              })}
+            </p>
+          )}
         </div>
         <div className="flex items-start gap-2 flex-wrap">
           {/* Phase 4: Pay-with-card available for open + overdue.

src/components/billing/customer-invoice-list.tsx

@@ -12,6 +12,13 @@ const statusColors: Record<string, string> = {
   paid: "text-success bg-success/10",
   overdue: "text-error bg-error/10",
   void: "text-text-muted bg-surface-3 line-through",
+  // Phase 7: refund states. Red tinting matches the credit-note
+  // PDF accent so customers reading the table get a visual cue
+  // that something was credited back. partially_refunded reads
+  // as a partial state (mixed colour), fully_refunded reads as
+  // closed (line-through like void).
+  partially_refunded: "text-error bg-error/10",
+  fully_refunded: "text-text-muted bg-error/10 line-through",
 };
 
 /**
@@ -64,9 +71,19 @@ export function CustomerInvoiceList({ invoices }: Props) {
                 </Link>
               </td>
               <td className="py-2 text-xs text-text-secondary">
-                {fmt.dateTime(new Date(inv.periodStart), { dateStyle: "medium" })}
-                <span className="text-text-muted mx-1">→</span>
-                {fmt.dateTime(new Date(inv.periodEnd), { dateStyle: "medium" })}
+                {inv.periodStart && inv.periodEnd ? (
+                  <>
+                    {fmt.dateTime(new Date(inv.periodStart), {
+                      dateStyle: "medium",
+                    })}
+                    <span className="text-text-muted mx-1">→</span>
+                    {fmt.dateTime(new Date(inv.periodEnd), {
+                      dateStyle: "medium",
+                    })}
+                  </>
+                ) : (
+                  <span className="text-text-muted">—</span>
+                )}
               </td>
               <td className="py-2 text-xs text-text-secondary">
                 {fmt.dateTime(new Date(inv.dueAt), { dateStyle: "medium" })}

src/components/billing/payment-status-banner.tsx

@@ -30,13 +30,14 @@ export function PaymentStatusBanner() {
     const params = new URLSearchParams(window.location.search);
     if (params.has("paid")) {
       setState("paid");
-      // Reload after 4s so the status badge picks up the webhook's
-      // effect on the invoice row. By then most webhook deliveries
-      // have landed; if not the user just sees "open" and can
-      // manually refresh.
+      // The webhook usually arrives before the browser redirect
+      // completes, so the page often renders with status='paid'
+      // on first load and this refresh is a no-op. In the rare
+      // case where it arrives slightly after, a short refresh
+      // picks up the status flip. 1.5s is comfortable for both.
       const timer = setTimeout(() => {
         router.refresh();
-      }, 4000);
+      }, 1500);
       // Strip the query string out of the URL.
       const cleanUrl = window.location.pathname;
       window.history.replaceState({}, "", cleanUrl);

src/components/billing/running-total-widget.tsx

@@ -11,6 +11,17 @@ type CurrentResponse =
   | { draft: InvoiceDraft }
   | { error: string; code?: string };
 
+interface Props {
+  /**
+   * Whether the viewing user has org-owner role. Drives the
+   * "complete your billing details" CTA — only owners can edit
+   * billing settings, so non-owners see a softer message asking
+   * them to contact their org owner instead. The flag is computed
+   * server-side and passed in to avoid a second API round-trip.
+   */
+  isOwner: boolean;
+}
+
 /**
  * Live running total for the current calendar month.
  *
@@ -28,7 +39,7 @@ type CurrentResponse =
  * No polling — the page is static enough that an explicit
  * "refresh" link is good enough if the user wants newer numbers.
  */
-export function RunningTotalWidget() {
+export function RunningTotalWidget({ isOwner }: Props) {
   const t = useTranslations("customerBilling");
   const fmt = useFormatter();
   const [data, setData] = useState<CurrentResponse | null>(null);
@@ -62,13 +73,29 @@ export function RunningTotalWidget() {
     );
   }
   if (!data || "error" in data) {
+    const noConfig =
+      data && "code" in data && data.code === "COMPUTE_FAILED";
     return (
       <Card>
         <p className="text-sm text-text-secondary py-2">
-          {data && "code" in data && data.code === "COMPUTE_FAILED"
-            ? t("noBillingConfig")
-            : t("currentPeriodError")}
+          {noConfig ? t("noBillingConfig") : t("currentPeriodError")}
         </p>
+        {/* Phase 6: owner-only CTA. Non-owners can't edit billing
+            settings, so we show them a "contact owner" hint instead
+            — that's gentler than a button that 404s on click. */}
+        {noConfig && isOwner && (
+          <Link
+            href="/settings/billing"
+            className="inline-block mt-2 px-4 py-2 rounded-md bg-accent text-white text-sm font-medium hover:bg-accent-dim transition-colors"
+          >
+            {t("configureBillingCta")}
+          </Link>
+        )}
+        {noConfig && !isOwner && (
+          <p className="text-xs text-text-muted italic mt-2">
+            {t("noBillingConfigNonOwner")}
+          </p>
+        )}
       </Card>
     );
   }
@@ -98,9 +125,16 @@ export function RunningTotalWidget() {
   }
   // draft
   const draft = data.draft;
-  const periodLabel = `${fmt.dateTime(new Date(draft.periodStart), {
-    dateStyle: "long",
-  })} → ${fmt.dateTime(new Date(draft.periodEnd), { dateStyle: "long" })}`;
+  // Phase 8: InvoiceDraft.periodStart/End became nullable for the
+  // custom-invoice flow. The running-total widget only renders the
+  // auto-cron draft (always has a period), so the null branch is
+  // defensive — if we ever did hit it the label just collapses.
+  const periodLabel =
+    draft.periodStart && draft.periodEnd
+      ? `${fmt.dateTime(new Date(draft.periodStart), {
+          dateStyle: "long",
+        })} → ${fmt.dateTime(new Date(draft.periodEnd), { dateStyle: "long" })}`
+      : "";
   return (
     <Card>
       <div className="flex items-start justify-between gap-4 flex-wrap mb-3">

src/components/onboarding/onboarding-flow.tsx

@@ -2,6 +2,7 @@
 
 import { useRouter } from "next/navigation";
 import { OnboardingWizard } from "./wizard";
+import type { OrgBilling } from "@/types";
 
 interface OnboardingFlowProps {
   orgName: string;
@@ -19,6 +20,12 @@ interface OnboardingFlowProps {
    * /settings/billing.
    */
   hasOrgBilling?: boolean;
+  /**
+   * Phase 6 fix3: the actual org_billing record (or null). Drives
+   * the review-step "Billing to" rendering AND the confirm-step
+   * validation skip when the billing step was skipped.
+   */
+  existingOrgBilling?: OrgBilling | null;
   /**
    * Bug 6: when present, the wizard is rendered in edit mode against
    * the given pending request. See `OnboardingWizard` for the full
@@ -45,6 +52,7 @@ export function OnboardingFlow({
   userName,
   userEmail,
   hasOrgBilling,
+  existingOrgBilling,
   editingRequest,
 }: OnboardingFlowProps) {
   const router = useRouter();
@@ -55,6 +63,7 @@ export function OnboardingFlow({
       userName={userName}
       userEmail={userEmail}
       hasOrgBilling={hasOrgBilling}
+      existingOrgBilling={existingOrgBilling}
       editingRequest={editingRequest}
       onComplete={() => {
         // Navigate back to /dashboard and re-fetch on the server. The

src/components/onboarding/wizard.tsx

@@ -13,6 +13,7 @@ import {
   SUPPORTED_COUNTRIES,
   type SupportedCountry,
 } from "@/lib/validation";
+import type { OrgBilling } from "@/types";
 
 type Step = "welcome" | "configure" | "billing" | "confirm";
 
@@ -96,6 +97,17 @@ interface WizardProps {
    * fix it before admin approves.
    */
   hasOrgBilling?: boolean;
+  /**
+   * Phase 6 fix3: the actual org_billing record when one exists.
+   * Used to render real values on the review-step "Billing to" block
+   * (rather than the wizard's empty default config.billingAddress)
+   * AND to skip the confirm-step's client-side validation of
+   * billingAddress — same logic that already strips billingAddress
+   * at submit time. Null when no org_billing row exists yet.
+   * Ignored in edit mode (the editingRequest carries its own
+   * billingAddress snapshot).
+   */
+  existingOrgBilling?: OrgBilling | null;
   /**
    * Bug 6: when present, the wizard renders in "edit" mode — fields
    * are pre-populated from the request, the SOUL.md auto-fetch is
@@ -134,6 +146,7 @@ export function OnboardingWizard({
   userName,
   userEmail,
   hasOrgBilling,
+  existingOrgBilling,
   editingRequest,
   onComplete,
 }: WizardProps) {
@@ -319,7 +332,23 @@ export function OnboardingWizard({
     }
     // confirm: validate the union (defence in depth — submit handler
     // also runs onboardingSchema before POST).
-    const r = onboardingSchema.safeParse(config);
+    //
+    // Phase 6 fix3: when hasOrgBilling=true AND not editing, the
+    // billing step was skipped and config.billingAddress is the
+    // empty default. zod's .optional() doesn't help here because the
+    // field IS present (empty object), so billingAddressSchema
+    // validates it and fails with required-field errors that the
+    // user has no way to fix — the form to enter the values was
+    // skipped on purpose. Strip the field for validation, matching
+    // the same strip we already do at submit time.
+    const configForValidation =
+      hasOrgBilling && !isEditing
+        ? (() => {
+            const { billingAddress: _b, ...rest } = config;
+            return rest;
+          })()
+        : config;
+    const r = onboardingSchema.safeParse(configForValidation);
     if (r.success) {
       setErrors({});
       return true;
@@ -1101,42 +1130,84 @@ export function OnboardingWizard({
               <ReviewRow
                 label={t("reviewBillingTo")}
                 value={
-                  <div className="text-text-primary text-right">
-                    {/* For personal: skip the company line so the
-                        invoice rendering matches what the user actually
-                        entered. For company: include it as the first
-                        line. */}
-                    {!isPersonal &&
-                      config.billingAddress.company &&
-                      config.billingAddress.company.trim().length > 0 && (
-                        <div>{config.billingAddress.company}</div>
-                      )}
-                    <div>{config.billingAddress.street}</div>
-                    <div>
-                      {config.billingAddress.postalCode}{" "}
-                      {config.billingAddress.city}
-                    </div>
-                    <div className="text-text-muted">
-                      {tCountries(
-                        config.billingAddress.country as SupportedCountry
-                      )}
-                    </div>
-                  </div>
+                  (() => {
+                    // Phase 6 fix3: when the org has billing on file
+                    // and we're not editing, render the saved
+                    // org_billing record (the authoritative source)
+                    // rather than config.billingAddress, which is the
+                    // wizard's empty default state because the billing
+                    // step was skipped. In edit mode, fall back to
+                    // config.billingAddress, which is pre-populated
+                    // from the request being edited.
+                    const useSaved =
+                      hasOrgBilling && !isEditing && existingOrgBilling;
+                    const company = useSaved
+                      ? existingOrgBilling!.companyName
+                      : config.billingAddress.company;
+                    const street = useSaved
+                      ? existingOrgBilling!.streetAddress
+                      : config.billingAddress.street;
+                    const postalCode = useSaved
+                      ? existingOrgBilling!.postalCode
+                      : config.billingAddress.postalCode;
+                    const city = useSaved
+                      ? existingOrgBilling!.city
+                      : config.billingAddress.city;
+                    const country = useSaved
+                      ? existingOrgBilling!.country
+                      : config.billingAddress.country;
+                    const contactName = useSaved
+                      ? existingOrgBilling!.contactName
+                      : null;
+                    return (
+                      <div className="text-text-primary text-right">
+                        {/* For personal: skip the company line so the
+                            invoice rendering matches what the user actually
+                            entered. For company: include it as the first
+                            line. */}
+                        {!isPersonal &&
+                          company &&
+                          company.trim().length > 0 && <div>{company}</div>}
+                        {/* Phase 6 fix2: optional contact-person line
+                            ("z.Hd. <name>") only present when the saved
+                            org_billing has it set. */}
+                        {contactName && contactName.trim().length > 0 && (
+                          <div className="text-text-muted">
+                            {t("reviewContactPersonPrefix")} {contactName}
+                          </div>
+                        )}
+                        <div>{street}</div>
+                        <div>
+                          {postalCode} {city}
+                        </div>
+                        <div className="text-text-muted">
+                          {tCountries(country as SupportedCountry)}
+                        </div>
+                      </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. */}
+                  VAT number, the form didn't ask, the review hides it.
+                  Phase 6 fix3: when reading from existingOrgBilling,
+                  the value comes from there too. */}
               {!isPersonal &&
-                config.billingAddress.vatNumber &&
-                config.billingAddress.vatNumber.trim().length > 0 && (
-                  <ReviewRow
-                    label={t("billingVatNumber")}
-                    value={config.billingAddress.vatNumber}
-                    mono
-                  />
-                )}
+                (() => {
+                  const vat =
+                    hasOrgBilling && !isEditing && existingOrgBilling
+                      ? existingOrgBilling.vatNumber
+                      : config.billingAddress.vatNumber;
+                  return vat && vat.trim().length > 0 ? (
+                    <ReviewRow
+                      label={t("billingVatNumber")}
+                      value={vat}
+                      mono
+                    />
+                  ) : null;
+                })()}
               <ReviewRow
                 label={t("reviewContactEmail")}
                 value={userEmail || ""}

src/components/settings/billing-form.tsx

@@ -0,0 +1,263 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { Card } from "@/components/ui/card";
+import type { OrgBilling } from "@/types";
+
+interface Props {
+  initial: OrgBilling | null;
+  /**
+   * Personal-account (individual customer) flag from the session.
+   * Individuals get a "Full name" field instead of "Company name",
+   * and the VAT input is hidden entirely — they don't have one and
+   * showing the field would only confuse. The underlying column is
+   * still `company_name` in the DB and the invoice PDF; for an
+   * individual that field carries their full name, which is
+   * exactly what should print on the invoice.
+   */
+  isPersonal: boolean;
+}
+
+/**
+ * Customer billing settings form. Drives PUT /api/settings/billing
+ * which upserts org_billing for the caller's org.
+ *
+ * Validation is the same regex as the server-side zod schema for
+ * the country field (ISO 3166-1 alpha-2). Other fields are checked
+ * for required + max-length client-side; the server is the
+ * authority and re-validates everything.
+ *
+ * On success we router.refresh() the page so the server component
+ * re-fetches and any "create now" -> "edit" wording flips.
+ */
+export function BillingSettingsForm({ initial, isPersonal }: Props) {
+  const t = useTranslations("settingsBilling");
+  const router = useRouter();
+  const [form, setForm] = useState({
+    companyName: initial?.companyName ?? "",
+    contactName: initial?.contactName ?? "",
+    streetAddress: initial?.streetAddress ?? "",
+    postalCode: initial?.postalCode ?? "",
+    city: initial?.city ?? "",
+    country: initial?.country ?? "CH",
+    vatNumber: initial?.vatNumber ?? "",
+    billingEmail: initial?.billingEmail ?? "",
+    notes: initial?.notes ?? "",
+  });
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [savedFlash, setSavedFlash] = useState(false);
+
+  const set =
+    (field: keyof typeof form) =>
+    (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) =>
+      setForm((f) => ({ ...f, [field]: e.target.value }));
+
+  const submit = async () => {
+    setError(null);
+    setSavedFlash(false);
+    // Client-side gate on required fields — the server re-validates.
+    if (
+      !form.companyName.trim() ||
+      !form.streetAddress.trim() ||
+      !form.postalCode.trim() ||
+      !form.city.trim() ||
+      !form.country.trim() ||
+      !form.billingEmail.trim()
+    ) {
+      setError(t("missingRequired"));
+      return;
+    }
+    if (!/^[A-Za-z]{2}$/.test(form.country.trim())) {
+      setError(t("invalidCountry"));
+      return;
+    }
+    if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(form.billingEmail.trim())) {
+      setError(t("invalidEmail"));
+      return;
+    }
+    setBusy(true);
+    try {
+      const res = await fetch("/api/settings/billing", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          companyName: form.companyName.trim(),
+          // Personal accounts don't have a contact-name field
+          // (companyName IS their name); force null so stale state
+          // from a previously-org-flagged account can't carry over.
+          contactName: isPersonal ? null : form.contactName.trim() || null,
+          streetAddress: form.streetAddress.trim(),
+          postalCode: form.postalCode.trim(),
+          city: form.city.trim(),
+          country: form.country.trim().toUpperCase(),
+          // Personal accounts never have a VAT number — force null
+          // regardless of stale state, in case a value was stored
+          // before the account got flagged as personal.
+          vatNumber: isPersonal ? null : form.vatNumber.trim() || null,
+          billingEmail: form.billingEmail.trim(),
+          notes: form.notes.trim() || null,
+        }),
+      });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        throw new Error(data.error ?? `HTTP ${res.status}`);
+      }
+      setSavedFlash(true);
+      router.refresh();
+    } catch (e: any) {
+      setError(e?.message ?? String(e));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <Card>
+      <div className="space-y-4">
+        <Field
+          label={isPersonal ? t("fullNameLabel") : t("companyNameLabel")}
+          required
+        >
+          <input
+            type="text"
+            value={form.companyName}
+            onChange={set("companyName")}
+            maxLength={200}
+            className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border focus:border-accent focus:outline-none text-sm"
+          />
+        </Field>
+        {!isPersonal && (
+          <Field label={t("contactNameLabel")} hint={t("contactNameHint")}>
+            <input
+              type="text"
+              value={form.contactName}
+              onChange={set("contactName")}
+              maxLength={200}
+              className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border focus:border-accent focus:outline-none text-sm"
+            />
+          </Field>
+        )}
+        <Field label={t("streetAddressLabel")} required>
+          <input
+            type="text"
+            value={form.streetAddress}
+            onChange={set("streetAddress")}
+            maxLength={200}
+            className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border focus:border-accent focus:outline-none text-sm"
+          />
+        </Field>
+        <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+          <Field label={t("postalCodeLabel")} required>
+            <input
+              type="text"
+              value={form.postalCode}
+              onChange={set("postalCode")}
+              maxLength={20}
+              className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border focus:border-accent focus:outline-none text-sm"
+            />
+          </Field>
+          <Field label={t("cityLabel")} required>
+            <input
+              type="text"
+              value={form.city}
+              onChange={set("city")}
+              maxLength={100}
+              className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border focus:border-accent focus:outline-none text-sm"
+            />
+          </Field>
+          <Field
+            label={t("countryLabel")}
+            required
+            hint={t("countryHint")}
+          >
+            <input
+              type="text"
+              value={form.country}
+              onChange={(e) =>
+                setForm((f) => ({
+                  ...f,
+                  country: e.target.value.toUpperCase().slice(0, 2),
+                }))
+              }
+              maxLength={2}
+              className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border focus:border-accent focus:outline-none text-sm uppercase font-mono"
+            />
+          </Field>
+        </div>
+        {!isPersonal && (
+          <Field label={t("vatNumberLabel")} hint={t("vatNumberHint")}>
+            <input
+              type="text"
+              value={form.vatNumber}
+              onChange={set("vatNumber")}
+              maxLength={40}
+              placeholder="CHE-123.456.789 MWST"
+              className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border focus:border-accent focus:outline-none text-sm font-mono"
+            />
+          </Field>
+        )}
+        <Field label={t("billingEmailLabel")} required hint={t("billingEmailHint")}>
+          <input
+            type="email"
+            value={form.billingEmail}
+            onChange={set("billingEmail")}
+            maxLength={200}
+            className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border focus:border-accent focus:outline-none text-sm"
+          />
+        </Field>
+        <Field label={t("notesLabel")} hint={t("notesHint")}>
+          <textarea
+            value={form.notes}
+            onChange={set("notes")}
+            maxLength={2000}
+            rows={3}
+            className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border focus:border-accent focus:outline-none text-sm"
+          />
+        </Field>
+        {error && (
+          <p className="text-sm text-error">{error}</p>
+        )}
+        {savedFlash && (
+          <p className="text-sm text-success">{t("saved")}</p>
+        )}
+        <div className="flex justify-end">
+          <button
+            onClick={submit}
+            disabled={busy}
+            className="px-4 py-2 rounded-md bg-accent text-white text-sm font-medium hover:bg-accent-dim transition-colors disabled:opacity-50 cursor-pointer"
+          >
+            {busy ? t("saving") : initial ? t("saveChanges") : t("createBilling")}
+          </button>
+        </div>
+      </div>
+    </Card>
+  );
+}
+
+function Field({
+  label,
+  required,
+  hint,
+  children,
+}: {
+  label: string;
+  required?: boolean;
+  hint?: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div>
+      <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+        {label}
+        {required && <span className="text-error ml-1">*</span>}
+      </label>
+      {children}
+      {hint && (
+        <p className="text-xs text-text-muted mt-1 italic">{hint}</p>
+      )}
+    </div>
+  );
+}

src/components/settings/profile-form.tsx

@@ -0,0 +1,187 @@
+"use client";
+
+import { useState } from "react";
+import { useSession } from "next-auth/react";
+import { useTranslations } from "next-intl";
+import { Card } from "@/components/ui/card";
+
+interface Props {
+  initial: {
+    firstName: string;
+    lastName: string;
+    email: string;
+  };
+  /**
+   * Personal-account flag. Drives a small hint about how the ZITADEL
+   * name relates (or doesn't) to invoice identity — see the page
+   * server component for the long explanation.
+   */
+  isPersonal: boolean;
+  /**
+   * For company accounts: the display org name. Shown in a small
+   * read-only "Member of <org>" hint so the user understands which
+   * identity they're editing. Ignored for personals (orgName is an
+   * opaque "personal-XXXX" string in that case).
+   */
+  orgName: string;
+}
+
+/**
+ * Edits first/last name in ZITADEL via PUT /api/settings/profile.
+ * Email is shown read-only — changing email requires verification
+ * flow that ZITADEL's own self-service UI handles.
+ *
+ * On save, we trigger NextAuth's `update()` from useSession() with
+ * the new display name. That routes through our jwt callback
+ * (trigger='update' branch) which overlays token.name without a
+ * logout/login. After the cookie is updated we trigger a full page
+ * reload — every server-rendered surface (nav-shell, dashboard
+ * welcome, instance cards) re-reads the cookie on the next request
+ * and renders with the new name. router.refresh() alone wasn't
+ * enough: it re-runs only the current route's server components,
+ * leaving outer-tree segments stale until the user navigates.
+ */
+export function ProfileSettingsForm({ initial, isPersonal, orgName }: Props) {
+  const t = useTranslations("settingsProfile");
+  const { update } = useSession();
+  const [form, setForm] = useState({
+    firstName: initial.firstName,
+    lastName: initial.lastName,
+  });
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [savedFlash, setSavedFlash] = useState(false);
+
+  const submit = async () => {
+    setError(null);
+    setSavedFlash(false);
+    if (!form.firstName.trim() || !form.lastName.trim()) {
+      setError(t("missingRequired"));
+      return;
+    }
+    setBusy(true);
+    try {
+      const res = await fetch("/api/settings/profile", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          firstName: form.firstName.trim(),
+          lastName: form.lastName.trim(),
+        }),
+      });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        throw new Error(data.error ?? `HTTP ${res.status}`);
+      }
+      // Phase 6 fix5: push the new display name into the session
+      // token. The jwt callback handles trigger='update' and overlays
+      // token.name; the next session callback maps token.name back
+      // to session.user.name. No re-login needed.
+      await update({ name: data.displayName });
+      setSavedFlash(true);
+      // Force a full reload so EVERY server-rendered component picks
+      // up the new session cookie immediately — router.refresh() only
+      // re-runs the current route's server components, leaving the
+      // nav-shell (rendered higher in the tree) and other cached
+      // segments showing the old name until the user navigates.
+      // The 800ms delay lets the "Saved" flash render briefly before
+      // the page reloads, so the user gets visible feedback.
+      setTimeout(() => {
+        window.location.reload();
+      }, 800);
+    } catch (e: any) {
+      setError(e?.message ?? String(e));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <Card>
+      <div className="space-y-4">
+        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+          <Field label={t("firstNameLabel")} required>
+            <input
+              type="text"
+              value={form.firstName}
+              onChange={(e) =>
+                setForm((f) => ({ ...f, firstName: e.target.value }))
+              }
+              maxLength={100}
+              className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border focus:border-accent focus:outline-none text-sm"
+            />
+          </Field>
+          <Field label={t("lastNameLabel")} required>
+            <input
+              type="text"
+              value={form.lastName}
+              onChange={(e) =>
+                setForm((f) => ({ ...f, lastName: e.target.value }))
+              }
+              maxLength={100}
+              className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border focus:border-accent focus:outline-none text-sm"
+            />
+          </Field>
+        </div>
+        <Field label={t("emailLabel")} hint={t("emailReadOnlyHint")}>
+          <input
+            type="email"
+            value={initial.email}
+            readOnly
+            disabled
+            className="w-full px-3 py-2 rounded-md bg-surface-2 border border-border text-sm text-text-muted cursor-not-allowed"
+          />
+        </Field>
+        {/* Personal vs company hint. Personals get the
+            "this won't change your invoice name" warning since their
+            ZITADEL name and their invoice identity are intentionally
+            decoupled. Company accounts get a benign "member of"
+            context line so they know which org's identity they're
+            editing. */}
+        {isPersonal ? (
+          <p className="text-xs text-text-muted italic">
+            {t("personalAccountHint")}
+          </p>
+        ) : (
+          <p className="text-xs text-text-muted italic">
+            {t("companyAccountHint", { orgName })}
+          </p>
+        )}
+        {error && <p className="text-sm text-error">{error}</p>}
+        {savedFlash && <p className="text-sm text-success">{t("saved")}</p>}
+        <div className="flex justify-end">
+          <button
+            onClick={submit}
+            disabled={busy}
+            className="px-4 py-2 rounded-md bg-accent text-white text-sm font-medium hover:bg-accent-dim transition-colors disabled:opacity-50 cursor-pointer"
+          >
+            {busy ? t("saving") : t("saveChanges")}
+          </button>
+        </div>
+      </div>
+    </Card>
+  );
+}
+
+function Field({
+  label,
+  required,
+  hint,
+  children,
+}: {
+  label: string;
+  required?: boolean;
+  hint?: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div>
+      <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+        {label}
+        {required && <span className="text-error ml-1">*</span>}
+      </label>
+      {children}
+      {hint && <p className="text-xs text-text-muted mt-1 italic">{hint}</p>}
+    </div>
+  );
+}

src/lib/auth.ts

@@ -49,7 +49,31 @@ export const authConfig: NextAuthConfig = {
     },
   ],
   callbacks: {
-    async jwt({ token, account, profile }) {
+    async jwt({ token, account, profile, trigger, session }) {
+      // Phase 6 fix5: client-side `useSession().update({ name })` calls
+      // route through this branch. We trust the new value because the
+      // PUT /api/settings/profile route already wrote it to ZITADEL
+      // and re-fetched the canonical displayName before returning.
+      // The session callback reads token.name directly (see below) so
+      // the update propagates without depending on auth.js's implicit
+      // token→session.user mapping, which is flaky for the name claim
+      // in the v5 OIDC provider configuration.
+      //
+      // Defensive: only the `name` field is accepted from the update
+      // payload, even if the client passes additional keys. Other
+      // identity claims (orgId, roles, sub) come from ZITADEL at
+      // sign-in time and are not user-mutable from a settings page.
+      //
+      // Returns a NEW token object (spread) rather than mutating, so
+      // there is no ambiguity for auth.js about whether the token
+      // changed and needs re-encoding into the session cookie.
+      if (trigger === "update" && session) {
+        const update = session as { name?: unknown };
+        if (typeof update.name === "string") {
+          return { ...token, name: update.name };
+        }
+        return token;
+      }
       if (account && profile) {
         const claims = profile as unknown as ZitadelClaims;
         token.orgId = claims["urn:zitadel:iam:user:resourceowner:id"];
@@ -58,6 +82,19 @@ export const authConfig: NextAuthConfig = {
           claims["urn:zitadel:iam:org:project:roles"]
         );
         token.accessToken = account.access_token;
+        // Phase 6 fix5: explicitly pin the standard name/email claims
+        // onto the token from the OIDC profile. Previously these came
+        // through auth.js's implicit mapping, which works on first
+        // sign-in but isn't reliable after update() — once the update
+        // path overrides token.name, the read-back path needs token
+        // to be the authoritative source. Setting them explicitly
+        // here keeps sign-in and update on the same path.
+        if (typeof profile.name === "string") {
+          token.name = profile.name;
+        }
+        if (typeof profile.email === "string") {
+          token.email = profile.email;
+        }
         // Pin token.sub to the OIDC subject. Auth.js v5 otherwise puts a
         // freshly generated UUID in token.sub on initial sign-in,
         // ignoring what profile() returns for `id`. That UUID then
@@ -80,10 +117,19 @@ export const authConfig: NextAuthConfig = {
     async session({ session, token }) {
       const roles = (token.roles as Role[]) ?? [];
       const orgName = (token.orgName as string) ?? "";
+      // Phase 6 fix5: read name and email directly from the token.
+      // Previously this code relied on `session.user?.name`, expecting
+      // auth.js to map token.name → session.user.name automatically.
+      // That mapping is brittle: it works on first sign-in (because
+      // OIDC profile() populates session.user) but not after update()
+      // overrides token.name. Reading from token is the canonical
+      // path regardless of how the token was last written.
+      const tokenName = (token.name as string | undefined) ?? "";
+      const tokenEmail = (token.email as string | undefined) ?? "";
       const sessionUser: SessionUser = {
         id: token.sub!,
-        name: session.user?.name ?? "",
-        email: session.user?.email ?? "",
+        name: tokenName || session.user?.name || "",
+        email: tokenEmail || session.user?.email || "",
         orgId: token.orgId as string,
         orgName,
         roles,
@@ -96,6 +142,14 @@ export const authConfig: NextAuthConfig = {
         isPersonal: isPersonalOrgName(orgName),
       };
       (session as any).platformUser = sessionUser;
+      // Also overwrite session.user so any client-side code that uses
+      // the standard NextAuth shape (session.user.name) sees the new
+      // value. Pre-fix5 code paths read from session.user.name; this
+      // keeps them working without per-component changes.
+      if (session.user) {
+        session.user.name = sessionUser.name;
+        session.user.email = sessionUser.email;
+      }
       return session;
     },
   },

src/lib/billing-i18n.ts

@@ -153,5 +153,21 @@ export function formatLineDescription(
       }[L];
       return reason ? `${base}: ${reason}` : base;
     }
+
+    // Phase 8: custom invoice lines. The description is what the
+    // admin typed in the editor — return it verbatim (no template,
+    // no locale-specific formatting). billing.ts persists the
+    // already-trimmed admin input into invoice_lines.description.
+    case "custom_line": {
+      const dRaw = (m as Record<string, unknown>)["description"];
+      if (typeof dRaw === "string" && dRaw.trim().length > 0) return dRaw;
+      // Fallback: the description column on the row itself. The
+      // PDF renderer hands us the line so it can read it directly
+      // — see how billing-pdf invokes formatLineDescription.
+      const onRow = (line as unknown as { description?: string }).description;
+      return onRow && onRow.trim().length > 0
+        ? onRow
+        : { de: "Leistung", en: "Service", fr: "Service", it: "Servizio" }[L];
+    }
   }
 }

src/lib/billing-pdf.tsx

@@ -31,44 +31,18 @@ import {
   Text,
   View,
   StyleSheet,
-  Svg,
-  Polygon,
-  Polyline,
   renderToBuffer,
 } from "@react-pdf/renderer";
 import type { Invoice, InvoiceLine, InvoiceLineKind } from "@/types";
+import { BRAND, Logo } from "./pdf-brand";
 
 // ---------------------------------------------------------------------------
-// Brand constants — edit here to tweak look without touching layout
+// Brand: imported from lib/pdf-brand. Edit there to change issuer
+// info, colours, or the logo. Both billing-pdf.tsx and credit-note-pdf.tsx
+// share the same source of truth so a brand change applies to every
+// PDF the portal produces.
 // ---------------------------------------------------------------------------
 
-const BRAND = {
-  name: "PieCed IT",
-  // Primary emerald — matches the logo SVG fill (#10B981).
-  primary: "#10B981",
-  // Slightly darker emerald for headings.
-  primaryDark: "#0a8060",
-  textColor: "#1a1a1a",
-  mutedColor: "#666",
-  borderColor: "#d4d4d4",
-  // Issuer block — change these to your real legal info.
-  issuer: {
-    legalName: "PieCed IT",
-    addressLine1: "Cedric Mosimann",
-    addressLine2: "[Strasse Nr.]",
-    postalCity: "[PLZ] Basel",
-    country: "Switzerland",
-    email: "billing@pieced.ch",
-    web: "pieced.ch",
-    // Show "MWST-Nr. ..." on PDF when set.
-    vatNumber: null as string | null,
-    // Bank instructions — Phase 7 replaces with QR-bill.
-    bankName: "[Bank name]",
-    bankIban: "[CHxx xxxx xxxx xxxx xxxx x]",
-    bankBic: "[BIC]",
-  },
-};
-
 // ---------------------------------------------------------------------------
 // Localized strings
 // ---------------------------------------------------------------------------
@@ -80,6 +54,11 @@ interface PdfStrings {
   dueDate: string;
   period: string;
   billTo: string;
+  // Phase 6 fix: prefix shown before the optional contact-person
+  // name on the bill-to block. "z.Hd." (DE) / "Attn:" (EN) /
+  // "À l'attention de" (FR) / "c.a." (IT). Empty/unused when the
+  // invoice has no contactName on its snapshot.
+  attentionPrefix: string;
   description: string;
   quantity: string;
   unitPrice: string;
@@ -107,6 +86,7 @@ const MESSAGES: Record<string, PdfStrings> = {
     dueDate: "Zahlbar bis",
     period: "Abrechnungsperiode",
     billTo: "Rechnungsempfänger",
+    attentionPrefix: "z.Hd.",
     description: "Beschreibung",
     quantity: "Menge",
     unitPrice: "Einzelpreis",
@@ -127,6 +107,7 @@ const MESSAGES: Record<string, PdfStrings> = {
       skill_usage: "Skill-Nutzung",
       skill_setup: "Einrichtungsgebühr Skill",
       adjustment: "Anpassung",
+      custom_line: "Leistungen",
     },
     reverseCharge:
       "Steuerschuldnerschaft des Leistungsempfängers (Reverse Charge).",
@@ -139,6 +120,7 @@ const MESSAGES: Record<string, PdfStrings> = {
     dueDate: "Due date",
     period: "Billing period",
     billTo: "Bill to",
+    attentionPrefix: "Attn:",
     description: "Description",
     quantity: "Qty",
     unitPrice: "Unit price",
@@ -159,6 +141,7 @@ const MESSAGES: Record<string, PdfStrings> = {
       skill_usage: "Skill usage",
       skill_setup: "Skill setup fee",
       adjustment: "Adjustment",
+      custom_line: "Services",
     },
     reverseCharge:
       "Reverse charge — VAT to be accounted for by the recipient.",
@@ -171,6 +154,7 @@ const MESSAGES: Record<string, PdfStrings> = {
     dueDate: "Échéance",
     period: "Période de facturation",
     billTo: "Destinataire",
+    attentionPrefix: "À l'attention de",
     description: "Description",
     quantity: "Qté",
     unitPrice: "Prix unitaire",
@@ -191,6 +175,7 @@ const MESSAGES: Record<string, PdfStrings> = {
       skill_usage: "Utilisation Skill",
       skill_setup: "Frais de configuration skill",
       adjustment: "Ajustement",
+      custom_line: "Services",
     },
     reverseCharge:
       "Autoliquidation — TVA à acquitter par le destinataire.",
@@ -203,6 +188,7 @@ const MESSAGES: Record<string, PdfStrings> = {
     dueDate: "Scadenza",
     period: "Periodo di fatturazione",
     billTo: "Destinatario",
+    attentionPrefix: "c.a.",
     description: "Descrizione",
     quantity: "Qtà",
     unitPrice: "Prezzo unitario",
@@ -223,6 +209,7 @@ const MESSAGES: Record<string, PdfStrings> = {
       skill_usage: "Utilizzo Skill",
       skill_setup: "Spese di attivazione skill",
       adjustment: "Rettifica",
+      custom_line: "Servizi",
     },
     reverseCharge:
       "Inversione contabile — IVA a carico del destinatario.",
@@ -349,62 +336,6 @@ const styles = StyleSheet.create({
 });
 
 // ---------------------------------------------------------------------------
-// Logo — inlined SVG primitives
-// ---------------------------------------------------------------------------
-
-/**
- * PieCed honeycomb logo. Re-renders the same 6-hex glyph as the
- * portal's `public/pieced-logo.svg` using React-PDF's SVG support.
- * Width/height are independent of the original viewBox so we can
- * scale it without losing stroke quality.
- */
-const Logo = ({ size = 60 }: { size?: number }) => (
-  <Svg width={size} height={size * (106 / 70)} viewBox="0 0 70 106">
-    {/* H1 solid */}
-    <Polygon
-      points="38.5,22.69 31.5,10.566 17.5,10.566 10.5,22.69 17.5,34.814 31.5,34.814"
-      fill="#10B981"
-      stroke="#10B981"
-      strokeWidth={1.6}
-    />
-    {/* H2 outline */}
-    <Polygon
-      points="59.5,34.814 52.5,22.69 38.5,22.69 31.5,34.814 38.5,46.938 52.5,46.938"
-      fill="none"
-      stroke="#10B981"
-      strokeWidth={1.8}
-    />
-    {/* H3 outline */}
-    <Polygon
-      points="38.5,46.938 31.5,34.814 17.5,34.814 10.5,46.938 17.5,59.062 31.5,59.062"
-      fill="none"
-      stroke="#10B981"
-      strokeWidth={1.8}
-    />
-    {/* H4 solid */}
-    <Polygon
-      points="59.5,59.062 52.5,46.938 38.5,46.938 31.5,59.062 38.5,71.186 52.5,71.186"
-      fill="#10B981"
-      stroke="#10B981"
-      strokeWidth={1.6}
-    />
-    {/* H5 partial */}
-    <Polyline
-      points="31.5,83.31 38.5,71.186 31.5,59.062 17.5,59.062 10.5,71.186"
-      fill="none"
-      stroke="#10B981"
-      strokeWidth={1.8}
-    />
-    {/* H6 partial */}
-    <Polyline
-      points="59.5,83.31 52.5,71.186 38.5,71.186 31.5,83.31 38.5,95.434"
-      fill="none"
-      stroke="#10B981"
-      strokeWidth={1.8}
-    />
-  </Svg>
-);
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -508,11 +439,18 @@ const InvoicePdf: React.FC<InvoicePdfProps> = ({ invoice, lines }) => {
             </Text>
           </View>
           <View style={styles.metaCol}>
-            <Text style={styles.metaLabel}>{s.period}</Text>
-            <Text style={styles.metaValue}>
-              {fmtDate(invoice.periodStart, invoice.locale)} —{" "}
-              {fmtDate(invoice.periodEnd, invoice.locale)}
-            </Text>
+            {/* Phase 8: skip the billing-period block on custom
+                invoices (which aren't tied to a period). Due date
+                still renders. */}
+            {invoice.periodStart && invoice.periodEnd && (
+              <>
+                <Text style={styles.metaLabel}>{s.period}</Text>
+                <Text style={styles.metaValue}>
+                  {fmtDate(invoice.periodStart, invoice.locale)} —{" "}
+                  {fmtDate(invoice.periodEnd, invoice.locale)}
+                </Text>
+              </>
+            )}
             <Text style={styles.metaLabel}>{s.dueDate}</Text>
             <Text style={styles.metaValue}>
               {fmtDate(invoice.dueAt, invoice.locale)}
@@ -524,6 +462,15 @@ const InvoicePdf: React.FC<InvoicePdfProps> = ({ invoice, lines }) => {
         <View style={styles.billToBlock}>
           <Text style={styles.billToLabel}>{s.billTo}</Text>
           <Text style={styles.billToName}>{snap.companyName}</Text>
+          {/* Phase 6 fix: optional "z.Hd." / "Attn:" line for routing
+              the printed invoice internally at the customer. Prints
+              between the company name and street address, in the
+              invoice's locale (frozen at issue time). */}
+          {snap.contactName && (
+            <Text>
+              {s.attentionPrefix} {snap.contactName}
+            </Text>
+          )}
           <Text>{snap.streetAddress}</Text>
           <Text>
             {snap.postalCode} {snap.city}

src/lib/billing.ts

@@ -30,9 +30,12 @@
  */
 
 import type {
+  CreditNote,
+  CustomInvoiceDraftPayload,
   Invoice,
   InvoiceBillingSnapshot,
   InvoiceDraft,
+  InvoiceDraftRecord,
   InvoiceLine,
   InvoiceLineKind,
   InvoicePaymentMethod,
@@ -44,8 +47,12 @@ import type {
   TenantSuspensionEvent,
 } from "@/types";
 import {
+  attachCreditNotePdf,
+  createCreditNote,
   createInvoice,
+  deleteInvoiceDraft,
   getInvoiceById,
+  getInvoiceDraftById,
   getOrgBilling,
   getOrgBillingConfig,
   getPlatformPricing,
@@ -53,6 +60,8 @@ import {
   listSkillEventsForTenant,
   listSkillPricing,
   listSuspensionEventsForTenant,
+  markInvoiceVoided,
+  recordInvoiceRefund,
   tenantHasSetupFeeBilled,
   tenantSkillHasBeenBilled,
   updateInvoicePdf,
@@ -61,7 +70,9 @@ import { listTenants } from "./k8s";
 import { getTeamSpendLogsV2 } from "./litellm";
 import { getUsage as getThreemaUsage } from "./threema-relay";
 import { renderInvoicePdf } from "./billing-pdf";
-import { sendInvoiceIssuedEmail } from "./email";
+import { renderCreditNotePdf } from "./credit-note-pdf";
+import { sendCreditNoteEmail, sendInvoiceIssuedEmail } from "./email";
+import { createInvoiceRefund } from "./stripe";
 import { formatLineDescription } from "./billing-i18n";
 
 // ---------------------------------------------------------------------------
@@ -240,6 +251,9 @@ const EU_COUNTRIES = new Set([
 
 /**
  * Determine VAT rate from billing address and the platform default.
+ * Exported for reuse by the Phase 8 custom-invoice flow so both
+ * pipelines (cron and custom) compute VAT identically.
+ *
  * See README for the legal interpretation; this implements the
  * defaults you confirmed:
  *
@@ -248,7 +262,7 @@ const EU_COUNTRIES = new Set([
  *   - EU without VAT:  CH MWST (B2C consumer, we charge our rate)
  *   - other:           0% (export of services)
  */
-function vatRateForAddress(
+export function vatRateForAddress(
   snapshot: InvoiceBillingSnapshot,
   platformPricing: PlatformPricing
 ): { rate: number; note: string | null } {
@@ -645,6 +659,7 @@ export async function computeInvoiceDraft(opts: {
   }
   const snapshot: InvoiceBillingSnapshot = {
     companyName: orgBilling.companyName,
+    contactName: orgBilling.contactName ?? null,
     streetAddress: orgBilling.streetAddress,
     postalCode: orgBilling.postalCode,
     city: orgBilling.city,
@@ -835,3 +850,692 @@ export async function generateInvoice(opts: {
     );
   }
 }
+
+// ---------------------------------------------------------------------------
+// Phase 7 — void and refund orchestration
+// ---------------------------------------------------------------------------
+
+export class VoidNotAllowedError extends Error {
+  constructor(message: string, public readonly currentStatus: string) {
+    super(message);
+    this.name = "VoidNotAllowedError";
+  }
+}
+
+export class RefundNotAllowedError extends Error {
+  constructor(message: string, public readonly currentStatus: string) {
+    super(message);
+    this.name = "RefundNotAllowedError";
+  }
+}
+
+/**
+ * Sanitize a locale string to the supported four. Used when picking
+ * which translation block to render emails/PDFs with. We never
+ * fall back to admin's locale here — the credit note inherits the
+ * invoice's locale so both documents read consistently to the
+ * customer.
+ */
+function pickSupportedLocale(
+  locale: string | null | undefined
+): "de" | "en" | "fr" | "it" {
+  const supported = ["de", "en", "fr", "it"] as const;
+  return (supported as readonly string[]).includes(locale ?? "")
+    ? (locale as "de" | "en" | "fr" | "it")
+    : "de";
+}
+
+/**
+ * Round a CHF amount to 2 decimal places. Used when proportionally
+ * splitting VAT between subtotal and refund amount — avoids
+ * accumulating fractional rappen across operations.
+ */
+function roundChf(amount: number): number {
+  return Math.round(amount * 100) / 100;
+}
+
+/**
+ * Void an unpaid invoice. State transition: open/overdue → void.
+ *
+ * Side effects, in order:
+ *   1. Mark the invoice voided (status, void_reason, voided_at, voided_by)
+ *   2. Insert credit_notes row (kind='void', amount=full invoice total)
+ *   3. Render the credit-note PDF and attach it to the row
+ *   4. Best-effort email to the billing contact
+ *
+ * Not allowed:
+ *   - status='paid' (use refundInvoice instead — voiding paid
+ *     invoices would create a record mismatch with the payment
+ *     processor)
+ *   - status='void' (already voided)
+ *   - status='draft' (drafts aren't issued; nothing to void)
+ *   - status='partially_refunded' / 'fully_refunded' (use refund
+ *     for the remaining amount instead)
+ *
+ * Throws VoidNotAllowedError if the invoice is in a non-voidable
+ * state. Caller surfaces this as 409 Conflict to the admin.
+ */
+export async function voidInvoice(params: {
+  invoiceId: string;
+  reason: string;
+  voidedBy: string;
+}): Promise<CreditNote> {
+  const invoice = await getInvoiceById(params.invoiceId);
+  if (!invoice) {
+    throw new Error(`Invoice not found: ${params.invoiceId}`);
+  }
+  // Only unpaid invoices can be voided. The state machine puts
+  // paid invoices on the refund path; voiding them would skip the
+  // payment reversal and leave the customer's money in our account
+  // with no obligation showing in the portal.
+  if (!["open", "overdue"].includes(invoice.status)) {
+    throw new VoidNotAllowedError(
+      `Cannot void invoice in status '${invoice.status}'. Voids are allowed only for open or overdue invoices; paid invoices must be refunded.`,
+      invoice.status
+    );
+  }
+  const locale = pickSupportedLocale(invoice.locale);
+
+  // The credit note matches the invoice 1:1 in amount and VAT.
+  // We carry the same VAT breakdown so the PDF can render
+  // "subtotal + VAT" the same way the original invoice did.
+  const creditNote = await createCreditNote({
+    invoiceId: invoice.id,
+    zitadelOrgId: invoice.zitadelOrgId,
+    kind: "void",
+    amountChf: invoice.totalChf,
+    vatAmountChf: invoice.vatAmountChf,
+    reason: params.reason || null,
+    issuedBy: params.voidedBy,
+    locale,
+    billingSnapshot: invoice.billingSnapshot,
+  });
+
+  // Mark invoice voided AFTER the credit note row exists, so the
+  // status change has a credit note to point at. If anything below
+  // here fails (PDF render, email), the invoice is still correctly
+  // voided and the credit note row exists — just without a PDF
+  // until manually re-rendered.
+  await markInvoiceVoided({
+    invoiceId: invoice.id,
+    reason: params.reason,
+    voidedBy: params.voidedBy,
+  });
+
+  // Render PDF + attach. PDF failure here doesn't undo the void —
+  // the customer can be told their invoice is voided and the PDF
+  // can be re-issued later. We surface the error in the response
+  // so admin knows to retry, but the void itself stands.
+  try {
+    const pdfBuffer = await renderCreditNotePdf(creditNote, invoice);
+    const filename = `${creditNote.creditNoteNumber}.pdf`;
+    await attachCreditNotePdf(creditNote.id, pdfBuffer, filename);
+  } catch (e) {
+    console.error(
+      `Credit note ${creditNote.creditNoteNumber} created but PDF render failed; re-render manually.`,
+      e
+    );
+  }
+
+  // Best-effort email. Same fail-soft pattern as invoice issuance.
+  try {
+    const snap = invoice.billingSnapshot;
+    if (snap.billingEmail) {
+      await sendCreditNoteEmail({
+        to: snap.billingEmail,
+        contactName: snap.contactName || snap.companyName,
+        companyName: snap.companyName,
+        creditNoteNumber: creditNote.creditNoteNumber,
+        invoiceNumber: invoice.invoiceNumber,
+        amountChf: creditNote.amountChf,
+        currency: "CHF",
+        kind: "void",
+        reason: params.reason || null,
+        locale,
+      });
+    }
+  } catch (e) {
+    console.error(
+      `Credit note ${creditNote.creditNoteNumber} issued; email send failed.`,
+      e
+    );
+  }
+
+  return creditNote;
+}
+
+/**
+ * Refund a paid invoice (in part or in full). State transition:
+ *   paid → partially_refunded (if amount < remaining)
+ *   paid → fully_refunded     (if amount >= remaining)
+ *   partially_refunded → fully_refunded (if cumulative >= total)
+ *
+ * Side effects, in order:
+ *   1. If the invoice was Stripe-paid (payment_method='card' with a
+ *      stripe_payment_intent_id) AND no `existingStripeRefund` was
+ *      passed, call Stripe to issue the refund. Stripe is the source
+ *      of truth for actual money movement; we mirror its outcome
+ *      locally.
+ *   2. Insert credit_notes row (kind='refund', amount=refund amount,
+ *      VAT proportional)
+ *   3. Insert invoice_refunds row, linking to the credit note and to
+ *      the Stripe refund (if any). recordInvoiceRefund updates the
+ *      invoice's status atomically based on the new running total.
+ *   4. Render PDF + attach
+ *   5. Best-effort email
+ *
+ * `existingStripeRefund` is for the webhook path: when Stripe fires
+ * `charge.refunded` for a refund that was initiated directly in the
+ * Stripe Dashboard (not via this portal), the webhook needs to
+ * mirror the refund into the DB and issue a credit note WITHOUT
+ * calling Stripe again. Pass the refund id and status to skip the
+ * Stripe call.
+ *
+ * Not allowed:
+ *   - status not in {paid, partially_refunded} — full refunds are
+ *     only meaningful against actual payment
+ *   - amount <= 0 or > remaining refundable
+ *
+ * For invoice-paid (non-Stripe) customers the Stripe step is
+ * skipped; refund settlement happens out-of-band (bank transfer)
+ * and admin records the action in the portal.
+ */
+export async function refundInvoice(params: {
+  invoiceId: string;
+  amountChf: number;
+  reason: string;
+  refundedBy: string;
+  /**
+   * Webhook path: a Stripe refund that has already been created
+   * (in the Stripe Dashboard or via a prior API call) and now needs
+   * to be mirrored into the portal. When set, the Stripe API call
+   * is skipped and the provided id/status are recorded as-is.
+   */
+  existingStripeRefund?: {
+    id: string;
+    status: "pending" | "succeeded" | "failed" | "canceled";
+  };
+}): Promise<CreditNote> {
+  const invoice = await getInvoiceById(params.invoiceId);
+  if (!invoice) {
+    throw new Error(`Invoice not found: ${params.invoiceId}`);
+  }
+  if (!["paid", "partially_refunded"].includes(invoice.status)) {
+    throw new RefundNotAllowedError(
+      `Cannot refund invoice in status '${invoice.status}'. Refunds are allowed only for paid invoices.`,
+      invoice.status
+    );
+  }
+  if (params.amountChf <= 0) {
+    throw new RefundNotAllowedError(
+      "Refund amount must be greater than zero.",
+      invoice.status
+    );
+  }
+  const remaining = roundChf(invoice.totalChf - invoice.refundedTotalChf);
+  if (params.amountChf - remaining > 0.005) {
+    // Allow a 0.005 tolerance to account for floating-point dust;
+    // anything genuinely larger is a real over-refund attempt.
+    throw new RefundNotAllowedError(
+      `Refund amount CHF ${params.amountChf.toFixed(2)} exceeds remaining refundable CHF ${remaining.toFixed(2)}.`,
+      invoice.status
+    );
+  }
+  const locale = pickSupportedLocale(invoice.locale);
+
+  // Proportional VAT split: refunded VAT / total VAT  =  refunded
+  // amount / total amount. Keep the proportion explicit so the
+  // credit note's "subtotal + VAT" lines reconcile to the same
+  // VAT rate as the original invoice.
+  const vatPortion =
+    invoice.totalChf > 0
+      ? roundChf((params.amountChf * invoice.vatAmountChf) / invoice.totalChf)
+      : 0;
+
+  // Step 1: Stripe (only for card-paid invoices, and only when the
+  // caller hasn't already created the refund). We do this BEFORE
+  // any local DB writes for refund tracking — Stripe is the source
+  // of truth for money movement, and if the Stripe call fails we
+  // must NOT have recorded the refund locally (the customer would
+  // see a credit note for money they never received).
+  //
+  // The charge.refunded webhook will also fire later, but we record
+  // the refund here too so the admin gets immediate confirmation
+  // and the credit note can be issued without waiting for the
+  // webhook round-trip. The webhook is idempotent (dedups by
+  // stripe_refund_id) so it's safe to do both.
+  let stripeRefundId: string | null = null;
+  let stripeStatus: "pending" | "succeeded" | "failed" | "canceled" =
+    "succeeded";
+  const isStripePaid =
+    invoice.paymentMethod === "card" && !!invoice.stripePaymentIntentId;
+  if (params.existingStripeRefund) {
+    // Webhook path: don't call Stripe again; trust the provided id.
+    stripeRefundId = params.existingStripeRefund.id;
+    stripeStatus = params.existingStripeRefund.status;
+  } else if (isStripePaid) {
+    try {
+      const refund = await createInvoiceRefund({
+        paymentIntentId: invoice.stripePaymentIntentId!,
+        amountChf: params.amountChf,
+        reason: "requested_by_customer",
+        metadata: {
+          invoice_number: invoice.invoiceNumber,
+          refunded_by: params.refundedBy,
+        },
+      });
+      stripeRefundId = refund.id;
+      // Map Stripe statuses to our enum. Anything other than
+      // 'succeeded' or 'pending' is treated as a failure — we
+      // don't record the credit note in that case (see below).
+      if (refund.status === "succeeded") stripeStatus = "succeeded";
+      else if (refund.status === "pending") stripeStatus = "pending";
+      else if (refund.status === "canceled") stripeStatus = "canceled";
+      else stripeStatus = "failed";
+    } catch (e) {
+      throw new Error(
+        `Stripe refund failed: ${e instanceof Error ? e.message : String(e)}`
+      );
+    }
+    if (stripeStatus === "failed" || stripeStatus === "canceled") {
+      throw new Error(
+        `Stripe refund returned non-success status: ${stripeStatus}`
+      );
+    }
+  }
+
+  // Step 2: insert credit note (PDF still null at this point).
+  const creditNote = await createCreditNote({
+    invoiceId: invoice.id,
+    zitadelOrgId: invoice.zitadelOrgId,
+    kind: "refund",
+    amountChf: params.amountChf,
+    vatAmountChf: vatPortion,
+    reason: params.reason || null,
+    issuedBy: params.refundedBy,
+    locale,
+    billingSnapshot: invoice.billingSnapshot,
+  });
+
+  // Step 3: record the refund event and bump invoice status.
+  // recordInvoiceRefund handles status transitions and idempotency.
+  await recordInvoiceRefund({
+    invoiceId: invoice.id,
+    stripeRefundId,
+    amountChf: params.amountChf,
+    reason: params.reason || null,
+    refundedBy: params.refundedBy,
+    creditNoteId: creditNote.id,
+    status: stripeStatus,
+  });
+
+  // Step 4: render + attach PDF. As with voidInvoice, a PDF failure
+  // here doesn't undo the refund — the refund happened (in Stripe
+  // and the DB), only the document is missing. Admin can re-render.
+  try {
+    const pdfBuffer = await renderCreditNotePdf(creditNote, invoice);
+    const filename = `${creditNote.creditNoteNumber}.pdf`;
+    await attachCreditNotePdf(creditNote.id, pdfBuffer, filename);
+  } catch (e) {
+    console.error(
+      `Credit note ${creditNote.creditNoteNumber} created but PDF render failed; re-render manually.`,
+      e
+    );
+  }
+
+  // Step 5: best-effort email.
+  try {
+    const snap = invoice.billingSnapshot;
+    if (snap.billingEmail) {
+      await sendCreditNoteEmail({
+        to: snap.billingEmail,
+        contactName: snap.contactName || snap.companyName,
+        companyName: snap.companyName,
+        creditNoteNumber: creditNote.creditNoteNumber,
+        invoiceNumber: invoice.invoiceNumber,
+        amountChf: creditNote.amountChf,
+        currency: "CHF",
+        kind: "refund",
+        reason: params.reason || null,
+        locale,
+      });
+    }
+  } catch (e) {
+    console.error(
+      `Credit note ${creditNote.creditNoteNumber} issued; email send failed.`,
+      e
+    );
+  }
+
+  return creditNote;
+}
+
+// ---------------------------------------------------------------------------
+// Phase 8 — custom invoices (admin-entered, ad-hoc)
+// ---------------------------------------------------------------------------
+
+export class CustomInvoiceValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CustomInvoiceValidationError";
+  }
+}
+
+/**
+ * Compute the totals for a custom-invoice draft payload, applying
+ * the same VAT logic the auto cron uses (vatRateForAddress against
+ * the org's billing snapshot).
+ *
+ * Returns the InvoiceDraft the createInvoice helper expects.
+ * Throws CustomInvoiceValidationError on:
+ *   - no lines
+ *   - any line with empty description or zero quantity
+ *   - invalid date (issue or due)
+ *   - issue date in past beyond 1 year (probably a typo)
+ *   - due before issue
+ *
+ * Negative line amounts are intentionally allowed — they're the
+ * Rabatt / discount mechanism (one row with a negative unitPriceChf).
+ * The algebraic sum becomes the subtotal.
+ */
+export async function computeCustomInvoiceTotals(params: {
+  zitadelOrgId: string;
+  payload: CustomInvoiceDraftPayload;
+}): Promise<InvoiceDraft> {
+  const { zitadelOrgId, payload } = params;
+
+  // Validation
+  if (!payload.lines || payload.lines.length === 0) {
+    throw new CustomInvoiceValidationError(
+      "Custom invoice must have at least one line."
+    );
+  }
+  for (let i = 0; i < payload.lines.length; i++) {
+    const ln = payload.lines[i];
+    if (!ln.description || !ln.description.trim()) {
+      throw new CustomInvoiceValidationError(
+        `Line ${i + 1}: description is required.`
+      );
+    }
+    if (
+      typeof ln.quantity !== "number" ||
+      !isFinite(ln.quantity) ||
+      ln.quantity === 0
+    ) {
+      throw new CustomInvoiceValidationError(
+        `Line ${i + 1}: quantity must be a non-zero number.`
+      );
+    }
+    if (typeof ln.unitPriceChf !== "number" || !isFinite(ln.unitPriceChf)) {
+      throw new CustomInvoiceValidationError(
+        `Line ${i + 1}: unit price must be a number (use negative for discounts).`
+      );
+    }
+  }
+  const issueDate = payload.issueDate;
+  const dueDate = payload.dueDate;
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(issueDate)) {
+    throw new CustomInvoiceValidationError(
+      "Issue date must be a valid YYYY-MM-DD."
+    );
+  }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(dueDate)) {
+    throw new CustomInvoiceValidationError(
+      "Due date must be a valid YYYY-MM-DD."
+    );
+  }
+  if (dueDate < issueDate) {
+    throw new CustomInvoiceValidationError(
+      "Due date cannot be before issue date."
+    );
+  }
+
+  // Billing snapshot — required for any invoice to render.
+  const orgBilling = await getOrgBilling(zitadelOrgId);
+  if (!orgBilling) {
+    throw new CustomInvoiceValidationError(
+      "Org has no billing configuration. Ask the customer to complete onboarding first, or set the billing info from the admin panel."
+    );
+  }
+  // Build the same snapshot shape the auto-cron freezes. Mirroring
+  // the auto flow keeps the PDF renderer happy with one code path.
+  const snapshot: InvoiceBillingSnapshot = {
+    companyName: orgBilling.companyName,
+    contactName: orgBilling.contactName ?? null,
+    streetAddress: orgBilling.streetAddress,
+    city: orgBilling.city,
+    postalCode: orgBilling.postalCode,
+    country: orgBilling.country,
+    vatNumber: orgBilling.vatNumber ?? null,
+    billingEmail: orgBilling.billingEmail,
+    notes: orgBilling.notes ?? null,
+  };
+
+  // VAT — same logic as auto.
+  const platformPricing = await getPlatformPricing();
+  const vat = vatRateForAddress(snapshot, platformPricing);
+
+  // Build invoice lines. quantity * unitPrice rounded to 2 decimals
+  // (rappen precision). We carry the per-line amount on the row so
+  // the PDF doesn't need to recompute and any rounding remains
+  // identical between rendering passes.
+  //
+  // tenantName=null because custom invoices aren't bound to a
+  // specific tenant. unitLabel=null because admin-entered lines are
+  // free-form (the auto-cron lines use "day" / "request" /
+  // "message" — for custom lines the quantity is just a number).
+  // metadata.description preserves the admin's input so
+  // formatLineDescription can read it via the metadata channel
+  // (the row's description column also has it, redundantly, for
+  // safety). displayOrder reflects the order the admin added the
+  // rows so the PDF renders them top-to-bottom unchanged.
+  const lines: Omit<InvoiceLine, "id" | "invoiceId">[] = payload.lines.map(
+    (ln, idx) => {
+      const amount = Math.round(ln.quantity * ln.unitPriceChf * 100) / 100;
+      return {
+        tenantName: null,
+        kind: "custom_line" as InvoiceLineKind,
+        description: ln.description.trim(),
+        quantity: ln.quantity,
+        unitLabel: null,
+        unitPriceChf: ln.unitPriceChf,
+        amountChf: amount,
+        metadata: { description: ln.description.trim() },
+        displayOrder: idx,
+      };
+    }
+  );
+
+  // Subtotal is the algebraic sum (negative lines reduce it).
+  const subtotalChf = Math.round(
+    lines.reduce((s, l) => s + l.amountChf, 0) * 100
+  ) / 100;
+  // VAT applies to the subtotal AFTER discounts (which is the
+  // legal default in CH — discounts reduce the taxable base).
+  const vatAmountChf = Math.round(subtotalChf * (vat.rate / 100) * 100) / 100;
+  const totalChf = Math.round((subtotalChf + vatAmountChf) * 100) / 100;
+
+  return {
+    zitadelOrgId,
+    source: "custom",
+    periodStart: null,
+    periodEnd: null,
+    issuedAt: `${issueDate}T00:00:00Z`,
+    dueAt: dueDate,
+    locale: payload.locale,
+    paymentMethod: payload.paymentMethod,
+    billingSnapshot: snapshot,
+    lines,
+    subtotalChf,
+    vatRate: vat.rate,
+    vatAmountChf,
+    totalChf,
+    warnings: [],
+  };
+}
+
+/**
+ * Issue a custom invoice from a draft. Three-step flow:
+ *
+ *   1. Compute totals + validate the payload (computeCustomInvoiceTotals)
+ *   2. Persist via createInvoice (allocates the number, inserts the
+ *      row + lines, source='custom', issued_at honours the override)
+ *   3. Render PDF, send email — best-effort each. PDF render failure
+ *      leaves the row in place with no PDF; admin can re-render. Email
+ *      failure is logged.
+ *
+ * After successful persistence, the draft row is deleted (its job
+ * is done). If persistence fails, the draft stays so the admin can
+ * fix the issue and try again.
+ */
+export async function issueCustomInvoiceDraft(params: {
+  draftId: string;
+  issuedBy: string;
+}): Promise<Invoice> {
+  const draft = await getInvoiceDraftById(params.draftId);
+  if (!draft) {
+    throw new CustomInvoiceValidationError(
+      `Draft not found: ${params.draftId}`
+    );
+  }
+  const invoiceDraft = await computeCustomInvoiceTotals({
+    zitadelOrgId: draft.zitadelOrgId,
+    payload: draft.payload,
+  });
+
+  // Two-pass: persist without PDF first, render against the canonical
+  // row (now has a number), then attach. Same pattern as the auto
+  // flow — keeps the PDF self-referential without juggling temporary
+  // numbers.
+  const placeholder = await createInvoice(invoiceDraft, null, null);
+
+  let pdfBuffer: Buffer | null = null;
+  try {
+    pdfBuffer = await renderInvoicePdf(
+      placeholder,
+      // Same pattern as the auto-cron generateInvoice: synthesize
+      // temporary ids for the PDF renderer. The real DB rows have
+      // these populated post-insert, but the renderer only reads
+      // them for React keys (display) and id-comparison-free
+      // operations, so synthetic values are fine.
+      invoiceDraft.lines.map((l, i) => ({
+        ...l,
+        id: `tmp-${i}`,
+        invoiceId: placeholder.id,
+      }))
+    );
+    const filename = `${placeholder.invoiceNumber}.pdf`;
+    await updateInvoicePdf(placeholder.id, pdfBuffer, filename);
+  } catch (e) {
+    console.error(
+      `Custom invoice ${placeholder.invoiceNumber} persisted but PDF render failed:`,
+      e
+    );
+    // Don't throw — the row exists. Admin can re-render via a
+    // future tool (Phase 8.5 or just by deleting+reissuing).
+  }
+
+  // Best-effort email.
+  try {
+    const snap = invoiceDraft.billingSnapshot;
+    if (snap.billingEmail) {
+      await sendInvoiceIssuedEmail({
+        to: snap.billingEmail,
+        contactName: snap.contactName || snap.companyName,
+        companyName: snap.companyName,
+        invoiceNumber: placeholder.invoiceNumber,
+        totalChf: placeholder.totalChf,
+        currency: "CHF",
+        dueAt: placeholder.dueAt,
+        lineCount: invoiceDraft.lines.length,
+        periodStart: null,
+        periodEnd: null,
+        locale: invoiceDraft.locale as "de" | "en" | "fr" | "it",
+      });
+    }
+  } catch (e) {
+    console.error(
+      `Custom invoice ${placeholder.invoiceNumber} issued; email send failed.`,
+      e
+    );
+  }
+
+  // Draft did its job — remove it. If this fails the issuance
+  // still stands (we already have a real invoice). Log and move on.
+  try {
+    await deleteInvoiceDraft(draft.id);
+  } catch (e) {
+    console.error(
+      `Custom invoice ${placeholder.invoiceNumber} issued but draft ${draft.id} could not be deleted:`,
+      e
+    );
+  }
+
+  return placeholder;
+}
+
+/**
+ * Preview a draft as a PDF without persisting an invoice. The PDF
+ * is rendered with a placeholder number ("DRAFT") and not stored
+ * anywhere — the caller streams the bytes back to the admin's
+ * browser for review.
+ *
+ * Throws CustomInvoiceValidationError if the draft isn't ready to
+ * issue (no lines, missing billing snapshot, etc.) so the editor
+ * can surface the problem before any rendering work.
+ */
+export async function renderCustomDraftPreview(
+  draftId: string
+): Promise<Buffer> {
+  const draft = await getInvoiceDraftById(draftId);
+  if (!draft) {
+    throw new CustomInvoiceValidationError(`Draft not found: ${draftId}`);
+  }
+  const invoiceDraft = await computeCustomInvoiceTotals({
+    zitadelOrgId: draft.zitadelOrgId,
+    payload: draft.payload,
+  });
+
+  // Render against a synthetic Invoice — same shape the persisted
+  // row would have, but with a DRAFT placeholder number. No DB
+  // writes. The PDF renderer doesn't care; it just consumes the
+  // Invoice + lines.
+  const fakeInvoice: Invoice = {
+    id: "preview",
+    invoiceNumber: "DRAFT",
+    zitadelOrgId: draft.zitadelOrgId,
+    source: "custom",
+    periodStart: null,
+    periodEnd: null,
+    issuedAt: invoiceDraft.issuedAt ?? new Date().toISOString(),
+    dueAt: invoiceDraft.dueAt,
+    subtotalChf: invoiceDraft.subtotalChf,
+    vatRate: invoiceDraft.vatRate,
+    vatAmountChf: invoiceDraft.vatAmountChf,
+    totalChf: invoiceDraft.totalChf,
+    status: "draft",
+    locale: invoiceDraft.locale,
+    paymentMethod: invoiceDraft.paymentMethod,
+    billingSnapshot: invoiceDraft.billingSnapshot,
+    stripePaymentIntentId: null,
+    pdfFilename: null,
+    hasPdf: false,
+    adminNotes: null,
+    paidAt: null,
+    paidBy: null,
+    paidMethodDetail: null,
+    voidReason: null,
+    voidedAt: null,
+    voidedBy: null,
+    refundedTotalChf: 0,
+    createdAt: new Date().toISOString(),
+  };
+  return renderInvoicePdf(
+    fakeInvoice,
+    invoiceDraft.lines.map((l, i) => ({
+      ...l,
+      id: `tmp-${i}`,
+      invoiceId: fakeInvoice.id,
+    }))
+  );
+}

src/lib/credit-note-pdf.tsx

@@ -0,0 +1,467 @@
+/**
+ * Credit-note PDF rendering via @react-pdf/renderer.
+ *
+ * Phase 7. Renders the same brand identity as the invoice PDF
+ * (hexagon logo, issuer block, layout) with one accent override:
+ * red instead of emerald. That difference is enough to make voids
+ * and refunds visually unmistakable from an invoice at a glance,
+ * while keeping every other element (logo shape, fonts, structure,
+ * issuer info, page footer) identical so the document family reads
+ * as one brand.
+ *
+ * Brand + Logo come from lib/pdf-brand. Edit there to change
+ * issuer info, colours, or the logo glyph — both invoice and
+ * credit-note PDFs pick the changes up.
+ */
+
+import React from "react";
+import {
+  Document,
+  Page,
+  Text,
+  View,
+  StyleSheet,
+  renderToBuffer,
+} from "@react-pdf/renderer";
+import type { CreditNote, Invoice } from "@/types";
+import { BRAND, Logo } from "./pdf-brand";
+
+
+// ---------------------------------------------------------------------------
+// Localized strings
+// ---------------------------------------------------------------------------
+
+interface CreditNoteStrings {
+  creditNote: string;
+  creditNoteNumber: string;
+  issueDate: string;
+  billTo: string;
+  attentionPrefix: string;
+  referenceInvoice: string;
+  reason: string;
+  voidLineLabel: string;
+  refundLineLabel: string;
+  subtotal: string;
+  vatLabel: string;
+  totalCredited: string;
+  footerVoidNote: string;
+  footerRefundNote: string;
+  vatNoteSwiss: string;
+  vatNoteReverseCharge: string;
+  vatNoteOutOfScope: string;
+}
+
+const MESSAGES: Record<string, CreditNoteStrings> = {
+  de: {
+    creditNote: "Gutschrift",
+    creditNoteNumber: "Gutschrift-Nr.",
+    issueDate: "Ausstellungsdatum",
+    billTo: "Empfänger",
+    attentionPrefix: "z.Hd.",
+    referenceInvoice: "Bezug Rechnung",
+    reason: "Begründung",
+    voidLineLabel: "Stornierung Rechnung {number}",
+    refundLineLabel: "Rückerstattung Rechnung {number}",
+    subtotal: "Zwischensumme",
+    vatLabel: "MWST",
+    totalCredited: "Gesamtbetrag Gutschrift",
+    footerVoidNote:
+      "Diese Gutschrift storniert die oben referenzierte Rechnung. Ein Zahlungsausgleich ist nicht erforderlich.",
+    footerRefundNote:
+      "Diese Gutschrift dokumentiert die Rückerstattung des oben genannten Betrags. Die Auszahlung erfolgt über den ursprünglichen Zahlungsweg.",
+    vatNoteSwiss:
+      "MWST gemäss schweizerischem Mehrwertsteuergesetz (MWSTG).",
+    vatNoteReverseCharge:
+      "Reverse Charge: Steuerschuldnerschaft des Leistungsempfängers nach Art. 196 EU-MwStSyst-RL bzw. nationaler Umsetzung.",
+    vatNoteOutOfScope:
+      "Leistung ausserhalb des Geltungsbereichs der schweizerischen MWST.",
+  },
+  en: {
+    creditNote: "Credit note",
+    creditNoteNumber: "Credit note no.",
+    issueDate: "Issue date",
+    billTo: "Bill to",
+    attentionPrefix: "Attn:",
+    referenceInvoice: "Reference invoice",
+    reason: "Reason",
+    voidLineLabel: "Void of invoice {number}",
+    refundLineLabel: "Refund for invoice {number}",
+    subtotal: "Subtotal",
+    vatLabel: "VAT",
+    totalCredited: "Total credited",
+    footerVoidNote:
+      "This credit note voids the referenced invoice. No payment is required.",
+    footerRefundNote:
+      "This credit note documents the refund of the amount above. Settlement occurs via the original payment method.",
+    vatNoteSwiss:
+      "VAT charged in accordance with Swiss VAT law (MWSTG).",
+    vatNoteReverseCharge:
+      "Reverse charge: VAT to be accounted for by the recipient per Art. 196 EU VAT Directive or national implementation.",
+    vatNoteOutOfScope:
+      "Service supplied outside the scope of Swiss VAT.",
+  },
+  fr: {
+    creditNote: "Note de crédit",
+    creditNoteNumber: "N° de note de crédit",
+    issueDate: "Date d'émission",
+    billTo: "Destinataire",
+    attentionPrefix: "À l'attention de",
+    referenceInvoice: "Facture de référence",
+    reason: "Motif",
+    voidLineLabel: "Annulation de la facture {number}",
+    refundLineLabel: "Remboursement de la facture {number}",
+    subtotal: "Sous-total",
+    vatLabel: "TVA",
+    totalCredited: "Total du crédit",
+    footerVoidNote:
+      "Cette note de crédit annule la facture référencée ci-dessus. Aucun paiement n'est requis.",
+    footerRefundNote:
+      "Cette note de crédit documente le remboursement du montant ci-dessus. Le règlement s'effectue via le moyen de paiement initial.",
+    vatNoteSwiss:
+      "TVA facturée conformément à la loi suisse sur la TVA (LTVA).",
+    vatNoteReverseCharge:
+      "Autoliquidation : TVA à acquitter par le destinataire selon l'art. 196 de la directive TVA UE ou sa mise en œuvre nationale.",
+    vatNoteOutOfScope:
+      "Prestation hors du champ d'application de la TVA suisse.",
+  },
+  it: {
+    creditNote: "Nota di credito",
+    creditNoteNumber: "N. nota di credito",
+    issueDate: "Data di emissione",
+    billTo: "Destinatario",
+    attentionPrefix: "c.a.",
+    referenceInvoice: "Fattura di riferimento",
+    reason: "Motivo",
+    voidLineLabel: "Annullamento della fattura {number}",
+    refundLineLabel: "Rimborso della fattura {number}",
+    subtotal: "Subtotale",
+    vatLabel: "IVA",
+    totalCredited: "Totale accreditato",
+    footerVoidNote:
+      "Questa nota di credito annulla la fattura sopra indicata. Non è richiesto alcun pagamento.",
+    footerRefundNote:
+      "Questa nota di credito documenta il rimborso dell'importo sopra indicato. Il regolamento avviene tramite il metodo di pagamento originale.",
+    vatNoteSwiss:
+      "IVA addebitata in conformità alla legge svizzera sull'IVA (LIVA).",
+    vatNoteReverseCharge:
+      "Inversione contabile: IVA dovuta dal destinatario ai sensi dell'art. 196 della direttiva IVA UE o della sua attuazione nazionale.",
+    vatNoteOutOfScope:
+      "Prestazione fuori dal campo di applicazione dell'IVA svizzera.",
+  },
+};
+
+function pickStrings(locale: string): CreditNoteStrings {
+  return MESSAGES[locale] ?? MESSAGES.de;
+}
+
+// Swiss number formatting — matches billing-pdf for consistency
+function fmtChf(n: number): string {
+  const fixed = n.toFixed(2);
+  const [intPart, decPart] = fixed.split(".");
+  const withSep = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, "'");
+  return decPart ? `${withSep}.${decPart}` : withSep;
+}
+
+function fmtDate(iso: string, locale: string): string {
+  const [y, m, d] = iso.split("T")[0].split("-").map(Number);
+  if (locale === "en") {
+    return new Date(Date.UTC(y, m - 1, d)).toLocaleDateString("en-US", {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+    });
+  }
+  return `${String(d).padStart(2, "0")}.${String(m).padStart(2, "0")}.${y}`;
+}
+
+function pickVatNote(
+  invoice: Invoice,
+  strings: CreditNoteStrings
+): string | null {
+  const country = invoice.billingSnapshot.country?.toUpperCase();
+  const hasVat = invoice.billingSnapshot.vatNumber?.trim();
+  if (country === "CH" || country === "LI") return strings.vatNoteSwiss;
+  if (hasVat) return strings.vatNoteReverseCharge;
+  return strings.vatNoteOutOfScope;
+}
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const styles = StyleSheet.create({
+  page: {
+    paddingTop: 36,
+    paddingBottom: 50,
+    paddingHorizontal: 50,
+    fontSize: 10,
+    fontFamily: "Helvetica",
+    color: BRAND.textColor,
+  },
+  headerRow: {
+    flexDirection: "row",
+    justifyContent: "space-between",
+    marginBottom: 32,
+  },
+  logoBlock: { flexDirection: "row", alignItems: "center" },
+  brandName: {
+    fontSize: 16,
+    color: BRAND.primaryDark,
+    marginLeft: 8,
+    fontFamily: "Helvetica-Bold",
+  },
+  issuerBlock: { textAlign: "right", fontSize: 8.5, color: BRAND.mutedColor },
+  issuerName: { fontSize: 11, color: BRAND.primaryDark, marginBottom: 2 },
+  docTitle: {
+    fontSize: 22,
+    color: BRAND.primaryDark,
+    marginBottom: 8,
+    fontFamily: "Helvetica-Bold",
+  },
+  metaTable: {
+    flexDirection: "row",
+    justifyContent: "space-between",
+    marginBottom: 20,
+  },
+  metaCol: { flexDirection: "column", minWidth: 140 },
+  metaLabel: { fontSize: 8, color: BRAND.mutedColor, marginBottom: 2 },
+  metaValue: { fontSize: 10 },
+  billTo: {
+    marginBottom: 24,
+    padding: 8,
+    backgroundColor: "#f7f7f5",
+    borderLeftWidth: 3,
+    borderLeftColor: BRAND.primary,
+  },
+  billToLabel: { fontSize: 8, color: BRAND.mutedColor, marginBottom: 4 },
+  billToName: { fontSize: 11, marginBottom: 2 },
+  amountTable: {
+    borderTopWidth: 1,
+    borderTopColor: BRAND.borderColor,
+    borderBottomWidth: 1,
+    borderBottomColor: BRAND.borderColor,
+    marginBottom: 16,
+  },
+  amountHeader: {
+    flexDirection: "row",
+    backgroundColor: BRAND.primaryDark,
+    color: "#ffffff",
+    paddingVertical: 5,
+    paddingHorizontal: 6,
+    fontSize: 9,
+    fontFamily: "Helvetica-Bold",
+  },
+  amountRow: {
+    flexDirection: "row",
+    paddingVertical: 8,
+    paddingHorizontal: 6,
+    borderBottomWidth: 1,
+    borderBottomColor: "#f0f0f0",
+  },
+  amountDesc: { flex: 1 },
+  amountValue: { width: 90, textAlign: "right" },
+  totals: { marginLeft: "auto", width: 220, marginBottom: 20 },
+  totalsRow: {
+    flexDirection: "row",
+    justifyContent: "space-between",
+    paddingVertical: 3,
+  },
+  totalsLabel: { color: BRAND.mutedColor, fontSize: 10 },
+  totalsValue: { fontSize: 10 },
+  totalsGrand: {
+    flexDirection: "row",
+    justifyContent: "space-between",
+    borderTopWidth: 1,
+    borderTopColor: BRAND.primaryDark,
+    paddingTop: 6,
+    marginTop: 4,
+  },
+  totalsGrandLabel: {
+    color: BRAND.primaryDark,
+    fontSize: 11,
+    fontFamily: "Helvetica-Bold",
+  },
+  totalsGrandValue: {
+    color: BRAND.primaryDark,
+    fontSize: 11,
+    textAlign: "right",
+    fontFamily: "Helvetica-Bold",
+  },
+  reasonBox: {
+    marginTop: 4,
+    marginBottom: 18,
+    padding: 8,
+    backgroundColor: "#fafafa",
+    borderLeftWidth: 2,
+    borderLeftColor: BRAND.borderColor,
+  },
+  reasonLabel: {
+    fontSize: 8,
+    color: BRAND.mutedColor,
+    marginBottom: 2,
+    textTransform: "uppercase",
+    letterSpacing: 0.5,
+  },
+  reasonText: { fontSize: 9.5, color: BRAND.textColor },
+  noteBox: {
+    marginTop: 12,
+    padding: 8,
+    fontSize: 8.5,
+    color: BRAND.mutedColor,
+    lineHeight: 1.5,
+  },
+  footer: {
+    position: "absolute",
+    bottom: 24,
+    left: 50,
+    right: 50,
+    fontSize: 7.5,
+    color: BRAND.mutedColor,
+    textAlign: "center",
+    borderTopWidth: 0.5,
+    borderTopColor: BRAND.borderColor,
+    paddingTop: 6,
+  },
+});
+
+interface CreditNotePdfProps {
+  creditNote: CreditNote;
+  invoice: Invoice;
+}
+
+function CreditNotePdfDocument({ creditNote, invoice }: CreditNotePdfProps) {
+  const strings = pickStrings(creditNote.locale);
+  const snap = creditNote.billingSnapshot;
+  const vatNote = pickVatNote(invoice, strings);
+  const amountLabelTemplate =
+    creditNote.kind === "void" ? strings.voidLineLabel : strings.refundLineLabel;
+  const amountLabel = amountLabelTemplate.replace(
+    "{number}",
+    invoice.invoiceNumber
+  );
+  const footerNote =
+    creditNote.kind === "void" ? strings.footerVoidNote : strings.footerRefundNote;
+  // Stored convention: amount_chf is gross (incl. VAT),
+  // vat_amount_chf is the VAT portion. Subtotal computed for
+  // display.
+  const subtotal = creditNote.amountChf - creditNote.vatAmountChf;
+  return (
+    <Document>
+      <Page size="A4" style={styles.page}>
+        {/* Header — SAME hexagon logo as the invoice, tinted red.
+            Issuer block from BRAND.issuer (shared with invoice). */}
+        <View style={styles.headerRow}>
+          <View style={styles.logoBlock}>
+            <Logo size={42} color={BRAND.primary} />
+            <Text style={styles.brandName}>{BRAND.name}</Text>
+          </View>
+          <View style={styles.issuerBlock}>
+            <Text style={styles.issuerName}>{BRAND.issuer.legalName}</Text>
+            <Text>{BRAND.issuer.addressLine1}</Text>
+            <Text>{BRAND.issuer.addressLine2}</Text>
+            <Text>{BRAND.issuer.postalCity}</Text>
+            <Text>{BRAND.issuer.country}</Text>
+            <Text>{BRAND.issuer.email}</Text>
+            <Text>{BRAND.issuer.web}</Text>
+            {BRAND.issuer.vatNumber && (
+              <Text>MWST-Nr. {BRAND.issuer.vatNumber}</Text>
+            )}
+          </View>
+        </View>
+
+        <Text style={styles.docTitle}>{strings.creditNote}</Text>
+
+        <View style={styles.metaTable}>
+          <View style={styles.metaCol}>
+            <Text style={styles.metaLabel}>{strings.creditNoteNumber}</Text>
+            <Text style={styles.metaValue}>{creditNote.creditNoteNumber}</Text>
+          </View>
+          <View style={styles.metaCol}>
+            <Text style={styles.metaLabel}>{strings.issueDate}</Text>
+            <Text style={styles.metaValue}>
+              {fmtDate(creditNote.issuedAt, creditNote.locale)}
+            </Text>
+          </View>
+          <View style={styles.metaCol}>
+            <Text style={styles.metaLabel}>{strings.referenceInvoice}</Text>
+            <Text style={styles.metaValue}>{invoice.invoiceNumber}</Text>
+          </View>
+        </View>
+
+        <View style={styles.billTo}>
+          <Text style={styles.billToLabel}>{strings.billTo}</Text>
+          <Text style={styles.billToName}>{snap.companyName}</Text>
+          {snap.contactName && snap.contactName.trim().length > 0 && (
+            <Text>
+              {strings.attentionPrefix} {snap.contactName}
+            </Text>
+          )}
+          <Text>{snap.streetAddress}</Text>
+          <Text>
+            {snap.postalCode} {snap.city}
+          </Text>
+          <Text>{snap.country}</Text>
+          {snap.vatNumber && <Text>MWST/VAT: {snap.vatNumber}</Text>}
+        </View>
+
+        <View style={styles.amountTable}>
+          <View style={styles.amountHeader}>
+            <Text style={styles.amountDesc}> </Text>
+            <Text style={styles.amountValue}>CHF</Text>
+          </View>
+          <View style={styles.amountRow}>
+            <Text style={styles.amountDesc}>{amountLabel}</Text>
+            <Text style={styles.amountValue}>{fmtChf(subtotal)}</Text>
+          </View>
+        </View>
+
+        <View style={styles.totals}>
+          <View style={styles.totalsRow}>
+            <Text style={styles.totalsLabel}>{strings.subtotal}</Text>
+            <Text style={styles.totalsValue}>CHF {fmtChf(subtotal)}</Text>
+          </View>
+          {creditNote.vatAmountChf > 0 && (
+            <View style={styles.totalsRow}>
+              <Text style={styles.totalsLabel}>
+                {strings.vatLabel} ({Number(invoice.vatRate).toFixed(1)}%)
+              </Text>
+              <Text style={styles.totalsValue}>
+                CHF {fmtChf(creditNote.vatAmountChf)}
+              </Text>
+            </View>
+          )}
+          <View style={styles.totalsGrand}>
+            <Text style={styles.totalsGrandLabel}>{strings.totalCredited}</Text>
+            <Text style={styles.totalsGrandValue}>
+              CHF {fmtChf(creditNote.amountChf)}
+            </Text>
+          </View>
+        </View>
+
+        {creditNote.reason && creditNote.reason.trim().length > 0 && (
+          <View style={styles.reasonBox}>
+            <Text style={styles.reasonLabel}>{strings.reason}</Text>
+            <Text style={styles.reasonText}>{creditNote.reason}</Text>
+          </View>
+        )}
+
+        <View style={styles.noteBox}>
+          <Text>{footerNote}</Text>
+          {vatNote && <Text style={{ marginTop: 6 }}>{vatNote}</Text>}
+        </View>
+
+        <Text style={styles.footer} fixed>
+          {BRAND.issuer.legalName} · {creditNote.creditNoteNumber}
+        </Text>
+      </Page>
+    </Document>
+  );
+}
+
+export async function renderCreditNotePdf(
+  creditNote: CreditNote,
+  invoice: Invoice
+): Promise<Buffer> {
+  const doc = <CreditNotePdfDocument creditNote={creditNote} invoice={invoice} />;
+  return renderToBuffer(doc) as unknown as Buffer;
+}

src/lib/cron.ts

@@ -0,0 +1,360 @@
+/**
+ * Phase 5 — Automated billing cron logic.
+ *
+ * This module hosts the two sweeps:
+ *   - runMonthlyIssuance() — invoked monthly to generate invoices
+ *     for orgs opted into auto-issuance. Idempotent via the
+ *     uniq_invoices_org_period constraint on invoices: a re-run
+ *     for an org that's already been billed for the target period
+ *     gets caught as a duplicate and counted as a skip, not a
+ *     failure.
+ *   - runReminderSweep() — invoked daily. Walks open/overdue
+ *     invoices, sends the appropriate reminder level (1/2/3) once
+ *     per invoice via the invoice_reminders unique-key constraint.
+ *
+ * Both entry points return a summary {success, failure, skipped}
+ * that the caller persists via finishCronRun(). The shared
+ * structure means the HTTP routes (machine + admin variants) are
+ * trivial wrappers.
+ *
+ * Time-of-month math is timezone-aware: we read the calendar in
+ * Europe/Zurich rather than UTC, because the K8s CronJob schedules
+ * at 00:30 local time on the 1st — UTC at that moment is still in
+ * the previous month, and a naive `getUTCMonth() - 1` would bill
+ * the wrong period.
+ */
+
+import {
+  finishCronRun,
+  getLastSuccessfulCronRuns,
+  getOrgBilling,
+  getReminderLevelsSent,
+  listAutoIssueOrgIds,
+  listInvoicesPendingReminders,
+  recordReminderSent,
+  startCronRun,
+  syncOverdueInvoices,
+} from "./db";
+import { generateInvoice } from "./billing";
+import { sendInvoiceReminderEmail } from "./email";
+
+// The org_billing snapshot's company_name field doubles as the
+// recipient name when no separate "billing contact" exists in
+// our schema. Same convention as Phase 3's issuance email.
+
+// All cron timing assumes Switzerland's calendar — the operator,
+// the customers, and the legal basis (Swiss MWST) are all here.
+const TZ = "Europe/Zurich";
+
+export type CronSummary = {
+  successCount: number;
+  failureCount: number;
+  skippedCount: number;
+  errorDetails: Array<{
+    orgId?: string;
+    invoiceId?: string;
+    reason: string;
+  }>;
+};
+
+// ---------------------------------------------------------------------------
+// Monthly issuance
+// ---------------------------------------------------------------------------
+
+/**
+ * The (year, month) of the calendar month that ended JUST BEFORE
+ * `now` in the configured timezone. This is what the issuance
+ * sweep bills.
+ *
+ * Reading the local-time calendar avoids a UTC-vs-local off-by-one
+ * when the sweep runs at 00:30 Zurich and UTC is still in the
+ * previous month.
+ */
+export function previousLocalMonth(
+  now: Date = new Date()
+): { year: number; month: number } {
+  const fmt = new Intl.DateTimeFormat("en-CA", {
+    timeZone: TZ,
+    year: "numeric",
+    month: "2-digit",
+  });
+  const parts = fmt.formatToParts(now);
+  const year = Number(parts.find((p) => p.type === "year")!.value);
+  const month = Number(parts.find((p) => p.type === "month")!.value);
+  if (month === 1) return { year: year - 1, month: 12 };
+  return { year, month: month - 1 };
+}
+
+export async function runMonthlyIssuance(opts: {
+  triggeredBy: string;
+  /** Override target year/month — defaults to previous local month. */
+  year?: number;
+  month?: number;
+}): Promise<{ runId: string; summary: CronSummary }> {
+  const target =
+    opts.year && opts.month
+      ? { year: opts.year, month: opts.month }
+      : previousLocalMonth();
+  const runId = await startCronRun("monthly_issue", opts.triggeredBy);
+  const summary: CronSummary = {
+    successCount: 0,
+    failureCount: 0,
+    skippedCount: 0,
+    errorDetails: [],
+  };
+
+  try {
+    const orgIds = await listAutoIssueOrgIds();
+    for (const orgId of orgIds) {
+      try {
+        const orgBilling = await getOrgBilling(orgId);
+        if (!orgBilling) {
+          // Auto-issue is enabled but billing details are missing.
+          // Skip rather than fail — the admin needs to complete the
+          // address before invoicing can succeed.
+          summary.skippedCount += 1;
+          summary.errorDetails.push({
+            orgId,
+            reason: "org_billing not configured",
+          });
+          continue;
+        }
+        // Derive invoice locale from the org's country. PieCed is
+        // Swiss-default; CH/LI/AT/DE customers get the German PDF,
+        // FR/BE/LU customers get French, IT customers get Italian,
+        // anything else falls through to English. Customers needing
+        // a different locale can still trigger a manual issuance
+        // with an explicit override from the admin UI.
+        const locale = pickLocaleForCountry(orgBilling.country);
+        const { invoice } = await generateInvoice({
+          zitadelOrgId: orgId,
+          year: target.year,
+          month: target.month,
+          locale,
+        });
+        if (invoice) {
+          summary.successCount += 1;
+        } else {
+          // dryRun path — shouldn't happen in production. Defensive.
+          summary.skippedCount += 1;
+        }
+      } catch (e: any) {
+        // The uniqueness constraint on (zitadel_org_id, period_start)
+        // surfaces as "An invoice already exists for this org and
+        // billing period" from createInvoice. Re-running the cron
+        // mid-month or after a partial completion is therefore safe:
+        // already-billed orgs end up as skipped, not failed.
+        const msg = String(e?.message ?? e);
+        const isAlreadyIssued = /already exists for this org and billing period/i.test(
+          msg
+        );
+        if (isAlreadyIssued) {
+          summary.skippedCount += 1;
+        } else {
+          summary.failureCount += 1;
+          summary.errorDetails.push({ orgId, reason: msg });
+          console.error(
+            `runMonthlyIssuance: org ${orgId} failed:`,
+            e
+          );
+        }
+      }
+    }
+    await finishCronRun(runId, summary);
+    return { runId, summary };
+  } catch (e) {
+    // Catastrophic — the sweep itself failed (DB down, etc).
+    summary.failureCount += 1;
+    summary.errorDetails.push({
+      reason: `sweep aborted: ${e instanceof Error ? e.message : String(e)}`,
+    });
+    await finishCronRun(runId, summary).catch(() => undefined);
+    throw e;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Reminder sweep
+// ---------------------------------------------------------------------------
+
+/**
+ * Which reminder level (if any) is due now for this invoice?
+ *
+ * Logic:
+ *   - days_past_due >= 30 AND level 3 not yet sent → 3 (final)
+ *   - else days_past_due >= 14 AND level 2 not yet sent → 2
+ *   - else days_past_due >=  7 AND level 1 not yet sent → 1
+ *   - else → null (nothing to do this run)
+ *
+ * One reminder per cron run per invoice — highest applicable
+ * un-sent level wins. If a customer fell behind quickly and is
+ * already 35 days past due without ever having received levels
+ * 1 or 2 (e.g. the cron was broken for a while), they get level
+ * 3 directly. We don't backfill lower levels.
+ */
+function nextReminderLevel(
+  daysPastDue: number,
+  sent: Set<number>
+): 1 | 2 | 3 | null {
+  if (daysPastDue >= 30 && !sent.has(3)) return 3;
+  if (daysPastDue >= 14 && !sent.has(2)) return 2;
+  if (daysPastDue >= 7 && !sent.has(1)) return 1;
+  return null;
+}
+
+function daysBetween(later: Date, earlier: Date): number {
+  const ms = later.getTime() - earlier.getTime();
+  return Math.floor(ms / (1000 * 60 * 60 * 24));
+}
+
+/**
+ * Pick a default invoice locale based on the org's country
+ * (ISO 3166-1 alpha-2 code from org_billing.country). PieCed is
+ * primarily a Swiss-German operator; CH/LI/AT/DE get German,
+ * FR/BE/LU get French, IT gets Italian, anything else falls
+ * through to English.
+ *
+ * This only drives the automated issuance default. Manual
+ * issuance from the admin UI takes an explicit override.
+ */
+function pickLocaleForCountry(country: string): "de" | "en" | "fr" | "it" {
+  const c = country.toUpperCase();
+  if (["CH", "LI", "AT", "DE"].includes(c)) return "de";
+  if (["FR", "BE", "LU"].includes(c)) return "fr";
+  if (c === "IT") return "it";
+  return "en";
+}
+
+export async function runReminderSweep(opts: {
+  triggeredBy: string;
+}): Promise<{ runId: string; summary: CronSummary }> {
+  const runId = await startCronRun("reminders", opts.triggeredBy);
+  const summary: CronSummary = {
+    successCount: 0,
+    failureCount: 0,
+    skippedCount: 0,
+    errorDetails: [],
+  };
+
+  try {
+    // Flip stale 'open' → 'overdue' first so the listing reflects
+    // current status, and audit trails stay accurate.
+    await syncOverdueInvoices().catch((e) => {
+      console.warn("syncOverdueInvoices failed during reminder sweep:", e);
+    });
+
+    const candidates = await listInvoicesPendingReminders();
+    const now = new Date();
+
+    for (const inv of candidates) {
+      try {
+        const sent = await getReminderLevelsSent(inv.id);
+        const dueAt = new Date(inv.dueAt);
+        const days = daysBetween(now, dueAt);
+        const level = nextReminderLevel(days, sent);
+        if (level === null) {
+          summary.skippedCount += 1;
+          continue;
+        }
+        const billing = inv.billingSnapshot;
+        if (!billing.billingEmail) {
+          summary.skippedCount += 1;
+          summary.errorDetails.push({
+            invoiceId: inv.id,
+            reason: "no billing email on snapshot",
+          });
+          continue;
+        }
+        const supportedLocales: Array<"de" | "en" | "fr" | "it"> = [
+          "de", "en", "fr", "it",
+        ];
+        const locale = supportedLocales.includes(inv.locale as any)
+          ? (inv.locale as "de" | "en" | "fr" | "it")
+          : "de";
+
+        await sendInvoiceReminderEmail({
+          to: billing.billingEmail,
+          contactName: billing.companyName,
+          companyName: billing.companyName,
+          invoiceNumber: inv.invoiceNumber,
+          totalChf: inv.totalChf,
+          currency: "CHF",
+          dueAt: inv.dueAt,
+          daysPastDue: days,
+          level,
+          locale,
+        });
+        // Record AFTER the send. If the SMTP send fails the email
+        // helper logs and doesn't throw, so we'd still record — but
+        // that's a tradeoff we accept: at-least-once delivery semantics
+        // with logged warnings is better than at-most-once where a
+        // transient failure stops the customer from ever getting
+        // reminded. If duplicate-reminder fatigue becomes a real
+        // problem in production, switch to: send first, only record
+        // on confirmed transporter success.
+        await recordReminderSent({
+          invoiceId: inv.id,
+          level,
+          sentBy: opts.triggeredBy,
+          emailSentTo: billing.billingEmail,
+        });
+        summary.successCount += 1;
+      } catch (e: any) {
+        summary.failureCount += 1;
+        summary.errorDetails.push({
+          invoiceId: inv.id,
+          reason: String(e?.message ?? e),
+        });
+        console.error(
+          `runReminderSweep: invoice ${inv.id} failed:`,
+          e
+        );
+      }
+    }
+    await finishCronRun(runId, summary);
+    return { runId, summary };
+  } catch (e) {
+    summary.failureCount += 1;
+    summary.errorDetails.push({
+      reason: `sweep aborted: ${e instanceof Error ? e.message : String(e)}`,
+    });
+    await finishCronRun(runId, summary).catch(() => undefined);
+    throw e;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auth — bearer token for the machine endpoints
+// ---------------------------------------------------------------------------
+
+/**
+ * Constant-time bearer token check. The CRON_BEARER_TOKEN env var
+ * is injected from OpenBao via the portal-cron K8s Secret. Both
+ * the CronJob and the portal Deployment reference it; the
+ * CronJob sends it in the Authorization header, the portal checks
+ * with timing-safe equals to defeat character-by-character probing.
+ */
+export function verifyCronBearer(authHeader: string | null): boolean {
+  if (!authHeader) return false;
+  const expected = process.env.CRON_BEARER_TOKEN;
+  if (!expected || expected.length < 16) {
+    // Treat misconfiguration as a hard refusal so a missing/
+    // accidentally-empty token doesn't silently grant access.
+    return false;
+  }
+  if (!authHeader.startsWith("Bearer ")) return false;
+  const got = authHeader.slice("Bearer ".length).trim();
+  if (got.length !== expected.length) return false;
+  // Constant-time byte compare. Node's Buffer.compare and the
+  // crypto.timingSafeEqual function both work, but the latter
+  // throws on length mismatch; the length pre-check above
+  // protects against that.
+  let diff = 0;
+  for (let i = 0; i < got.length; i++) {
+    diff |= got.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+// Re-export for the admin UI to render "last run X ago" indicators.
+export { getLastSuccessfulCronRuns };

src/lib/email.ts

@@ -923,8 +923,8 @@ export async function sendInvoiceIssuedEmail(params: {
   currency: string; // "CHF" — passed for future-proofing
   dueAt: string;    // ISO date
   lineCount: number;
-  periodStart: string; // ISO date
-  periodEnd: string;   // ISO date
+  periodStart: string | null; // ISO date; null for custom invoices
+  periodEnd: string | null;   // ISO date; null for custom invoices
   locale: "de" | "en" | "fr" | "it";
 }): Promise<void> {
   // All four locales — the email is sent in the invoice's locale,
@@ -960,7 +960,13 @@ export async function sendInvoiceIssuedEmail(params: {
   const safeCompany = escapeHtml(params.companyName);
   const safeNumber = escapeHtml(params.invoiceNumber);
   const totalFmt = `${params.currency} ${params.totalChf.toFixed(2)}`;
-  const periodFmt = `${params.periodStart.slice(0, 10)} → ${params.periodEnd.slice(0, 10)}`;
+  // Phase 8: period is null for custom invoices. When missing, the
+  // template skips the "Service period:" line entirely; otherwise
+  // it renders the date range as before.
+  const periodFmt =
+    params.periodStart && params.periodEnd
+      ? `${params.periodStart.slice(0, 10)} → ${params.periodEnd.slice(0, 10)}`
+      : null;
   const dueFmt = params.dueAt.slice(0, 10);
 
   // Both bodies built in the invoice's locale.
@@ -977,7 +983,9 @@ export async function sendInvoiceIssuedEmail(params: {
         introByLocale[L],
         "",
         `${l.number}:  ${params.invoiceNumber}`,
-        `${l.period}:  ${periodFmt}`,
+        // Phase 8: omit the period line entirely for custom
+        // invoices (which have no billing period).
+        ...(periodFmt ? [`${l.period}:  ${periodFmt}`] : []),
         `${l.total}:   ${totalFmt}`,
         `${l.due}:     ${dueFmt}`,
         `${l.lines}:   ${params.lineCount}`,
@@ -995,7 +1003,7 @@ export async function sendInvoiceIssuedEmail(params: {
           <p>${escapeHtml(introByLocale[L])}</p>
           <table style="width:100%; border-collapse:collapse; margin:16px 0; font-size:14px;">
             <tr><td style="color:#888; padding:6px 0; width:120px;">${l.number}</td><td><strong>${safeNumber}</strong></td></tr>
-            <tr><td style="color:#888; padding:6px 0;">${l.period}</td><td>${escapeHtml(periodFmt)}</td></tr>
+            ${periodFmt ? `<tr><td style="color:#888; padding:6px 0;">${l.period}</td><td>${escapeHtml(periodFmt)}</td></tr>` : ""}
             <tr><td style="color:#888; padding:6px 0;">${l.total}</td><td style="color:#10B981; font-weight:600;">${escapeHtml(totalFmt)}</td></tr>
             <tr><td style="color:#888; padding:6px 0;">${l.due}</td><td>${escapeHtml(dueFmt)}</td></tr>
             <tr><td style="color:#888; padding:6px 0;">${l.lines}</td><td>${params.lineCount}</td></tr>
@@ -1014,3 +1022,302 @@ export async function sendInvoiceIssuedEmail(params: {
     console.error("Failed to send invoice issued email:", err);
   }
 }
+
+// ---------------------------------------------------------------------------
+// Reminder emails — Phase 5
+// ---------------------------------------------------------------------------
+
+/**
+ * Send a payment reminder for an open/overdue invoice.
+ *
+ * Three escalation levels:
+ *   1 — Gentle nudge: ~7 days past due. Friendly tone, "in case
+ *       you missed it".
+ *   2 — Firmer reminder: ~14 days past due. Clear that payment is
+ *       outstanding, please pay.
+ *   3 — Final notice: ~30 days past due. Explicit consequences
+ *       (service may be suspended). Last automated touch — beyond
+ *       this, admin involvement is expected.
+ *
+ * Failure is logged, never thrown — the cron sweep must continue
+ * past a single failed send.
+ */
+export async function sendInvoiceReminderEmail(params: {
+  to: string;
+  contactName: string;
+  companyName: string;
+  invoiceNumber: string;
+  totalChf: number;
+  currency: string;
+  dueAt: string;
+  daysPastDue: number;
+  level: 1 | 2 | 3;
+  locale: "de" | "en" | "fr" | "it";
+}): Promise<void> {
+  const L = params.locale;
+  // Per-locale strings keyed by the three escalation levels.
+  // Kept inline (rather than the next-intl message files) because
+  // the email layer doesn't import from React's i18n context.
+  const SUBJECTS: Record<typeof L, Record<1 | 2 | 3, string>> = {
+    en: {
+      1: `Friendly reminder: invoice ${params.invoiceNumber} is overdue`,
+      2: `Second reminder: invoice ${params.invoiceNumber} is still unpaid`,
+      3: `Final notice: invoice ${params.invoiceNumber} requires immediate payment`,
+    },
+    de: {
+      1: `Freundliche Erinnerung: Rechnung ${params.invoiceNumber} ist überfällig`,
+      2: `Zweite Mahnung: Rechnung ${params.invoiceNumber} ist weiterhin unbezahlt`,
+      3: `Letzte Mahnung: Rechnung ${params.invoiceNumber} erfordert sofortige Zahlung`,
+    },
+    fr: {
+      1: `Rappel amical : la facture ${params.invoiceNumber} est en retard`,
+      2: `Deuxième rappel : la facture ${params.invoiceNumber} reste impayée`,
+      3: `Dernier avis : la facture ${params.invoiceNumber} doit être réglée sans délai`,
+    },
+    it: {
+      1: `Promemoria amichevole: la fattura ${params.invoiceNumber} è scaduta`,
+      2: `Secondo sollecito: la fattura ${params.invoiceNumber} è ancora insoluta`,
+      3: `Avviso finale: la fattura ${params.invoiceNumber} richiede pagamento immediato`,
+    },
+  };
+  const INTROS: Record<typeof L, Record<1 | 2 | 3, string>> = {
+    en: {
+      1: "We noticed this invoice hasn't been settled yet — in case it slipped through.",
+      2: "This invoice remains unpaid. Please arrange payment at your earliest convenience.",
+      3: "This invoice is significantly overdue. Service may be suspended if payment is not received promptly.",
+    },
+    de: {
+      1: "Diese Rechnung scheint noch nicht beglichen — falls sie übersehen wurde, möchten wir freundlich daran erinnern.",
+      2: "Diese Rechnung ist weiterhin unbezahlt. Bitte veranlassen Sie die Zahlung umgehend.",
+      3: "Diese Rechnung ist erheblich überfällig. Bei nicht zeitnaher Zahlung kann der Dienst ausgesetzt werden.",
+    },
+    fr: {
+      1: "Cette facture n'a pas encore été réglée — au cas où elle vous aurait échappé.",
+      2: "Cette facture reste impayée. Merci d'effectuer le paiement dans les meilleurs délais.",
+      3: "Cette facture est en grand retard. Le service pourra être suspendu en l'absence de paiement rapide.",
+    },
+    it: {
+      1: "Questa fattura non risulta ancora saldata — nel caso vi fosse sfuggita.",
+      2: "Questa fattura risulta ancora insoluta. Si prega di provvedere al pagamento al più presto.",
+      3: "Questa fattura è significativamente in ritardo. In assenza di pagamento tempestivo il servizio potrà essere sospeso.",
+    },
+  };
+  const LABELS: Record<typeof L, Record<string, string>> = {
+    en: { num: "Invoice", total: "Total", due: "Due date", days: "Days past due", cta: "View invoice & pay", signoff: "Best regards", brand: "PieCed IT", greeting: "Hello" },
+    de: { num: "Rechnung", total: "Gesamt", due: "Fälligkeitsdatum", days: "Tage überfällig", cta: "Rechnung ansehen & bezahlen", signoff: "Mit freundlichen Grüssen", brand: "PieCed IT", greeting: "Sehr geehrte/r" },
+    fr: { num: "Facture", total: "Total", due: "Échéance", days: "Jours de retard", cta: "Voir la facture & payer", signoff: "Cordialement", brand: "PieCed IT", greeting: "Bonjour" },
+    it: { num: "Fattura", total: "Totale", due: "Scadenza", days: "Giorni di ritardo", cta: "Vedi fattura & paga", signoff: "Cordiali saluti", brand: "PieCed IT", greeting: "Gentile" },
+  };
+  const l = LABELS[L];
+  const safeName = escapeHtml(params.contactName);
+  const safeCompany = escapeHtml(params.companyName);
+  const safeNumber = escapeHtml(params.invoiceNumber);
+  const totalFmt = `${params.currency} ${params.totalChf.toFixed(2)}`;
+  const dueFmt = params.dueAt.slice(0, 10);
+  const link = `https://app.pieced.ch/billing/${encodeURIComponent(params.invoiceNumber)}`;
+  // Final-notice gets red accent; earlier levels keep the brand green.
+  const accent = params.level === 3 ? "#dc2626" : "#10B981";
+
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: params.to,
+      subject: SUBJECTS[L][params.level],
+      text: [
+        `${l.greeting} ${params.contactName},`,
+        "",
+        INTROS[L][params.level],
+        "",
+        `${l.num}:    ${params.invoiceNumber}`,
+        `${l.total}:    ${totalFmt}`,
+        `${l.due}:    ${dueFmt}`,
+        `${l.days}:    ${params.daysPastDue}`,
+        "",
+        `${l.cta}: ${link}`,
+        "",
+        `${l.signoff},`,
+        l.brand,
+      ].join("\n"),
+      html: `
+        <div style="font-family:-apple-system,BlinkMacSystemFont,sans-serif;max-width:560px;padding:24px;background:#1a1a1a;color:#e5e5e5;">
+          <h2 style="margin:0 0 16px;color:${accent};">${escapeHtml(SUBJECTS[L][params.level])}</h2>
+          <p>${l.greeting} ${safeName},</p>
+          <p>${escapeHtml(INTROS[L][params.level])}</p>
+          <table style="width:100%;border-collapse:collapse;margin:16px 0;font-size:14px;">
+            <tr><td style="color:#888;padding:6px 0;width:140px;">${l.num}</td><td><strong>${safeNumber}</strong></td></tr>
+            <tr><td style="color:#888;padding:6px 0;">${l.total}</td><td style="color:${accent};font-weight:600;">${escapeHtml(totalFmt)}</td></tr>
+            <tr><td style="color:#888;padding:6px 0;">${l.due}</td><td>${escapeHtml(dueFmt)}</td></tr>
+            <tr><td style="color:#888;padding:6px 0;">${l.days}</td><td>${params.daysPastDue}</td></tr>
+          </table>
+          <p>
+            <a href="${link}" style="display:inline-block;padding:10px 24px;background:${accent};color:#fff;text-decoration:none;border-radius:8px;font-weight:500;">
+              ${l.cta}
+            </a>
+          </p>
+          <hr style="border:none;border-top:1px solid #333;margin:24px 0;" />
+          <p style="color:#666;font-size:12px;">${l.brand}</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error(
+      `Failed to send reminder L${params.level} for invoice ${params.invoiceNumber}:`,
+      err
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Credit note emails — Phase 7
+// ---------------------------------------------------------------------------
+
+/**
+ * Send a credit-note notification to the customer's billing email.
+ *
+ * Covers both kinds (void and refund). The subject and body adapt
+ * based on `kind` — voids ("we've cancelled invoice X, no payment
+ * needed") read very differently from refunds ("we've refunded CHF
+ * X, expect to see it on your card statement within 5-10 days").
+ *
+ * Link-only — the PDF is not attached. The customer downloads it
+ * from /api/credit-notes/<number>/pdf when they click through, which
+ * also gives them a permanent in-portal record next to their
+ * invoices. Same approach as invoice emails.
+ *
+ * Best-effort: failures are logged and swallowed. A mail-server
+ * hiccup must never roll back a credit-note issuance.
+ */
+export async function sendCreditNoteEmail(params: {
+  to: string;
+  contactName: string;
+  companyName: string;
+  creditNoteNumber: string;
+  invoiceNumber: string;
+  amountChf: number;
+  currency: string;
+  kind: "void" | "refund";
+  reason: string | null;
+  locale: "de" | "en" | "fr" | "it";
+}): Promise<void> {
+  const L = params.locale;
+  const totalFmt = `${params.currency} ${params.amountChf.toFixed(2)}`;
+  const link = `https://app.pieced.ch/billing/cn/${encodeURIComponent(
+    params.creditNoteNumber
+  )}`;
+
+  // Subject lines diverge between void and refund — different
+  // mental models for the recipient. Void: "your charge is
+  // cancelled". Refund: "your money is on the way back".
+  const subjectsByLocale: Record<typeof L, { void: string; refund: string }> = {
+    en: {
+      void: `Invoice ${params.invoiceNumber} cancelled — credit note ${params.creditNoteNumber}`,
+      refund: `Refund of ${totalFmt} for invoice ${params.invoiceNumber} — credit note ${params.creditNoteNumber}`,
+    },
+    de: {
+      void: `Rechnung ${params.invoiceNumber} storniert — Gutschrift ${params.creditNoteNumber}`,
+      refund: `Rückerstattung ${totalFmt} für Rechnung ${params.invoiceNumber} — Gutschrift ${params.creditNoteNumber}`,
+    },
+    fr: {
+      void: `Facture ${params.invoiceNumber} annulée — note de crédit ${params.creditNoteNumber}`,
+      refund: `Remboursement ${totalFmt} pour la facture ${params.invoiceNumber} — note de crédit ${params.creditNoteNumber}`,
+    },
+    it: {
+      void: `Fattura ${params.invoiceNumber} annullata — nota di credito ${params.creditNoteNumber}`,
+      refund: `Rimborso ${totalFmt} per fattura ${params.invoiceNumber} — nota di credito ${params.creditNoteNumber}`,
+    },
+  };
+
+  const greetingsByLocale: Record<typeof L, string> = {
+    en: `Hello ${params.contactName},`,
+    de: `Sehr geehrte/r ${params.contactName},`,
+    fr: `Bonjour ${params.contactName},`,
+    it: `Gentile ${params.contactName},`,
+  };
+
+  // Intro: distinct phrasing per kind in each locale.
+  const introsByLocale: Record<typeof L, { void: string; refund: string }> = {
+    en: {
+      void: `We've cancelled invoice ${params.invoiceNumber}. The invoice is no longer payable, and a credit note has been issued for your records.`,
+      refund: `We've refunded ${totalFmt} for invoice ${params.invoiceNumber}. The refund will appear on the original payment method within 5–10 business days, depending on your bank.`,
+    },
+    de: {
+      void: `Wir haben Rechnung ${params.invoiceNumber} storniert. Die Rechnung ist nicht mehr zahlbar; eine Gutschrift wurde für Ihre Unterlagen ausgestellt.`,
+      refund: `Wir haben ${totalFmt} für Rechnung ${params.invoiceNumber} zurückerstattet. Der Betrag wird je nach Bank innerhalb von 5–10 Geschäftstagen auf dem ursprünglichen Zahlungsweg gutgeschrieben.`,
+    },
+    fr: {
+      void: `Nous avons annulé la facture ${params.invoiceNumber}. La facture n'est plus exigible ; une note de crédit a été émise pour vos archives.`,
+      refund: `Nous avons remboursé ${totalFmt} pour la facture ${params.invoiceNumber}. Le montant apparaîtra sur le moyen de paiement initial sous 5 à 10 jours ouvrés, selon votre banque.`,
+    },
+    it: {
+      void: `Abbiamo annullato la fattura ${params.invoiceNumber}. La fattura non è più dovuta; è stata emessa una nota di credito per la sua documentazione.`,
+      refund: `Abbiamo rimborsato ${totalFmt} per la fattura ${params.invoiceNumber}. L'importo apparirà sul metodo di pagamento originale entro 5–10 giorni lavorativi, a seconda della banca.`,
+    },
+  };
+
+  const labels: Record<typeof L, Record<string, string>> = {
+    en: { creditNote: "Credit note", invoice: "Invoice", amount: "Amount", reason: "Reason", cta: "View credit note & download PDF", signoff: "Best regards", brand: "PieCed IT" },
+    de: { creditNote: "Gutschrift", invoice: "Rechnung", amount: "Betrag", reason: "Begründung", cta: "Gutschrift ansehen & PDF herunterladen", signoff: "Mit freundlichen Grüssen", brand: "PieCed IT" },
+    fr: { creditNote: "Note de crédit", invoice: "Facture", amount: "Montant", reason: "Motif", cta: "Voir la note de crédit & télécharger le PDF", signoff: "Cordialement", brand: "PieCed IT" },
+    it: { creditNote: "Nota di credito", invoice: "Fattura", amount: "Importo", reason: "Motivo", cta: "Visualizza nota di credito & scarica PDF", signoff: "Cordiali saluti", brand: "PieCed IT" },
+  };
+  const l = labels[L];
+
+  const subject = subjectsByLocale[L][params.kind];
+  const intro = introsByLocale[L][params.kind];
+  const safeName = escapeHtml(params.contactName);
+  const safeNumberCN = escapeHtml(params.creditNoteNumber);
+  const safeNumberINV = escapeHtml(params.invoiceNumber);
+  const safeReason = params.reason ? escapeHtml(params.reason) : null;
+
+  // PieCed brand emerald — same accent the invoice email uses.
+  // A credit note is still a PieCed IT document; the company
+  // identity stays consistent across the document family. The
+  // doc type is distinguished by the subject line and copy, not
+  // by colour.
+  const ACCENT = "#10B981";
+
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: params.to,
+      subject,
+      text: [
+        greetingsByLocale[L],
+        "",
+        intro,
+        "",
+        `${l.creditNote}:  ${params.creditNoteNumber}`,
+        `${l.invoice}:    ${params.invoiceNumber}`,
+        `${l.amount}:     ${totalFmt}`,
+        ...(params.reason ? [`${l.reason}:    ${params.reason}`] : []),
+        "",
+        `${l.cta}:`,
+        link,
+        "",
+        `${l.signoff},`,
+        l.brand,
+      ].join("\n"),
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, sans-serif; max-width: 560px; padding: 24px; background: #1a1a1a; color: #e5e5e5;">
+          <h2 style="margin: 0 0 16px; color: ${ACCENT};">${escapeHtml(intro)}</h2>
+          <p>${safeName === "" ? "" : escapeHtml(greetingsByLocale[L])}</p>
+          <table style="width:100%; border-collapse:collapse; margin:16px 0; font-size:14px;">
+            <tr><td style="color:#888; padding:6px 0; width:140px;">${l.creditNote}</td><td><strong>${safeNumberCN}</strong></td></tr>
+            <tr><td style="color:#888; padding:6px 0;">${l.invoice}</td><td>${safeNumberINV}</td></tr>
+            <tr><td style="color:#888; padding:6px 0;">${l.amount}</td><td style="color:${ACCENT}; font-weight:600;">${escapeHtml(totalFmt)}</td></tr>
+            ${safeReason ? `<tr><td style="color:#888; padding:6px 0; vertical-align:top;">${l.reason}</td><td style="color:#bbb;">${safeReason}</td></tr>` : ""}
+          </table>
+          <p>
+            <a href="${link}" style="display:inline-block; padding:10px 24px; background:${ACCENT}; color:#fff; text-decoration:none; border-radius:8px; font-weight:500;">
+              ${l.cta}
+            </a>
+          </p>
+          <hr style="border:none; border-top:1px solid #333; margin:24px 0;" />
+          <p style="color:#666; font-size:12px;">${l.brand}</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error("Failed to send credit note email:", err);
+  }
+}

src/lib/pdf-brand.tsx

@@ -0,0 +1,118 @@
+/**
+ * Shared brand constants and Logo component for all PDF documents
+ * (invoices, credit notes, future quotes / reminders).
+ *
+ * Phase 7 fix: previously each PDF generator carried its own copy
+ * of BRAND and its own Logo. When Cedric customized the invoice
+ * issuer block in his deployment (real Strasse Nr., PLZ, etc.),
+ * the credit note PDF kept the original placeholders because it
+ * had its own duplicate. Hoisting both here means every PDF reads
+ * the same source of truth.
+ *
+ * To change the brand: edit BRAND below. To change the logo:
+ * edit Logo below. To change the issuer info Cedric ships: edit
+ * BRAND.issuer — both billing-pdf.tsx and credit-note-pdf.tsx pick
+ * it up automatically.
+ *
+ * The Logo component accepts a `color` prop so the credit-note
+ * variant can render the SAME shape tinted red (the document
+ * family is visually consistent; only the accent colour signals
+ * "this is a credit, not an invoice").
+ */
+
+import React from "react";
+import { Svg, Polygon, Polyline } from "@react-pdf/renderer";
+
+// ---------------------------------------------------------------------------
+// Brand constants
+// ---------------------------------------------------------------------------
+
+export const BRAND = {
+  name: "PieCed IT",
+  // Primary emerald — matches the logo SVG fill (#10B981).
+  primary: "#10B981",
+  // Slightly darker emerald for headings.
+  primaryDark: "#0a8060",
+  textColor: "#1a1a1a",
+  mutedColor: "#666",
+  borderColor: "#d4d4d4",
+  // Issuer block — change these to your real legal info.
+  // Both billing-pdf.tsx and credit-note-pdf.tsx read from here.
+  issuer: {
+    legalName: "PieCed IT",
+    addressLine1: "Cedric Mosimann",
+    addressLine2: "[Strasse Nr.]",
+    postalCity: "[PLZ] Basel",
+    country: "Switzerland",
+    email: "billing@pieced.ch",
+    web: "pieced.ch",
+    // Show "MWST-Nr. ..." on PDF when set.
+    vatNumber: null as string | null,
+    // Bank instructions — used by invoice PDF, ignored on credit
+    // notes (refunds flow back via the original payment method).
+    bankName: "[Bank name]",
+    bankIban: "[CHxx xxxx xxxx xxxx xxxx x]",
+    bankBic: "[BIC]",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Logo — PieCed's hexagon-pattern mark. Same shape used everywhere
+// and same brand colour. The credit note is still a PieCed IT
+// document and reads with the same company identity as an invoice.
+// ---------------------------------------------------------------------------
+
+interface LogoProps {
+  size?: number;
+  /** Defaults to BRAND.primary. Override only for special cases
+   *  (e.g. an inverse variant on a dark background). Standard
+   *  documents — invoices, credit notes — all use BRAND.primary. */
+  color?: string;
+}
+
+export const Logo = ({ size = 60, color = BRAND.primary }: LogoProps) => (
+  <Svg width={size} height={size * (106 / 70)} viewBox="0 0 70 106">
+    {/* H1 solid */}
+    <Polygon
+      points="38.5,22.69 31.5,10.566 17.5,10.566 10.5,22.69 17.5,34.814 31.5,34.814"
+      fill={color}
+      stroke={color}
+      strokeWidth={1.6}
+    />
+    {/* H2 outline */}
+    <Polygon
+      points="59.5,34.814 52.5,22.69 38.5,22.69 31.5,34.814 38.5,46.938 52.5,46.938"
+      fill="none"
+      stroke={color}
+      strokeWidth={1.8}
+    />
+    {/* H3 outline */}
+    <Polygon
+      points="38.5,46.938 31.5,34.814 17.5,34.814 10.5,46.938 17.5,59.062 31.5,59.062"
+      fill="none"
+      stroke={color}
+      strokeWidth={1.8}
+    />
+    {/* H4 solid */}
+    <Polygon
+      points="59.5,59.062 52.5,46.938 38.5,46.938 31.5,59.062 38.5,71.186 52.5,71.186"
+      fill={color}
+      stroke={color}
+      strokeWidth={1.6}
+    />
+    {/* H5 partial */}
+    <Polyline
+      points="31.5,83.31 38.5,71.186 31.5,59.062 17.5,59.062 10.5,71.186"
+      fill="none"
+      stroke={color}
+      strokeWidth={1.8}
+    />
+    {/* H6 partial */}
+    <Polyline
+      points="59.5,83.31 52.5,71.186 38.5,71.186 31.5,83.31 38.5,95.434"
+      fill="none"
+      stroke={color}
+      strokeWidth={1.8}
+    />
+  </Svg>
+);

src/lib/stripe.ts

@@ -220,7 +220,13 @@ export async function createCheckoutSessionForInvoice(params: {
           unit_amount: chfToRappen(invoice.totalChf),
           product_data: {
             name: `Invoice ${invoice.invoiceNumber}`,
-            description: `PieCed IT — ${invoice.periodStart.slice(0, 10)} → ${invoice.periodEnd.slice(0, 10)}`,
+            // Phase 8: custom invoices have no period — fall back
+            // to a description that just references the invoice
+            // number and due date.
+            description:
+              invoice.periodStart && invoice.periodEnd
+                ? `PieCed IT — ${invoice.periodStart.slice(0, 10)} → ${invoice.periodEnd.slice(0, 10)}`
+                : `PieCed IT — due ${invoice.dueAt.slice(0, 10)}`,
           },
         },
       },
@@ -258,3 +264,57 @@ export async function createCheckoutSessionForInvoice(params: {
   }
   return { url: session.url, sessionId: session.id };
 }
+
+// ---------------------------------------------------------------------------
+// Phase 7 — refunds
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Stripe Refund against an invoice's PaymentIntent.
+ *
+ * The amount is in CHF; we convert to rappen for Stripe's smallest-
+ * currency-unit API. Pass 0 or undefined for `amountChf` to refund
+ * the full charge.
+ *
+ * Returns the Stripe refund object so the caller can record the
+ * refund id and final status. Stripe processes refunds asynchronously
+ * for some payment methods, so the initial status may be 'pending'
+ * — the charge.refunded webhook delivers the eventual succeeded /
+ * failed transition.
+ *
+ * Throws on Stripe API errors (no charge, insufficient balance,
+ * etc.). The caller surfaces these to the admin via the API
+ * response — we don't swallow them because partial-refund logic
+ * shouldn't be guessing about server state.
+ */
+export async function createInvoiceRefund(params: {
+  paymentIntentId: string;
+  amountChf?: number;
+  reason?: "duplicate" | "fraudulent" | "requested_by_customer";
+  metadata?: Record<string, string>;
+}): Promise<{
+  id: string;
+  amountChf: number;
+  status: string;
+}> {
+  const stripe = getStripeClient();
+  const refundParams: Parameters<typeof stripe.refunds.create>[0] = {
+    payment_intent: params.paymentIntentId,
+    metadata: params.metadata,
+  };
+  if (params.amountChf && params.amountChf > 0) {
+    refundParams.amount = chfToRappen(params.amountChf);
+  }
+  if (params.reason) {
+    refundParams.reason = params.reason;
+  }
+  const refund = await stripe.refunds.create(refundParams);
+  // The amount on the response is in rappen; convert back. If no
+  // amount was passed, Stripe defaults to the full remaining
+  // charge, which is what we read back.
+  return {
+    id: refund.id,
+    amountChf: refund.amount != null ? refund.amount / 100 : 0,
+    status: refund.status ?? "unknown",
+  };
+}

src/lib/zitadel.ts

@@ -528,3 +528,113 @@ export async function registerCustomer(params: {
     throw err;
   }
 }
+
+// ---------------------------------------------------------------------------
+// v2 User API — profile updates (Phase 6 fix5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Update a human user's profile (first name + last name + display
+ * name). Returns the new `details.changeDate` from ZITADEL so the
+ * caller can confirm the write landed.
+ *
+ * The v2 user service endpoint is technically a PUT but accepts
+ * partial bodies — only the `profile` block is sent. ZITADEL
+ * preserves email, password, and other fields across the call
+ * (verified empirically in zitadel-server#7786 and documented in
+ * v2.63+ of zitadel-server).
+ *
+ * `displayName` IS sent explicitly, set to "givenName familyName".
+ * Empirically (and contra what some docs suggest), ZITADEL does
+ * NOT recompute displayName when only the name parts change — it
+ * keeps whatever displayName was previously stored, including the
+ * one set at user creation time. That stale displayName is what
+ * ZITADEL surfaces in the OIDC `name` claim, so without this
+ * explicit write the portal session would never see the updated
+ * name (even after sign-out / sign-in).
+ *
+ * Auth: the portal's service-account PAT (ZITADEL_SA_PAT). The PAT
+ * must have user-write permission in the user's resource org.
+ * Today portal-zitadel-sa-pat already has user-write for
+ * createHumanUser etc. — same scope covers this.
+ */
+export interface UpdateHumanUserProfileResult {
+  changeDate: string;
+  /** The displayName ZITADEL stored, which the OIDC `name` claim will
+   * carry on the user's next session. */
+  displayName: string;
+}
+
+export async function updateHumanUserProfile(params: {
+  userId: string;
+  givenName: string;
+  familyName: string;
+}): Promise<UpdateHumanUserProfileResult> {
+  const path = `/v2/users/human/${encodeURIComponent(params.userId)}`;
+  // Compose the displayName ourselves so ZITADEL stores something
+  // sensible. Empty-string fallback only triggers if both name parts
+  // are blank, which the API zod schema prevents anyway.
+  const displayName =
+    `${params.givenName.trim()} ${params.familyName.trim()}`.trim();
+  type ZitadelUpdateResponse = {
+    details?: { changeDate?: string };
+  };
+  await zitadelFetch<ZitadelUpdateResponse>(path, "PUT", {
+    profile: {
+      givenName: params.givenName,
+      familyName: params.familyName,
+      displayName,
+    },
+  });
+  // Re-fetch the user to read back the canonical displayName ZITADEL
+  // committed. Should match what we sent, but reading from the source
+  // of truth catches any sanitization ZITADEL might apply.
+  const detail = await getHumanUserDetail(params.userId);
+  return {
+    changeDate: new Date().toISOString(),
+    displayName: detail.displayName || displayName,
+  };
+}
+
+/**
+ * Fetch a human user's current profile (given/family/display name +
+ * email). Used by the settings page to populate the form and by the
+ * update helper above to read back the computed displayName.
+ */
+export interface HumanUserDetail {
+  userId: string;
+  givenName: string;
+  familyName: string;
+  displayName: string;
+  email: string;
+}
+
+export async function getHumanUserDetail(
+  userId: string
+): Promise<HumanUserDetail> {
+  type ZitadelGetUserResponse = {
+    user?: {
+      userId?: string;
+      human?: {
+        profile?: {
+          givenName?: string;
+          familyName?: string;
+          displayName?: string;
+        };
+        email?: { email?: string };
+      };
+    };
+  };
+  const response = await zitadelFetch<ZitadelGetUserResponse>(
+    `/v2/users/${encodeURIComponent(userId)}`,
+    "GET"
+  );
+  const human = response.user?.human;
+  return {
+    userId: response.user?.userId ?? userId,
+    givenName: human?.profile?.givenName ?? "",
+    familyName: human?.profile?.familyName ?? "",
+    displayName: human?.profile?.displayName ?? "",
+    email: human?.email?.email ?? "",
+  };
+}

src/messages/de.json

@@ -121,7 +121,8 @@
     "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."
+    "billingNotesPlaceholderPersonal": "Was wir wissen sollten — bevorzugte Zahlungsart, Rechnungsreferenz, etc.",
+    "reviewContactPersonPrefix": "z.Hd."
   },
   "dashboard": {
     "title": "Dashboard",
@@ -393,7 +394,8 @@
     "resumeRequestTooltip": "Reaktivierungsanfrage für einen bestehenden Tenant. Bei Genehmigung wird der Tenant wieder aktiviert; keine Provisionierung läuft.",
     "openclawTool": "OpenClaw-Versionen",
     "billingTool": "Abrechnung →",
-    "skillsQueueTool": "Aktivierungs-Warteschlange"
+    "skillsQueueTool": "Aktivierungs-Warteschlange",
+    "cronTool": "Automatisierung"
   },
   "channelUsers": {
     "title": "Autorisierte Benutzer",
@@ -478,28 +480,36 @@
     "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."
+    "billingDescriptionPersonal": "Adresse und Rechnungs-E-Mail für alle Ihre Tenants.",
+    "profileTitle": "Profil",
+    "profileDescription": "Bearbeiten Sie Ihren Vor- und Nachnamen, wie er im Portal erscheint."
   },
   "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",
+    "title": "Rechnungsdaten",
+    "subtitle": "Rechnungsadresse, MWST-Nummer und Rechnungskontakt Ihres Unternehmens. Erforderlich, bevor Rechnungen für Ihre Organisation ausgestellt werden können.",
+    "companyNameLabel": "Firmenname",
+    "streetAddressLabel": "Strasse und Hausnummer",
+    "postalCodeLabel": "PLZ",
+    "cityLabel": "Ort",
+    "countryLabel": "Ländercode",
+    "countryHint": "ISO 3166-1 alpha-2 — z.B. CH, DE, AT, FR, IT, GB, US",
+    "vatNumberLabel": "MWST-Nummer (optional)",
+    "vatNumberHint": "Für Schweizer Kunden: CHE-XXX.XXX.XXX MWST. EU-Kunden mit USt-IdNr. erhalten eine Reverse-Charge-Rechnung (0% MWST).",
+    "billingEmailLabel": "Rechnungs-E-Mail",
+    "billingEmailHint": "Rechnungen und Zahlungserinnerungen werden an diese Adresse gesendet. Kann von Ihrer Konto-E-Mail abweichen.",
+    "notesLabel": "Bemerkungen (optional)",
+    "notesHint": "Referenznummern, Bestellnummern oder andere Angaben, die auf der Rechnung erscheinen sollen.",
+    "saveChanges": "Änderungen speichern",
+    "createBilling": "Rechnungsdaten speichern",
+    "saving": "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."
+    "missingRequired": "Bitte alle Pflichtfelder ausfüllen.",
+    "invalidCountry": "Ländercode muss aus 2 Buchstaben bestehen (z.B. CH).",
+    "invalidEmail": "Bitte eine gültige E-Mail-Adresse eingeben.",
+    "fullNameLabel": "Vor- und Nachname",
+    "subtitlePersonal": "Ihre Rechnungsadresse und Rechnungskontakt. Erforderlich, bevor Rechnungen ausgestellt werden können.",
+    "contactNameLabel": "Ansprechperson (optional)",
+    "contactNameHint": "Erscheint als 'z.Hd. <Name>' auf der Rechnung unter dem Firmennamen. Hilfreich für die Zuordnung in der Buchhaltung grösserer Firmen."
   },
   "support": {
     "title": "Support",
@@ -568,7 +578,7 @@
     "subtitle": "Plattform-Preise verwalten, Rechnungen generieren und den Rechnungsstatus aller Organisationen prüfen.",
     "backToAdmin": "Zurück zur Verwaltung",
     "backToBilling": "Zurück zur Abrechnung",
-    "backToInvoices": "Zurück zu den Rechnungen",
+    "backToInvoices": "Zurück zu Rechnungen",
     "totalOpenBalance": "Offener Saldo gesamt",
     "orgsWithBalance": "Organisationen mit Saldo",
     "overdueInvoices": "Überfällige Rechnungen",
@@ -663,7 +673,98 @@
     "lineItemsTitle": "Positionen",
     "billToSnapshotTitle": "Rechnungsempfänger",
     "setupFeeCol": "Einrichtungsgebühr",
-    "skillSetupFeeLabel": "Einrichtungsgebühr"
+    "skillSetupFeeLabel": "Einrichtungsgebühr",
+    "status_partially_refunded": "Teilrückerstattung",
+    "status_fully_refunded": "Vollständig rückerstattet",
+    "voidBtn": "Stornieren",
+    "voidReasonPlaceholder": "Stornierungsgrund (auf Gutschrift gedruckt)",
+    "voidReasonRequired": "Bitte einen Grund für die Stornierung angeben.",
+    "confirmVoid": "Stornierung bestätigen",
+    "voidedOnLabel": "Storniert",
+    "refundBtn": "Rückerstatten",
+    "refundReasonPlaceholder": "Grund der Rückerstattung (auf Gutschrift gedruckt)",
+    "refundReasonRequired": "Bitte einen Grund für die Rückerstattung angeben.",
+    "refundAmountInvalid": "Rückerstattungsbetrag muss eine positive Zahl sein.",
+    "refundAmountExceeds": "Rückerstattungsbetrag überschreitet den verbleibenden Betrag von CHF {max}.",
+    "refundRemainingHint": "Verbleibend erstattbar: CHF {max}",
+    "confirmRefund": "Rückerstattung bestätigen",
+    "refundedTotalLabel": "Rückerstattet",
+    "refundedRemainingLabel": "Verbleibend erstattbar",
+    "creditNotesPanelTitle": "Gutschriften",
+    "creditNoteNumberHeader": "Nummer",
+    "creditNoteKindHeader": "Typ",
+    "creditNoteAmountHeader": "Betrag",
+    "creditNoteReasonHeader": "Grund",
+    "creditNoteIssuedHeader": "Ausgestellt",
+    "creditNotePdfHeader": "PDF",
+    "creditNoteKind_void": "Storno",
+    "creditNoteKind_refund": "Rückerstattung",
+    "creditNoteNoPdf": "—",
+    "refundAmountLabel": "Betrag",
+    "refundReasonLabel": "Grund",
+    "refundAmountInclVatHint": "inkl. MWST",
+    "newInvoiceBtn": "Neue Rechnung",
+    "draftsLink": "Entwürfe",
+    "backToDrafts": "Zurück zu Entwürfen",
+    "newInvoicePageTitle": "Neue Rechnung",
+    "newInvoicePageSubtitle": "Wählen Sie den Kunden, dem Sie eine Rechnung stellen möchten. Im nächsten Schritt fügen Sie die Positionen hinzu.",
+    "newInvoiceOrgLabel": "Kunde",
+    "newInvoiceOrgPlaceholder": "— Kunde wählen —",
+    "newInvoiceOrgNoBilling": "keine Rechnungsadresse",
+    "newInvoiceOrgBillingMissing": "Dieser Kunde hat keine hinterlegte Rechnungsadresse. Bitte abschliessen lassen oder im Admin-Panel hinterlegen, bevor die Rechnung ausgestellt wird.",
+    "newInvoiceLocaleLabel": "Dokumentensprache",
+    "newInvoiceOrgRequired": "Bitte einen Kunden wählen.",
+    "newInvoiceContinueBtn": "Weiter",
+    "creating": "Wird erstellt…",
+    "draftsPageTitle": "Rechnungsentwürfe",
+    "draftsPageSubtitle": "Laufende benutzerdefinierte Rechnungen. Bearbeitung fortsetzen oder verwerfen.",
+    "draftsEmpty": "Noch keine Entwürfe. Starten Sie eine neue Rechnung.",
+    "draftOrgCol": "Kunde",
+    "draftIssueDateCol": "Rechnungsdatum",
+    "draftLinesCol": "Positionen",
+    "draftSubtotalCol": "Zwischensumme (Schätzung)",
+    "draftUpdatedCol": "Zuletzt bearbeitet",
+    "draftActionsCol": "Aktionen",
+    "draftDeleteConfirm": "Diesen Entwurf verwerfen? Kann nicht rückgängig gemacht werden.",
+    "editBtn": "Bearbeiten",
+    "editorPageTitle": "Rechnungsentwurf bearbeiten",
+    "editorBillToHeading": "Rechnungsempfänger",
+    "editorNoBillingSnapshot": "Keine Rechnungsadresse für diesen Kunden hinterlegt. Ausstellung ist nicht möglich, bis Rechnungsinformationen erfasst wurden.",
+    "editorMetadataHeading": "Rechnungsdaten",
+    "editorIssueDateLabel": "Rechnungsdatum",
+    "editorDueDateLabel": "Fälligkeitsdatum",
+    "editorLocaleLabel": "Dokumentensprache",
+    "editorPaymentMethodLabel": "Zahlungsart",
+    "editorPaymentInvoice": "Banküberweisung (Rechnung)",
+    "editorPaymentCard": "Kreditkarte (Stripe)",
+    "editorLinesHeading": "Positionen",
+    "editorLineDescription": "Beschreibung",
+    "editorLineDescriptionPlaceholder": "z.B. Beratungsstunden, individuelle Integration, …",
+    "editorLineQty": "Menge",
+    "editorLineUnitPrice": "Einzelpreis",
+    "editorLineAmount": "Betrag",
+    "editorLineRemove": "Position entfernen",
+    "editorAddLine": "Position hinzufügen",
+    "editorAddDiscount": "Rabatt hinzufügen",
+    "editorAddDiscountHint": "Fügt eine Zeile mit negativem Einzelpreis hinzu. Beschreibung und Betrag nach Bedarf anpassen.",
+    "editorRabattDefaultDescription": "Rabatt",
+    "editorNotesHeading": "Interne Notizen",
+    "editorNotesPlaceholder": "Nur für Admin sichtbar (nicht auf der Rechnung)",
+    "editorNotesHint": "Wird dem Kunden nicht angezeigt.",
+    "editorTotalsHeading": "Beträge (Schätzung)",
+    "editorSubtotal": "Zwischensumme",
+    "editorVat": "MWST",
+    "editorTotal": "Gesamt",
+    "editorTotalsEstimateNote": "Schätzung basierend auf Kundenland. Die endgültige MWST wird bei Ausstellung berechnet.",
+    "editorSaveBtn": "Entwurf speichern",
+    "editorSavedBtn": "Gespeichert",
+    "editorPreviewBtn": "PDF-Vorschau",
+    "editorIssueBtn": "Rechnung ausstellen",
+    "editorDeleteBtn": "Entwurf verwerfen",
+    "editorIssueConfirm": "Rechnung jetzt ausstellen? Eine Rechnungsnummer wird zugewiesen, das PDF wird dem Kunden zugesendet und dieser Entwurf wird entfernt.",
+    "editorDeleteConfirm": "Diesen Entwurf verwerfen? Kann nicht rückgängig gemacht werden.",
+    "previewing": "Wird geöffnet…",
+    "issuing": "Wird ausgestellt…"
   },
   "skillCostDialog": {
     "title": "Aktivierungskosten bestätigen",
@@ -736,11 +837,72 @@
       "paid": "Bezahlt",
       "overdue": "Überfällig",
       "void": "Storniert",
-      "uncollectible": "Uneinbringlich"
+      "uncollectible": "Uneinbringlich",
+      "partially_refunded": "Teilrückerstattung",
+      "fully_refunded": "Vollständig rückerstattet"
     },
     "payWithCard": "Mit Karte bezahlen",
     "redirectingToStripe": "Weiterleitung…",
-    "paymentReceived": "Zahlung erhalten — vielen Dank. Der Status wird aktualisiert, sobald Stripe bestätigt (wenige Sekunden).",
-    "paymentCancelled": "Zahlung wurde abgebrochen. Die Rechnung ist weiterhin offen; Sie können es jederzeit erneut versuchen."
+    "paymentReceived": "Zahlung erhalten — vielen Dank!",
+    "paymentCancelled": "Zahlung abgebrochen.",
+    "configureBillingCta": "Rechnungsdaten einrichten",
+    "noBillingConfigNonOwner": "Nur der Organisations-Owner kann die Rechnungsdaten einrichten. Bitte wenden Sie sich an diese Person, um diesen Schritt abzuschliessen.",
+    "creditNotesHeading": "Gutschriften",
+    "creditNoteNumberCol": "Gutschrift",
+    "creditNoteInvoiceCol": "Rechnung",
+    "creditNoteIssuedCol": "Ausgestellt",
+    "creditNoteAmountCol": "Betrag",
+    "creditNoteKindCol": "Typ",
+    "creditNotePdfCol": "PDF",
+    "creditNoteKind_void": "Storno",
+    "creditNoteKind_refund": "Rückerstattung",
+    "creditNoteNoPdf": "PDF nicht verfügbar"
+  },
+  "adminCron": {
+    "title": "Abrechnungsautomatisierung",
+    "subtitle": "Monatliche Rechnungsstellung und tägliche Mahnungsläufe. Beides läuft automatisch; mit den Schaltflächen unten können Sie einen Lauf manuell auslösen.",
+    "monthlyIssue": "Monatliche Rechnungsstellung",
+    "reminders": "Mahnungen",
+    "scheduleIssueLabel": "Zeitplan",
+    "scheduleIssueValue": "00:30 Europe/Zurich am 1.",
+    "scheduleReminderLabel": "Zeitplan",
+    "scheduleReminderValue": "09:00 Europe/Zurich täglich",
+    "lastSuccess": "Letzter Erfolg",
+    "never": "nie",
+    "runIssueNow": "Letzten Monat jetzt abrechnen",
+    "runRemindersNow": "Mahnungslauf jetzt starten",
+    "running": "Läuft…",
+    "flashIssueOk": "Rechnungsstellung abgeschlossen: {success} Rechnungen erstellt, {skipped} übersprungen, {failure} fehlgeschlagen.",
+    "flashRemindersOk": "Mahnungen versendet: {success} erfolgreich, {skipped} übersprungen, {failure} fehlgeschlagen.",
+    "recentRuns": "Letzte Läufe (max. 30)",
+    "noRunsYet": "Noch keine Automatisierungsläufe erfasst.",
+    "startedCol": "Gestartet",
+    "kindCol": "Art",
+    "triggeredByCol": "Ausgelöst von",
+    "okCol": "OK",
+    "skipCol": "Übersprungen",
+    "failCol": "Fehler",
+    "triggeredByCron": "Cron",
+    "kind": {
+      "monthly_issue": "Rechnungsstellung",
+      "reminders": "Mahnungen"
+    },
+    "failureBannerTitle": "Fehler in jüngsten Automatisierungsläufen",
+    "failureBannerBody": "{count} Lauf/Läufe im aktuellen Fenster haben mindestens einen Fehler gemeldet. Bitte die Tabelle unten prüfen — betroffene Zeilen sind rot hervorgehoben."
+  },
+  "settingsProfile": {
+    "title": "Profil",
+    "subtitle": "Ihr Anzeigename, der im Portal, in Tenant-Anfragen und in Support-Tickets erscheint.",
+    "subtitlePersonal": "Ihr Anzeigename, der im Portal erscheint. Um Ihren Namen auf Rechnungen zu ändern, bearbeiten Sie ihn unter Rechnungsdaten.",
+    "firstNameLabel": "Vorname",
+    "lastNameLabel": "Nachname",
+    "emailLabel": "E-Mail",
+    "emailReadOnlyHint": "Die E-Mail-Adresse kann hier nicht geändert werden. Verwenden Sie die Selbstbedienungseinstellungen Ihres Identitätsanbieters.",
+    "personalAccountHint": "Dies ist ein persönliches Konto. Eine Änderung Ihres Namens hier ändert NICHT, wie Ihr Name auf Rechnungen erscheint — bearbeiten Sie diesen separat unter Rechnungsdaten.",
+    "companyAccountHint": "Sie sind als Mitglied von {orgName} angemeldet.",
+    "saveChanges": "Änderungen speichern",
+    "saving": "Speichern…",
+    "saved": "Gespeichert.",
+    "missingRequired": "Vor- und Nachname sind erforderlich."
   }
 }

src/messages/en.json

@@ -121,7 +121,8 @@
     "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."
+    "billingNotesPlaceholderPersonal": "Anything we should know — preferred payment method, billing reference, etc.",
+    "reviewContactPersonPrefix": "Attn:"
   },
   "dashboard": {
     "title": "Dashboard",
@@ -393,7 +394,8 @@
     "resumeRequestTooltip": "Reactivation request for an existing tenant. Approving will un-suspend the tenant; no provisioning runs.",
     "openclawTool": "OpenClaw versions",
     "billingTool": "Billing →",
-    "skillsQueueTool": "Activation Queue"
+    "skillsQueueTool": "Activation Queue",
+    "cronTool": "Automation"
   },
   "channelUsers": {
     "title": "Authorized Users",
@@ -478,28 +480,36 @@
     "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."
+    "billingDescriptionPersonal": "Address and invoice email used for all your tenants.",
+    "profileTitle": "Profile",
+    "profileDescription": "Edit your first and last name as shown across the portal."
   },
   "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",
+    "title": "Billing details",
+    "subtitle": "Your company's billing address, VAT number, and invoice contact. Required before invoices can be issued for your organization.",
+    "companyNameLabel": "Company name",
+    "streetAddressLabel": "Street address",
+    "postalCodeLabel": "Postal code",
+    "cityLabel": "City",
+    "countryLabel": "Country code",
+    "countryHint": "ISO 3166-1 alpha-2 — e.g. CH, DE, AT, FR, IT, GB, US",
+    "vatNumberLabel": "VAT number (optional)",
+    "vatNumberHint": "For Swiss customers: CHE-XXX.XXX.XXX MWST. EU customers with a VAT number get a 0% reverse-charge invoice.",
+    "billingEmailLabel": "Billing email",
+    "billingEmailHint": "Invoices and payment reminders are sent here. Can differ from your account email.",
+    "notesLabel": "Notes (optional)",
+    "notesHint": "Reference numbers, purchase order tags, or anything else you'd like printed on invoices.",
+    "saveChanges": "Save changes",
+    "createBilling": "Save billing details",
+    "saving": "Saving…",
     "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."
+    "missingRequired": "Please fill in all required fields.",
+    "invalidCountry": "Country code must be 2 letters (e.g. CH).",
+    "invalidEmail": "Please enter a valid email address.",
+    "fullNameLabel": "Full name",
+    "subtitlePersonal": "Your billing address and invoice contact. Required before invoices can be issued.",
+    "contactNameLabel": "Contact person (optional)",
+    "contactNameHint": "Prints as 'Attn: <name>' on the invoice below the company name. Useful for AP routing in larger organizations."
   },
   "support": {
     "title": "Support",
@@ -567,8 +577,8 @@
     "title": "Billing administration",
     "subtitle": "Manage platform pricing, generate invoices, and review billing status across all organizations.",
     "backToAdmin": "Back to Admin",
-    "backToBilling": "Back to Billing",
-    "backToInvoices": "Back to Invoices",
+    "backToBilling": "Back to billing",
+    "backToInvoices": "Back to invoices",
     "totalOpenBalance": "Total open balance",
     "orgsWithBalance": "Orgs with balance",
     "overdueInvoices": "Overdue invoices",
@@ -663,7 +673,98 @@
     "lineItemsTitle": "Line items",
     "billToSnapshotTitle": "Billed to",
     "setupFeeCol": "Setup fee",
-    "skillSetupFeeLabel": "Setup fee"
+    "skillSetupFeeLabel": "Setup fee",
+    "status_partially_refunded": "Partially refunded",
+    "status_fully_refunded": "Fully refunded",
+    "voidBtn": "Void",
+    "voidReasonPlaceholder": "Reason for voiding (printed on credit note)",
+    "voidReasonRequired": "Please provide a reason for voiding.",
+    "confirmVoid": "Confirm void",
+    "voidedOnLabel": "Voided",
+    "refundBtn": "Refund",
+    "refundReasonPlaceholder": "Reason for refund (printed on credit note)",
+    "refundReasonRequired": "Please provide a reason for the refund.",
+    "refundAmountInvalid": "Refund amount must be a positive number.",
+    "refundAmountExceeds": "Refund amount exceeds remaining refundable CHF {max}.",
+    "refundRemainingHint": "Remaining refundable: CHF {max}",
+    "confirmRefund": "Confirm refund",
+    "refundedTotalLabel": "Refunded total",
+    "refundedRemainingLabel": "Remaining refundable",
+    "creditNotesPanelTitle": "Credit notes",
+    "creditNoteNumberHeader": "Number",
+    "creditNoteKindHeader": "Type",
+    "creditNoteAmountHeader": "Amount",
+    "creditNoteReasonHeader": "Reason",
+    "creditNoteIssuedHeader": "Issued",
+    "creditNotePdfHeader": "PDF",
+    "creditNoteKind_void": "Void",
+    "creditNoteKind_refund": "Refund",
+    "creditNoteNoPdf": "—",
+    "refundAmountLabel": "Amount",
+    "refundReasonLabel": "Reason",
+    "refundAmountInclVatHint": "incl. VAT",
+    "newInvoiceBtn": "New invoice",
+    "draftsLink": "Drafts",
+    "backToDrafts": "Back to drafts",
+    "newInvoicePageTitle": "New invoice",
+    "newInvoicePageSubtitle": "Pick the customer you want to invoice. You'll add lines on the next step.",
+    "newInvoiceOrgLabel": "Customer",
+    "newInvoiceOrgPlaceholder": "— select customer —",
+    "newInvoiceOrgNoBilling": "no billing info",
+    "newInvoiceOrgBillingMissing": "This customer has no billing address on file. Ask them to complete onboarding or set the billing info from the admin panel before issuing.",
+    "newInvoiceLocaleLabel": "Document language",
+    "newInvoiceOrgRequired": "Please select a customer.",
+    "newInvoiceContinueBtn": "Continue",
+    "creating": "Creating…",
+    "draftsPageTitle": "Invoice drafts",
+    "draftsPageSubtitle": "Custom invoices in progress. Resume editing or discard.",
+    "draftsEmpty": "No drafts yet. Start a new invoice to begin.",
+    "draftOrgCol": "Customer",
+    "draftIssueDateCol": "Issue date",
+    "draftLinesCol": "Lines",
+    "draftSubtotalCol": "Subtotal (est.)",
+    "draftUpdatedCol": "Last edited",
+    "draftActionsCol": "Actions",
+    "draftDeleteConfirm": "Discard this draft? This cannot be undone.",
+    "editBtn": "Edit",
+    "editorPageTitle": "Edit invoice draft",
+    "editorBillToHeading": "Bill to",
+    "editorNoBillingSnapshot": "No billing address on file for this customer. Issuance will fail until billing info is set.",
+    "editorMetadataHeading": "Invoice details",
+    "editorIssueDateLabel": "Issue date",
+    "editorDueDateLabel": "Due date",
+    "editorLocaleLabel": "Document language",
+    "editorPaymentMethodLabel": "Payment method",
+    "editorPaymentInvoice": "Bank transfer (invoice)",
+    "editorPaymentCard": "Credit card (Stripe)",
+    "editorLinesHeading": "Line items",
+    "editorLineDescription": "Description",
+    "editorLineDescriptionPlaceholder": "e.g. Consulting hours, custom integration, …",
+    "editorLineQty": "Qty",
+    "editorLineUnitPrice": "Unit price",
+    "editorLineAmount": "Amount",
+    "editorLineRemove": "Remove line",
+    "editorAddLine": "Add line",
+    "editorAddDiscount": "Add discount",
+    "editorAddDiscountHint": "Adds a line with negative unit price. Edit description and amount as needed.",
+    "editorRabattDefaultDescription": "Discount",
+    "editorNotesHeading": "Internal notes",
+    "editorNotesPlaceholder": "Notes only visible to admin (not on the invoice PDF)",
+    "editorNotesHint": "Not shown to the customer.",
+    "editorTotalsHeading": "Totals (estimate)",
+    "editorSubtotal": "Subtotal",
+    "editorVat": "VAT",
+    "editorTotal": "Total",
+    "editorTotalsEstimateNote": "Estimate based on customer country. Final VAT is computed at issuance.",
+    "editorSaveBtn": "Save draft",
+    "editorSavedBtn": "Saved",
+    "editorPreviewBtn": "Preview PDF",
+    "editorIssueBtn": "Issue invoice",
+    "editorDeleteBtn": "Discard draft",
+    "editorIssueConfirm": "Issue this invoice now? An invoice number will be allocated, the PDF will be sent to the customer, and this draft will be removed.",
+    "editorDeleteConfirm": "Discard this draft? This cannot be undone.",
+    "previewing": "Opening…",
+    "issuing": "Issuing…"
   },
   "skillCostDialog": {
     "title": "Confirm activation cost",
@@ -736,11 +837,72 @@
       "paid": "Paid",
       "overdue": "Overdue",
       "void": "Void",
-      "uncollectible": "Uncollectible"
+      "uncollectible": "Uncollectible",
+      "partially_refunded": "Partially refunded",
+      "fully_refunded": "Fully refunded"
     },
     "payWithCard": "Pay with card",
     "redirectingToStripe": "Redirecting…",
-    "paymentReceived": "Payment received — thank you. The status will update once Stripe confirms (a few seconds).",
-    "paymentCancelled": "Payment was cancelled. The invoice is still open; you can try again whenever."
+    "paymentReceived": "Payment received — thank you!",
+    "paymentCancelled": "Payment cancelled.",
+    "configureBillingCta": "Configure billing details",
+    "noBillingConfigNonOwner": "Only the organization owner can configure billing details. Please contact them to complete this step.",
+    "creditNotesHeading": "Credit notes",
+    "creditNoteNumberCol": "Credit note",
+    "creditNoteInvoiceCol": "Invoice",
+    "creditNoteIssuedCol": "Issued",
+    "creditNoteAmountCol": "Amount",
+    "creditNoteKindCol": "Type",
+    "creditNotePdfCol": "PDF",
+    "creditNoteKind_void": "Void",
+    "creditNoteKind_refund": "Refund",
+    "creditNoteNoPdf": "PDF unavailable"
+  },
+  "adminCron": {
+    "title": "Billing automation",
+    "subtitle": "Monthly issuance and daily reminder sweeps. Both run automatically; use the buttons below to trigger a sweep on demand.",
+    "monthlyIssue": "Monthly issuance",
+    "reminders": "Reminders",
+    "scheduleIssueLabel": "Schedule",
+    "scheduleIssueValue": "00:30 Europe/Zurich on the 1st",
+    "scheduleReminderLabel": "Schedule",
+    "scheduleReminderValue": "09:00 Europe/Zurich daily",
+    "lastSuccess": "Last success",
+    "never": "never",
+    "runIssueNow": "Run last month's issuance now",
+    "runRemindersNow": "Run reminder sweep now",
+    "running": "Running…",
+    "flashIssueOk": "Issuance complete: {success} invoices issued, {skipped} skipped, {failure} failed.",
+    "flashRemindersOk": "Reminders sent: {success} succeeded, {skipped} skipped, {failure} failed.",
+    "recentRuns": "Recent runs (last 30)",
+    "noRunsYet": "No automation runs recorded yet.",
+    "startedCol": "Started",
+    "kindCol": "Kind",
+    "triggeredByCol": "Triggered by",
+    "okCol": "OK",
+    "skipCol": "Skipped",
+    "failCol": "Failed",
+    "triggeredByCron": "cron",
+    "kind": {
+      "monthly_issue": "Issuance",
+      "reminders": "Reminders"
+    },
+    "failureBannerTitle": "Recent automation failures detected",
+    "failureBannerBody": "{count} run(s) in the recent window reported at least one failure. Review the table below — the affected rows are highlighted in red."
+  },
+  "settingsProfile": {
+    "title": "Profile",
+    "subtitle": "Your display name as shown across the portal, in tenant requests, and in support tickets.",
+    "subtitlePersonal": "Your display name as shown across the portal. To change how your name appears on invoices, edit it in Billing details.",
+    "firstNameLabel": "First name",
+    "lastNameLabel": "Last name",
+    "emailLabel": "Email",
+    "emailReadOnlyHint": "Email can't be changed here. Use your identity provider's self-service settings to change your email.",
+    "personalAccountHint": "This is a personal account. Changing your name here does NOT update how your name appears on invoices — edit that separately in Billing details.",
+    "companyAccountHint": "You're signed in as a member of {orgName}.",
+    "saveChanges": "Save changes",
+    "saving": "Saving…",
+    "saved": "Saved.",
+    "missingRequired": "First and last name are required."
   }
 }

src/messages/fr.json

@@ -121,7 +121,8 @@
     "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."
+    "billingNotesPlaceholderPersonal": "Tout ce que nous devons savoir — moyen de paiement préféré, référence de facturation, etc.",
+    "reviewContactPersonPrefix": "À l'attention de"
   },
   "dashboard": {
     "title": "Tableau de bord",
@@ -393,7 +394,8 @@
     "resumeRequestTooltip": "Demande de réactivation d'un locataire existant. L'approbation le réactivera ; aucun provisionnement ne s'exécute.",
     "openclawTool": "Versions OpenClaw",
     "billingTool": "Facturation →",
-    "skillsQueueTool": "File d'activation"
+    "skillsQueueTool": "File d'activation",
+    "cronTool": "Automatisation"
   },
   "channelUsers": {
     "title": "Utilisateurs autorisés",
@@ -478,28 +480,36 @@
     "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."
+    "billingDescriptionPersonal": "Adresse et e-mail de facturation utilisés pour tous vos locataires.",
+    "profileTitle": "Profil",
+    "profileDescription": "Modifiez votre prénom et nom tels qu'ils apparaissent dans le portail."
   },
   "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",
+    "title": "Informations de facturation",
+    "subtitle": "Adresse de facturation, numéro de TVA et contact pour les factures. Requis avant l'émission de toute facture pour votre organisation.",
+    "companyNameLabel": "Nom de l'entreprise",
+    "streetAddressLabel": "Adresse",
+    "postalCodeLabel": "Code postal",
+    "cityLabel": "Ville",
+    "countryLabel": "Code pays",
+    "countryHint": "ISO 3166-1 alpha-2 — p. ex. CH, DE, AT, FR, IT, GB, US",
+    "vatNumberLabel": "Numéro de TVA (facultatif)",
+    "vatNumberHint": "Pour les clients suisses : CHE-XXX.XXX.XXX TVA. Les clients UE avec un n° de TVA reçoivent une facture à 0% (autoliquidation).",
+    "billingEmailLabel": "E-mail de facturation",
+    "billingEmailHint": "Les factures et rappels de paiement sont envoyés à cette adresse. Peut différer de l'e-mail du compte.",
+    "notesLabel": "Notes (facultatif)",
+    "notesHint": "Numéros de référence, bons de commande, ou toute autre information à imprimer sur les factures.",
+    "saveChanges": "Enregistrer les modifications",
+    "createBilling": "Enregistrer les informations",
+    "saving": "Enregistrement…",
     "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."
+    "missingRequired": "Veuillez remplir tous les champs obligatoires.",
+    "invalidCountry": "Le code pays doit comporter 2 lettres (p. ex. CH).",
+    "invalidEmail": "Veuillez saisir une adresse e-mail valide.",
+    "fullNameLabel": "Nom et prénom",
+    "subtitlePersonal": "Votre adresse de facturation et votre contact. Requis avant l'émission de toute facture.",
+    "contactNameLabel": "Personne à contacter (facultatif)",
+    "contactNameHint": "S'imprime « À l'attention de <nom> » sur la facture, sous le nom de l'entreprise. Utile pour le routage en comptabilité dans les grandes organisations."
   },
   "support": {
     "title": "Support",
@@ -663,7 +673,98 @@
     "lineItemsTitle": "Lignes",
     "billToSnapshotTitle": "Destinataire",
     "setupFeeCol": "Frais de configuration",
-    "skillSetupFeeLabel": "Frais de configuration"
+    "skillSetupFeeLabel": "Frais de configuration",
+    "status_partially_refunded": "Partiellement remboursée",
+    "status_fully_refunded": "Entièrement remboursée",
+    "voidBtn": "Annuler",
+    "voidReasonPlaceholder": "Motif de l'annulation (imprimé sur la note de crédit)",
+    "voidReasonRequired": "Veuillez indiquer un motif d'annulation.",
+    "confirmVoid": "Confirmer l'annulation",
+    "voidedOnLabel": "Annulée",
+    "refundBtn": "Rembourser",
+    "refundReasonPlaceholder": "Motif du remboursement (imprimé sur la note de crédit)",
+    "refundReasonRequired": "Veuillez indiquer un motif de remboursement.",
+    "refundAmountInvalid": "Le montant du remboursement doit être un nombre positif.",
+    "refundAmountExceeds": "Le montant dépasse le restant remboursable de CHF {max}.",
+    "refundRemainingHint": "Restant remboursable : CHF {max}",
+    "confirmRefund": "Confirmer le remboursement",
+    "refundedTotalLabel": "Remboursé",
+    "refundedRemainingLabel": "Restant remboursable",
+    "creditNotesPanelTitle": "Notes de crédit",
+    "creditNoteNumberHeader": "Numéro",
+    "creditNoteKindHeader": "Type",
+    "creditNoteAmountHeader": "Montant",
+    "creditNoteReasonHeader": "Motif",
+    "creditNoteIssuedHeader": "Émise",
+    "creditNotePdfHeader": "PDF",
+    "creditNoteKind_void": "Annulation",
+    "creditNoteKind_refund": "Remboursement",
+    "creditNoteNoPdf": "—",
+    "refundAmountLabel": "Montant",
+    "refundReasonLabel": "Motif",
+    "refundAmountInclVatHint": "TVA incluse",
+    "newInvoiceBtn": "Nouvelle facture",
+    "draftsLink": "Brouillons",
+    "backToDrafts": "Retour aux brouillons",
+    "newInvoicePageTitle": "Nouvelle facture",
+    "newInvoicePageSubtitle": "Choisissez le client à facturer. Vous ajouterez les lignes à l'étape suivante.",
+    "newInvoiceOrgLabel": "Client",
+    "newInvoiceOrgPlaceholder": "— sélectionner un client —",
+    "newInvoiceOrgNoBilling": "pas d'adresse de facturation",
+    "newInvoiceOrgBillingMissing": "Ce client n'a pas d'adresse de facturation. Demandez-lui de compléter l'inscription ou renseignez-la depuis le panneau d'administration avant d'émettre.",
+    "newInvoiceLocaleLabel": "Langue du document",
+    "newInvoiceOrgRequired": "Veuillez sélectionner un client.",
+    "newInvoiceContinueBtn": "Continuer",
+    "creating": "Création…",
+    "draftsPageTitle": "Brouillons de factures",
+    "draftsPageSubtitle": "Factures personnalisées en cours. Reprenez l'édition ou supprimez.",
+    "draftsEmpty": "Aucun brouillon pour le moment. Démarrez une nouvelle facture.",
+    "draftOrgCol": "Client",
+    "draftIssueDateCol": "Date d'émission",
+    "draftLinesCol": "Lignes",
+    "draftSubtotalCol": "Sous-total (est.)",
+    "draftUpdatedCol": "Modifié",
+    "draftActionsCol": "Actions",
+    "draftDeleteConfirm": "Supprimer ce brouillon ? Cette action est irréversible.",
+    "editBtn": "Modifier",
+    "editorPageTitle": "Modifier le brouillon de facture",
+    "editorBillToHeading": "Destinataire",
+    "editorNoBillingSnapshot": "Aucune adresse de facturation pour ce client. L'émission échouera tant que les informations de facturation ne sont pas renseignées.",
+    "editorMetadataHeading": "Détails de la facture",
+    "editorIssueDateLabel": "Date d'émission",
+    "editorDueDateLabel": "Date d'échéance",
+    "editorLocaleLabel": "Langue du document",
+    "editorPaymentMethodLabel": "Mode de paiement",
+    "editorPaymentInvoice": "Virement (facture)",
+    "editorPaymentCard": "Carte bancaire (Stripe)",
+    "editorLinesHeading": "Lignes",
+    "editorLineDescription": "Description",
+    "editorLineDescriptionPlaceholder": "p.ex. Heures de conseil, intégration sur mesure, …",
+    "editorLineQty": "Qté",
+    "editorLineUnitPrice": "Prix unitaire",
+    "editorLineAmount": "Montant",
+    "editorLineRemove": "Supprimer la ligne",
+    "editorAddLine": "Ajouter une ligne",
+    "editorAddDiscount": "Ajouter une remise",
+    "editorAddDiscountHint": "Ajoute une ligne avec un prix unitaire négatif. Modifiez la description et le montant si nécessaire.",
+    "editorRabattDefaultDescription": "Remise",
+    "editorNotesHeading": "Notes internes",
+    "editorNotesPlaceholder": "Notes visibles uniquement par l'administrateur (pas sur le PDF)",
+    "editorNotesHint": "Non visible par le client.",
+    "editorTotalsHeading": "Totaux (estimation)",
+    "editorSubtotal": "Sous-total",
+    "editorVat": "TVA",
+    "editorTotal": "Total",
+    "editorTotalsEstimateNote": "Estimation basée sur le pays du client. La TVA finale est calculée à l'émission.",
+    "editorSaveBtn": "Enregistrer le brouillon",
+    "editorSavedBtn": "Enregistré",
+    "editorPreviewBtn": "Aperçu PDF",
+    "editorIssueBtn": "Émettre la facture",
+    "editorDeleteBtn": "Supprimer le brouillon",
+    "editorIssueConfirm": "Émettre cette facture maintenant ? Un numéro de facture sera attribué, le PDF sera envoyé au client et ce brouillon sera supprimé.",
+    "editorDeleteConfirm": "Supprimer ce brouillon ? Cette action est irréversible.",
+    "previewing": "Ouverture…",
+    "issuing": "Émission…"
   },
   "skillCostDialog": {
     "title": "Confirmer le coût d'activation",
@@ -729,18 +830,79 @@
     "subtotalLabel": "Sous-total",
     "vatLabel": "TVA ({rate}%)",
     "totalLabel": "Total",
-    "downloadPdf": "Télécharger le PDF",
+    "downloadPdf": "Télécharger PDF",
     "status": {
       "draft": "Brouillon",
       "open": "Ouverte",
       "paid": "Payée",
       "overdue": "En retard",
       "void": "Annulée",
-      "uncollectible": "Irrécouvrable"
+      "uncollectible": "Irrécouvrable",
+      "partially_refunded": "Partiellement remboursée",
+      "fully_refunded": "Entièrement remboursée"
     },
     "payWithCard": "Payer par carte",
     "redirectingToStripe": "Redirection…",
-    "paymentReceived": "Paiement reçu — merci. Le statut sera mis à jour dès la confirmation de Stripe (quelques secondes).",
-    "paymentCancelled": "Le paiement a été annulé. La facture reste ouverte ; vous pouvez réessayer à tout moment."
+    "paymentReceived": "Paiement reçu — merci !",
+    "paymentCancelled": "Paiement annulé.",
+    "configureBillingCta": "Configurer les informations de facturation",
+    "noBillingConfigNonOwner": "Seul le propriétaire de l'organisation peut configurer les informations de facturation. Veuillez le contacter pour terminer cette étape.",
+    "creditNotesHeading": "Notes de crédit",
+    "creditNoteNumberCol": "Note de crédit",
+    "creditNoteInvoiceCol": "Facture",
+    "creditNoteIssuedCol": "Émise",
+    "creditNoteAmountCol": "Montant",
+    "creditNoteKindCol": "Type",
+    "creditNotePdfCol": "PDF",
+    "creditNoteKind_void": "Annulation",
+    "creditNoteKind_refund": "Remboursement",
+    "creditNoteNoPdf": "PDF indisponible"
+  },
+  "adminCron": {
+    "title": "Automatisation de la facturation",
+    "subtitle": "Émission mensuelle et balayage quotidien des rappels. Les deux s'exécutent automatiquement ; utilisez les boutons ci-dessous pour déclencher un lancement à la demande.",
+    "monthlyIssue": "Émission mensuelle",
+    "reminders": "Rappels",
+    "scheduleIssueLabel": "Planning",
+    "scheduleIssueValue": "00:30 Europe/Zurich le 1er",
+    "scheduleReminderLabel": "Planning",
+    "scheduleReminderValue": "09:00 Europe/Zurich quotidien",
+    "lastSuccess": "Dernière réussite",
+    "never": "jamais",
+    "runIssueNow": "Facturer le mois dernier maintenant",
+    "runRemindersNow": "Lancer les rappels maintenant",
+    "running": "En cours…",
+    "flashIssueOk": "Émission terminée : {success} factures émises, {skipped} ignorées, {failure} échouées.",
+    "flashRemindersOk": "Rappels envoyés : {success} réussis, {skipped} ignorés, {failure} échoués.",
+    "recentRuns": "Lancements récents (30 derniers)",
+    "noRunsYet": "Aucun lancement automatique enregistré pour le moment.",
+    "startedCol": "Démarré",
+    "kindCol": "Type",
+    "triggeredByCol": "Déclenché par",
+    "okCol": "OK",
+    "skipCol": "Ignorés",
+    "failCol": "Échoués",
+    "triggeredByCron": "cron",
+    "kind": {
+      "monthly_issue": "Émission",
+      "reminders": "Rappels"
+    },
+    "failureBannerTitle": "Échecs récents détectés",
+    "failureBannerBody": "{count} lancement(s) récent(s) ont signalé au moins un échec. Consultez le tableau ci-dessous — les lignes concernées sont en rouge."
+  },
+  "settingsProfile": {
+    "title": "Profil",
+    "subtitle": "Votre nom d'affichage tel qu'il apparaît dans le portail, les demandes de tenant et les tickets d'assistance.",
+    "subtitlePersonal": "Votre nom d'affichage tel qu'il apparaît dans le portail. Pour modifier votre nom sur les factures, modifiez-le dans Informations de facturation.",
+    "firstNameLabel": "Prénom",
+    "lastNameLabel": "Nom",
+    "emailLabel": "E-mail",
+    "emailReadOnlyHint": "L'e-mail ne peut pas être modifié ici. Utilisez les paramètres en libre-service de votre fournisseur d'identité.",
+    "personalAccountHint": "Ceci est un compte personnel. Modifier votre nom ici ne change PAS la façon dont votre nom apparaît sur les factures — modifiez-le séparément dans Informations de facturation.",
+    "companyAccountHint": "Vous êtes connecté en tant que membre de {orgName}.",
+    "saveChanges": "Enregistrer les modifications",
+    "saving": "Enregistrement…",
+    "saved": "Enregistré.",
+    "missingRequired": "Le prénom et le nom sont obligatoires."
   }
 }

src/messages/it.json

@@ -121,7 +121,8 @@
     "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."
+    "billingNotesPlaceholderPersonal": "Qualsiasi cosa dovremmo sapere — metodo di pagamento preferito, riferimento per fatturazione, ecc.",
+    "reviewContactPersonPrefix": "c.a."
   },
   "dashboard": {
     "title": "Dashboard",
@@ -393,7 +394,8 @@
     "resumeRequestTooltip": "Richiesta di riattivazione di un tenant esistente. L'approvazione lo riattiverà; non viene eseguito alcun provisioning.",
     "openclawTool": "Versioni OpenClaw",
     "billingTool": "Fatturazione →",
-    "skillsQueueTool": "Coda di attivazione"
+    "skillsQueueTool": "Coda di attivazione",
+    "cronTool": "Automazione"
   },
   "channelUsers": {
     "title": "Utenti autorizzati",
@@ -478,28 +480,36 @@
     "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."
+    "billingDescriptionPersonal": "Indirizzo ed e-mail di fatturazione usati per tutti i tuoi tenant.",
+    "profileTitle": "Profilo",
+    "profileDescription": "Modifica il tuo nome e cognome come appaiono nel portale."
   },
   "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",
+    "title": "Dati di fatturazione",
+    "subtitle": "Indirizzo di fatturazione, partita IVA e contatto fatture della tua azienda. Necessari prima che possano essere emesse fatture per la tua organizzazione.",
+    "companyNameLabel": "Nome azienda",
+    "streetAddressLabel": "Indirizzo",
+    "postalCodeLabel": "CAP",
+    "cityLabel": "Città",
+    "countryLabel": "Codice paese",
+    "countryHint": "ISO 3166-1 alpha-2 — es. CH, DE, AT, FR, IT, GB, US",
+    "vatNumberLabel": "Partita IVA (facoltativa)",
+    "vatNumberHint": "Per clienti svizzeri: CHE-XXX.XXX.XXX IVA. Clienti UE con partita IVA ricevono fattura in reverse charge (0% IVA).",
+    "billingEmailLabel": "E-mail di fatturazione",
+    "billingEmailHint": "Le fatture e i solleciti vengono inviati a questo indirizzo. Può differire dall'e-mail dell'account.",
+    "notesLabel": "Note (facoltative)",
+    "notesHint": "Numeri di riferimento, ordini d'acquisto o altre informazioni da riportare in fattura.",
+    "saveChanges": "Salva modifiche",
+    "createBilling": "Salva dati di fatturazione",
+    "saving": "Salvataggio…",
     "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."
+    "missingRequired": "Compila tutti i campi obbligatori.",
+    "invalidCountry": "Il codice paese deve essere di 2 lettere (es. CH).",
+    "invalidEmail": "Inserisci un indirizzo e-mail valido.",
+    "fullNameLabel": "Nome e cognome",
+    "subtitlePersonal": "Il tuo indirizzo di fatturazione e contatto. Necessari prima che possano essere emesse fatture.",
+    "contactNameLabel": "Persona di contatto (facoltativa)",
+    "contactNameHint": "Stampato come 'c.a. <nome>' sulla fattura, sotto il nome dell'azienda. Utile per l'instradamento contabile in grandi organizzazioni."
   },
   "support": {
     "title": "Supporto",
@@ -663,7 +673,98 @@
     "lineItemsTitle": "Righe",
     "billToSnapshotTitle": "Destinatario",
     "setupFeeCol": "Spese di attivazione",
-    "skillSetupFeeLabel": "Spese di attivazione"
+    "skillSetupFeeLabel": "Spese di attivazione",
+    "status_partially_refunded": "Rimborsata parzialmente",
+    "status_fully_refunded": "Rimborsata integralmente",
+    "voidBtn": "Annulla",
+    "voidReasonPlaceholder": "Motivo dell'annullamento (stampato sulla nota di credito)",
+    "voidReasonRequired": "Indicare un motivo per l'annullamento.",
+    "confirmVoid": "Conferma annullamento",
+    "voidedOnLabel": "Annullata",
+    "refundBtn": "Rimborsa",
+    "refundReasonPlaceholder": "Motivo del rimborso (stampato sulla nota di credito)",
+    "refundReasonRequired": "Indicare un motivo per il rimborso.",
+    "refundAmountInvalid": "L'importo del rimborso deve essere un numero positivo.",
+    "refundAmountExceeds": "L'importo supera il residuo rimborsabile di CHF {max}.",
+    "refundRemainingHint": "Residuo rimborsabile: CHF {max}",
+    "confirmRefund": "Conferma rimborso",
+    "refundedTotalLabel": "Rimborsato",
+    "refundedRemainingLabel": "Residuo rimborsabile",
+    "creditNotesPanelTitle": "Note di credito",
+    "creditNoteNumberHeader": "Numero",
+    "creditNoteKindHeader": "Tipo",
+    "creditNoteAmountHeader": "Importo",
+    "creditNoteReasonHeader": "Motivo",
+    "creditNoteIssuedHeader": "Emessa",
+    "creditNotePdfHeader": "PDF",
+    "creditNoteKind_void": "Annullamento",
+    "creditNoteKind_refund": "Rimborso",
+    "creditNoteNoPdf": "—",
+    "refundAmountLabel": "Importo",
+    "refundReasonLabel": "Motivo",
+    "refundAmountInclVatHint": "IVA inclusa",
+    "newInvoiceBtn": "Nuova fattura",
+    "draftsLink": "Bozze",
+    "backToDrafts": "Torna alle bozze",
+    "newInvoicePageTitle": "Nuova fattura",
+    "newInvoicePageSubtitle": "Scegli il cliente da fatturare. Aggiungerai le righe nel passaggio successivo.",
+    "newInvoiceOrgLabel": "Cliente",
+    "newInvoiceOrgPlaceholder": "— seleziona cliente —",
+    "newInvoiceOrgNoBilling": "nessun indirizzo di fatturazione",
+    "newInvoiceOrgBillingMissing": "Questo cliente non ha un indirizzo di fatturazione registrato. Chiedi al cliente di completare l'onboarding o imposta i dati dal pannello admin prima di emettere.",
+    "newInvoiceLocaleLabel": "Lingua del documento",
+    "newInvoiceOrgRequired": "Selezionare un cliente.",
+    "newInvoiceContinueBtn": "Continua",
+    "creating": "Creazione…",
+    "draftsPageTitle": "Bozze di fatture",
+    "draftsPageSubtitle": "Fatture personalizzate in corso. Riprendi la modifica o scarta.",
+    "draftsEmpty": "Ancora nessuna bozza. Inizia una nuova fattura.",
+    "draftOrgCol": "Cliente",
+    "draftIssueDateCol": "Data emissione",
+    "draftLinesCol": "Righe",
+    "draftSubtotalCol": "Subtotale (stima)",
+    "draftUpdatedCol": "Modificato",
+    "draftActionsCol": "Azioni",
+    "draftDeleteConfirm": "Scartare questa bozza? Operazione irreversibile.",
+    "editBtn": "Modifica",
+    "editorPageTitle": "Modifica bozza di fattura",
+    "editorBillToHeading": "Destinatario",
+    "editorNoBillingSnapshot": "Nessun indirizzo di fatturazione per questo cliente. L'emissione fallirà finché i dati di fatturazione non saranno impostati.",
+    "editorMetadataHeading": "Dettagli fattura",
+    "editorIssueDateLabel": "Data emissione",
+    "editorDueDateLabel": "Data scadenza",
+    "editorLocaleLabel": "Lingua del documento",
+    "editorPaymentMethodLabel": "Metodo di pagamento",
+    "editorPaymentInvoice": "Bonifico (fattura)",
+    "editorPaymentCard": "Carta di credito (Stripe)",
+    "editorLinesHeading": "Voci",
+    "editorLineDescription": "Descrizione",
+    "editorLineDescriptionPlaceholder": "es. Ore di consulenza, integrazione su misura, …",
+    "editorLineQty": "Q.tà",
+    "editorLineUnitPrice": "Prezzo unitario",
+    "editorLineAmount": "Importo",
+    "editorLineRemove": "Rimuovi riga",
+    "editorAddLine": "Aggiungi riga",
+    "editorAddDiscount": "Aggiungi sconto",
+    "editorAddDiscountHint": "Aggiunge una riga con prezzo unitario negativo. Modifica descrizione e importo se necessario.",
+    "editorRabattDefaultDescription": "Sconto",
+    "editorNotesHeading": "Note interne",
+    "editorNotesPlaceholder": "Note visibili solo all'admin (non sul PDF)",
+    "editorNotesHint": "Non mostrato al cliente.",
+    "editorTotalsHeading": "Totali (stima)",
+    "editorSubtotal": "Subtotale",
+    "editorVat": "IVA",
+    "editorTotal": "Totale",
+    "editorTotalsEstimateNote": "Stima basata sul paese del cliente. L'IVA finale è calcolata all'emissione.",
+    "editorSaveBtn": "Salva bozza",
+    "editorSavedBtn": "Salvato",
+    "editorPreviewBtn": "Anteprima PDF",
+    "editorIssueBtn": "Emetti fattura",
+    "editorDeleteBtn": "Scarta bozza",
+    "editorIssueConfirm": "Emettere questa fattura ora? Verrà assegnato un numero di fattura, il PDF sarà inviato al cliente e questa bozza verrà rimossa.",
+    "editorDeleteConfirm": "Scartare questa bozza? Operazione irreversibile.",
+    "previewing": "Apertura…",
+    "issuing": "Emissione…"
   },
   "skillCostDialog": {
     "title": "Conferma costi di attivazione",
@@ -736,11 +837,72 @@
       "paid": "Pagata",
       "overdue": "In ritardo",
       "void": "Annullata",
-      "uncollectible": "Inesigibile"
+      "uncollectible": "Inesigibile",
+      "partially_refunded": "Rimborsata parzialmente",
+      "fully_refunded": "Rimborsata integralmente"
     },
     "payWithCard": "Paga con carta",
     "redirectingToStripe": "Reindirizzamento…",
-    "paymentReceived": "Pagamento ricevuto — grazie. Lo stato si aggiornerà alla conferma di Stripe (pochi secondi).",
-    "paymentCancelled": "Il pagamento è stato annullato. La fattura rimane aperta; puoi riprovare in qualsiasi momento."
+    "paymentReceived": "Pagamento ricevuto — grazie!",
+    "paymentCancelled": "Pagamento annullato.",
+    "configureBillingCta": "Configura dati di fatturazione",
+    "noBillingConfigNonOwner": "Solo il proprietario dell'organizzazione può configurare i dati di fatturazione. Contattalo per completare questo passaggio.",
+    "creditNotesHeading": "Note di credito",
+    "creditNoteNumberCol": "Nota di credito",
+    "creditNoteInvoiceCol": "Fattura",
+    "creditNoteIssuedCol": "Emessa",
+    "creditNoteAmountCol": "Importo",
+    "creditNoteKindCol": "Tipo",
+    "creditNotePdfCol": "PDF",
+    "creditNoteKind_void": "Annullamento",
+    "creditNoteKind_refund": "Rimborso",
+    "creditNoteNoPdf": "PDF non disponibile"
+  },
+  "adminCron": {
+    "title": "Automazione fatturazione",
+    "subtitle": "Emissione mensile e invio quotidiano dei solleciti. Entrambi vengono eseguiti automaticamente; usa i pulsanti sotto per avviare un'esecuzione su richiesta.",
+    "monthlyIssue": "Emissione mensile",
+    "reminders": "Solleciti",
+    "scheduleIssueLabel": "Pianificazione",
+    "scheduleIssueValue": "00:30 Europe/Zurich il 1°",
+    "scheduleReminderLabel": "Pianificazione",
+    "scheduleReminderValue": "09:00 Europe/Zurich quotidianamente",
+    "lastSuccess": "Ultimo successo",
+    "never": "mai",
+    "runIssueNow": "Fattura il mese scorso ora",
+    "runRemindersNow": "Avvia solleciti ora",
+    "running": "In corso…",
+    "flashIssueOk": "Emissione completata: {success} fatture emesse, {skipped} ignorate, {failure} fallite.",
+    "flashRemindersOk": "Solleciti inviati: {success} riusciti, {skipped} ignorati, {failure} falliti.",
+    "recentRuns": "Esecuzioni recenti (ultime 30)",
+    "noRunsYet": "Nessuna esecuzione automatica registrata.",
+    "startedCol": "Avviata",
+    "kindCol": "Tipo",
+    "triggeredByCol": "Avviata da",
+    "okCol": "OK",
+    "skipCol": "Ignorati",
+    "failCol": "Falliti",
+    "triggeredByCron": "cron",
+    "kind": {
+      "monthly_issue": "Emissione",
+      "reminders": "Solleciti"
+    },
+    "failureBannerTitle": "Fallimenti recenti rilevati",
+    "failureBannerBody": "{count} esecuzione/i recente/i hanno segnalato almeno un fallimento. Controlla la tabella sotto — le righe interessate sono in rosso."
+  },
+  "settingsProfile": {
+    "title": "Profilo",
+    "subtitle": "Il tuo nome visualizzato come appare nel portale, nelle richieste tenant e nei ticket di supporto.",
+    "subtitlePersonal": "Il tuo nome visualizzato come appare nel portale. Per modificare il tuo nome in fattura, modificalo in Dati di fatturazione.",
+    "firstNameLabel": "Nome",
+    "lastNameLabel": "Cognome",
+    "emailLabel": "E-mail",
+    "emailReadOnlyHint": "L'e-mail non può essere modificata qui. Usa le impostazioni self-service del tuo provider di identità.",
+    "personalAccountHint": "Questo è un account personale. Modificare il tuo nome qui NON cambia come appare in fattura — modificalo separatamente in Dati di fatturazione.",
+    "companyAccountHint": "Sei connesso come membro di {orgName}.",
+    "saveChanges": "Salva modifiche",
+    "saving": "Salvataggio…",
+    "saved": "Salvato.",
+    "missingRequired": "Nome e cognome sono obbligatori."
   }
 }

src/types/index.ts

@@ -234,6 +234,12 @@ export interface BillingAddress {
 export interface OrgBilling {
   zitadelOrgId: string;
   companyName: string;
+  // Optional contact-person line ("z.Hd. / Attn:") shown on the
+  // invoice PDF below the company name. Useful when invoicing
+  // larger companies where the mailroom needs a name to route
+  // the document. Personal accounts don't expose this in the UI —
+  // their "Full name" already lives in companyName.
+  contactName?: string | null;
   streetAddress: string;
   postalCode: string;
   city: string;
@@ -538,10 +544,71 @@ export type InvoiceStatus =
   | "paid"
   | "overdue"
   | "void"
-  | "uncollectible";
+  | "uncollectible"
+  // Phase 7: refund states. partially_refunded = at least one refund
+  // recorded but sum < total. fully_refunded = sum >= total. Voiding
+  // applies to unpaid invoices; refunding applies to paid invoices —
+  // the two states are mutually exclusive transitions from 'paid'
+  // versus 'open'.
+  | "partially_refunded"
+  | "fully_refunded";
 
 export type InvoicePaymentMethod = "invoice" | "card";
 
+// Phase 7 — credit notes are independent documents (separate
+// numbering, separate PDF) that record a void or refund against an
+// original invoice. Issued as part of voidInvoice() or
+// refundInvoice() flows; the customer downloads them from
+// /api/credit-notes/<number>/pdf.
+export type CreditNoteKind = "void" | "refund";
+
+export interface CreditNote {
+  id: string;
+  creditNoteNumber: string;
+  invoiceId: string;
+  invoiceNumber: string;
+  zitadelOrgId: string;
+  kind: CreditNoteKind;
+  amountChf: number;
+  vatAmountChf: number;
+  reason: string | null;
+  issuedAt: string;
+  issuedBy: string;
+  locale: string;
+  pdfFilename: string | null;
+  hasPdf: boolean;
+  billingSnapshot: InvoiceBillingSnapshot;
+}
+
+// Phase 7 — per-refund-event record (one row per Stripe Refund
+// object, or per admin-initiated refund for invoice-paid customers).
+// Aggregated into invoices.refunded_total_chf for query convenience.
+export interface InvoiceRefund {
+  id: string;
+  invoiceId: string;
+  stripeRefundId: string | null;
+  amountChf: number;
+  reason: string | null;
+  status: "pending" | "succeeded" | "failed" | "canceled";
+  refundedAt: string;
+  refundedBy: string;
+  creditNoteId: string | null;
+}
+
+// Phase 5 — Cron run history rows for the admin /admin/cron page.
+export type CronRunKind = "monthly_issue" | "reminders";
+export interface CronRun {
+  id: string;
+  runKind: CronRunKind;
+  triggeredBy: string;
+  startedAt: string;
+  finishedAt: string | null;
+  successCount: number;
+  failureCount: number;
+  skippedCount: number;
+  errorDetails: unknown | null;
+}
+
 export type InvoiceLineKind =
   | "tenant_monthly"
   | "tenant_setup"
@@ -549,7 +616,11 @@ export type InvoiceLineKind =
   | "threema_messages"
   | "skill_usage"
   | "skill_setup"
-  | "adjustment";
+  | "adjustment"
+  // Phase 8 — line kind for ad-hoc invoices. Rendered under a
+  // "Services" / "Leistungen" header on the PDF. Negative
+  // unitPriceChf is allowed (used for Rabatt rows).
+  | "custom_line";
 
 /**
  * Snapshot of the customer's billing details captured at invoice
@@ -561,6 +632,7 @@ export type InvoiceLineKind =
  */
 export interface InvoiceBillingSnapshot {
   companyName: string;
+  contactName: string | null;
   streetAddress: string;
   postalCode: string;
   city: string;
@@ -601,8 +673,19 @@ export interface Invoice {
   id: string;
   invoiceNumber: string;
   zitadelOrgId: string;
-  periodStart: string; // ISO date (YYYY-MM-DD)
-  periodEnd: string;
+  /**
+   * Phase 8: invoice provenance. 'auto' = generated by the monthly
+   * cron from tenant usage; 'custom' = created via the admin
+   * "New invoice" flow. Custom invoices have nullable period_start
+   * / period_end and skip the per-org-per-month uniqueness guard.
+   * Defaults to 'auto' for all pre-Phase-8 rows (backfilled by the
+   * column DEFAULT).
+   */
+  source: "auto" | "custom";
+  // Billing period — null on custom invoices that aren't tied to a
+  // billing period.
+  periodStart: string | null;
+  periodEnd: string | null;
   issuedAt: string;
   dueAt: string;
   subtotalChf: number;
@@ -620,6 +703,16 @@ export interface Invoice {
   paidAt: string | null;
   paidBy: string | null;
   paidMethodDetail: string | null;
+  // Phase 7 — void tracking. Populated when status='void'. The reason
+  // free-text is rendered on the credit note PDF.
+  voidReason: string | null;
+  voidedAt: string | null;
+  voidedBy: string | null;
+  // Phase 7 — running sum of refunds applied to this invoice. Zero
+  // for invoices that have never been refunded. Drives status
+  // transitions (partially_refunded vs fully_refunded) and the
+  // running-total widget on /billing.
+  refundedTotalChf: number;
   createdAt: string;
 }
 
@@ -637,8 +730,21 @@ export interface InvoiceDetail {
  */
 export interface InvoiceDraft {
   zitadelOrgId: string;
-  periodStart: string;
-  periodEnd: string;
+  /**
+   * Phase 8: optional for custom invoices. The auto cron always
+   * sets both period_start and period_end; the custom flow may
+   * leave them null.
+   */
+  periodStart: string | null;
+  periodEnd: string | null;
+  /**
+   * Phase 8: optional override of the issue date. When omitted,
+   * the DB uses now() at insertion time. The custom flow uses
+   * this to let admin backdate or future-date invoices.
+   */
+  issuedAt?: string;
+  /** Phase 8: 'auto' (cron) or 'custom' (admin form). Defaults to 'auto'. */
+  source?: "auto" | "custom";
   dueAt: string;
   locale: string;
   paymentMethod: InvoicePaymentMethod;
@@ -656,6 +762,65 @@ export interface InvoiceDraft {
   warnings: string[];
 }
 
+// ---------------------------------------------------------------------------
+// Phase 8 — custom invoice drafts
+// ---------------------------------------------------------------------------
+
+/**
+ * The shape persisted in the invoice_drafts.payload JSONB column.
+ * This is the in-progress form state the admin is composing — not
+ * yet an invoice. On "Issue" it's converted into a real Invoice row
+ * via billing.issueCustomInvoiceDraft and the draft row deleted.
+ *
+ * Kept separate from InvoiceDraft (which is the compute pipeline's
+ * type for in-flight monthly bills) so the two domains don't
+ * accidentally drift.
+ */
+export interface CustomInvoiceDraftPayload {
+  /** ISO date (YYYY-MM-DD). Defaults to today on creation. */
+  issueDate: string;
+  /** ISO date (YYYY-MM-DD). Defaults to issueDate + 30 days. */
+  dueDate: string;
+  /** Locale for the PDF and email; defaults to org's default. */
+  locale: "de" | "en" | "fr" | "it";
+  paymentMethod: InvoicePaymentMethod;
+  /**
+   * Optional notes only the admin sees in the portal (not on the PDF).
+   */
+  adminNotes?: string;
+  lines: CustomInvoiceDraftLine[];
+}
+
+export interface CustomInvoiceDraftLine {
+  /** Free-text description, shown on the PDF as the line label. */
+  description: string;
+  /**
+   * Decimal quantity. Most cases are integer (1, 2, 10 hours) but
+   * we allow decimal for fractional hours (0.5) or ratios.
+   */
+  quantity: number;
+  /**
+   * CHF per unit. Negative values are allowed for discount /
+   * Rabatt rows — the PDF shows them as negative amounts and the
+   * subtotal is the algebraic sum of all line amounts.
+   */
+  unitPriceChf: number;
+}
+
+/**
+ * The DB row in invoice_drafts. The admin can save a draft, come
+ * back later, and issue it (or delete it) at any time. Drafts have
+ * no invoice number, no PDF, and are never visible to the customer.
+ */
+export interface InvoiceDraftRecord {
+  id: string;
+  zitadelOrgId: string;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+  payload: CustomInvoiceDraftPayload;
+}
+
 // ---------------------------------------------------------------------------
 // Skill activation requests — manual provisioning queue
 // ---------------------------------------------------------------------------