From 47225405a9be29191488bc552ec4336e17033050 Mon Sep 17 00:00:00 2001
From: naaiyy <naaiyyyy@gmail.com>
Date: Sat, 22 Aug 2026 03:10:50 +0200
Subject: [PATCH] Refactor billing around workspace members

---
 CONTEXT.md                                    |  25 +++
 .../dashboard/billing/billing-overview.tsx    |  27 +--
 .../dashboard/billing/billing-plan-cards.tsx  |   3 +-
 .../dashboard/billing/billing-plans-page.tsx  |  10 +-
 .../features/dashboard/billing/model.test.ts  |  32 ++-
 apps/web/features/dashboard/billing/model.ts  |  12 +-
 .../content-pages/content/docs/index.fr.mdx   |   3 +
 .../content-pages/content/docs/index.mdx      |   3 +
 .../content-pages/content/docs/meta.fr.json   |   2 +
 .../content-pages/content/docs/meta.json      |   2 +
 .../content/docs/plans-and-billing.fr.mdx     |  70 +++++++
 .../content/docs/plans-and-billing.mdx        |  70 +++++++
 .../marketing/content-pages/source.ts         |   2 +
 packages/backend/convex/_generated/api.d.ts   |   2 +
 .../backend/convex/_generated/server.d.ts     |   8 +-
 .../convex/billing-webhook-model.test.ts      |   3 +-
 packages/backend/convex/billing.ts            | 136 +++++++------
 .../backend/convex/billingMigrations.test.ts  |  87 +++++++++
 packages/backend/convex/billingMigrations.ts  | 182 ++++++++++++++++++
 packages/backend/convex/billingModel.ts       |  33 ++--
 .../backend/convex/billing_webhook_model.ts   |  12 --
 packages/backend/convex/schema.ts             |   6 +-
 packages/backend/convex/schema/billing.ts     |   9 +-
 .../backend/convex/workspaceBilling.test.ts   |  21 +-
 packages/backend/convex/workspaceBilling.ts   |  18 +-
 packages/i18n/src/messages/en.json            |  20 +-
 packages/i18n/src/messages/fr.json            |  20 +-
 27 files changed, 614 insertions(+), 204 deletions(-)
 create mode 100644 CONTEXT.md
 create mode 100644 apps/web/features/marketing/content-pages/content/docs/plans-and-billing.fr.mdx
 create mode 100644 apps/web/features/marketing/content-pages/content/docs/plans-and-billing.mdx
 create mode 100644 packages/backend/convex/billingMigrations.test.ts
 create mode 100644 packages/backend/convex/billingMigrations.ts

diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 00000000..42a08ef1
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,25 @@
+# BaseBlocks context
+
+This context defines the product terms that cross the workspace and billing domains.
+
+## Workspace and billing language
+
+**Workspace member**:
+An accepted member of a workspace. Workspace members are counted from the authentication membership records.
+_Avoid_: Active member when describing membership; active means recent product activity.
+
+**Subscription**:
+A recurring relationship between a workspace and a billing provider.
+_Avoid_: Plan when referring to the provider relationship.
+
+**Plan**:
+The product access level available to a workspace, such as Free or Plus.
+_Avoid_: Seat when referring to product access.
+
+**Paid seat quantity**:
+The quantity sent to the billing provider for a Plus subscription. It is an internal billing value and is not a workspace-membership count.
+_Avoid_: Active members, billable members, or seats in normal user-facing copy.
+
+**AI credits**:
+A workspace-level balance that funds AI usage. Included credits and prepaid credits have separate expiration rules.
+_Avoid_: AI seats.
diff --git a/apps/web/features/dashboard/billing/billing-overview.tsx b/apps/web/features/dashboard/billing/billing-overview.tsx
index df1ae8be..9b44d0f5 100644
--- a/apps/web/features/dashboard/billing/billing-overview.tsx
+++ b/apps/web/features/dashboard/billing/billing-overview.tsx
@@ -26,7 +26,6 @@ import {
 } from "@/features/dashboard/layout/dashboard-page";
 import {
   canUsePaidFeatures,
-  getAdditionalSeatCount,
   getBillingCallout,
   type BillingCallout,
   type WorkspaceBillingEntitlement,
@@ -126,9 +125,9 @@ function BillingSupportDialog() {
           {t("description")}{" "}
           <a
             className="font-medium text-sidebar-foreground underline decoration-sidebar-foreground/30 underline-offset-2 transition-colors hover:decoration-sidebar-foreground focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50"
-            href="mailto:support@easylink.com"
+            href="mailto:support@easylink.one"
           >
-            support@easylink.com
+            support@easylink.one
           </a>
           .
         </DialogDescription>
@@ -151,7 +150,6 @@ export function BillingOverview({
   const t = useTranslations("billing");
   const locale = useLocale();
   const isPlus = canUsePaidFeatures(entitlement);
-  const additionalSeats = getAdditionalSeatCount(entitlement);
   const callout = getBillingCallout(entitlement);
   const [selectedPlusSku, setSelectedPlusSku] = useState(
     plusOptions.find((option) => option.recurringInterval === "year")?.sku ??
@@ -189,13 +187,8 @@ export function BillingOverview({
             </p>
             <p className="mt-1 text-xs text-muted-foreground">
               {t("current.memberCount", {
-                count: entitlement.billableSeatCount,
+                count: entitlement.workspaceMemberCount,
               })}
-              {isPlus
-                ? ` · ${t("current.paidSeatCount", {
-                    count: entitlement.paidSeatCapacity,
-                  })}`
-                : null}
             </p>
             {effectiveThrough ? (
               <p className="mt-1 text-xs text-muted-foreground">
@@ -252,21 +245,11 @@ export function BillingOverview({
             </p>
             <p className="mt-1 text-xs text-muted-foreground">
               {t("current.memberCount", {
-                count: entitlement.billableSeatCount,
+                count: entitlement.workspaceMemberCount,
               })}
-              {isPlus
-                ? ` · ${t("current.paidSeatCount", {
-                    count: entitlement.paidSeatCapacity,
-                  })}`
-                : null}
             </p>
-            {additionalSeats > 0 || effectiveThrough ? (
+            {effectiveThrough ? (
               <div className="mt-1 space-y-0.5 text-xs text-muted-foreground">
-                {additionalSeats > 0 ? (
-                  <p>
-                    {t("current.additionalSeats", { count: additionalSeats })}
-                  </p>
-                ) : null}
                 {effectiveThrough ? (
                   <p>
                     {t("current.effectiveThrough", { date: effectiveThrough })}
diff --git a/apps/web/features/dashboard/billing/billing-plan-cards.tsx b/apps/web/features/dashboard/billing/billing-plan-cards.tsx
index 9f8d7bd2..0d3cc11b 100644
--- a/apps/web/features/dashboard/billing/billing-plan-cards.tsx
+++ b/apps/web/features/dashboard/billing/billing-plan-cards.tsx
@@ -157,10 +157,9 @@ export function BillingPlanCards({
               )}
             </div>
           </div>
-          <ul className="mt-4 grid gap-2 sm:grid-cols-3">
+          <ul className="mt-4 grid gap-2 sm:grid-cols-2">
             <PlanFeature>{t("plans.plus.features.everything")}</PlanFeature>
             <PlanFeature>{t("plans.plus.features.ai")}</PlanFeature>
-            <PlanFeature>{t("plans.plus.features.seats")}</PlanFeature>
           </ul>
         </div>
       ) : null}
diff --git a/apps/web/features/dashboard/billing/billing-plans-page.tsx b/apps/web/features/dashboard/billing/billing-plans-page.tsx
index 0220762b..cb5a4650 100644
--- a/apps/web/features/dashboard/billing/billing-plans-page.tsx
+++ b/apps/web/features/dashboard/billing/billing-plans-page.tsx
@@ -80,12 +80,7 @@ export function BillingPlansPage({
         {
           feature: t("plans.comparison.ai"),
           free: t("plans.comparison.prepaid"),
-          plus: t("plans.comparison.monthly"),
-        },
-        {
-          feature: t("plans.comparison.seats"),
-          free: t("plans.comparison.notIncluded"),
-          plus: <Included />,
+          plus: t("plans.comparison.includedAndPrepaid"),
         },
       ],
     },
@@ -150,9 +145,6 @@ export function BillingPlansPage({
                     <p className="mt-1 text-sm text-foreground">
                       <span className="font-semibold">
                         {t("plans.free.price")}
-                      </span>{" "}
-                      <span className="text-xs text-muted-foreground">
-                        {t("plans.perMemberMonth")}
                       </span>
                     </p>
                   </div>
diff --git a/apps/web/features/dashboard/billing/model.test.ts b/apps/web/features/dashboard/billing/model.test.ts
index c19b798e..36e07c99 100644
--- a/apps/web/features/dashboard/billing/model.test.ts
+++ b/apps/web/features/dashboard/billing/model.test.ts
@@ -2,7 +2,6 @@ import { describe, expect, test } from "bun:test";
 import {
   canRequestAi,
   canUsePaidFeatures,
-  getAdditionalSeatCount,
   getBillingCallout,
   type WorkspaceBillingEntitlement,
 } from "./model";
@@ -10,8 +9,7 @@ import {
 const plusEntitlement: WorkspaceBillingEntitlement = {
   plan: "plus",
   subscriptionState: "entitled",
-  billableSeatCount: 3,
-  paidSeatCapacity: 3,
+  workspaceMemberCount: 3,
   plusEnabled: true,
   aiAdmissionAvailable: true,
   availableAiCreditUnits: 500_000n,
@@ -46,22 +44,18 @@ describe("billing presentation model", () => {
     ).toBe(false);
   });
 
-  test("reports seats beyond paid capacity without negative counts", () => {
-    expect(getAdditionalSeatCount(plusEntitlement)).toBe(0);
-    expect(
-      getAdditionalSeatCount({
-        ...plusEntitlement,
-        billableSeatCount: 5,
-        paidSeatCapacity: 3,
-      }),
-    ).toBe(2);
-    expect(
-      getAdditionalSeatCount({
-        ...plusEntitlement,
-        billableSeatCount: 1,
-        paidSeatCapacity: 3,
-      }),
-    ).toBe(0);
+  test("uses the accepted workspace-member count as the only member value", () => {
+    const freeEntitlement: WorkspaceBillingEntitlement = {
+      ...plusEntitlement,
+      plan: "free",
+      subscriptionState: "none",
+      workspaceMemberCount: 8,
+      plusEnabled: false,
+      aiAdmissionAvailable: false,
+      availableAiCreditUnits: 0n,
+    };
+
+    expect(freeEntitlement.workspaceMemberCount).toBe(8);
   });
 
   test("maps non-entitled states to an actionable callout", () => {
diff --git a/apps/web/features/dashboard/billing/model.ts b/apps/web/features/dashboard/billing/model.ts
index 9e47d09d..7841ab1c 100644
--- a/apps/web/features/dashboard/billing/model.ts
+++ b/apps/web/features/dashboard/billing/model.ts
@@ -13,8 +13,7 @@ export type SubscriptionState = (typeof subscriptionStates)[number];
 export interface WorkspaceBillingEntitlement {
   plan: "free" | "plus";
   subscriptionState: SubscriptionState;
-  billableSeatCount: number;
-  paidSeatCapacity: number;
+  workspaceMemberCount: number;
   plusEnabled: boolean;
   aiAdmissionAvailable: boolean;
   availableAiCreditUnits: bigint;
@@ -41,15 +40,6 @@ export function getBillingCallout(
   return entitlement.subscriptionState;
 }
 
-export function getAdditionalSeatCount(
-  entitlement: WorkspaceBillingEntitlement,
-): number {
-  return Math.max(
-    0,
-    entitlement.billableSeatCount - entitlement.paidSeatCapacity,
-  );
-}
-
 export function canUsePaidFeatures(
   entitlement: WorkspaceBillingEntitlement,
 ): boolean {
diff --git a/apps/web/features/marketing/content-pages/content/docs/index.fr.mdx b/apps/web/features/marketing/content-pages/content/docs/index.fr.mdx
index 9024bf3a..f45e4571 100644
--- a/apps/web/features/marketing/content-pages/content/docs/index.fr.mdx
+++ b/apps/web/features/marketing/content-pages/content/docs/index.fr.mdx
@@ -45,6 +45,9 @@ BaseBlocks est un constructeur de sites Fair Source pour les équipes. Créez de
   <Card href="/docs/team" title="Équipe">
     Configuration de l'espace de travail, rôles et gestion des membres.
   </Card>
+  <Card href="/docs/plans-and-billing" title="Offres et facturation">
+    Comprendre les offres, les crédits IA, les membres et la facturation.
+  </Card>
   <Card href="/docs/sites/branding" title="Identité visuelle">
     Nom et logo du site dans la barre latérale publiée.
   </Card>
diff --git a/apps/web/features/marketing/content-pages/content/docs/index.mdx b/apps/web/features/marketing/content-pages/content/docs/index.mdx
index fe8602ff..ef2b416c 100644
--- a/apps/web/features/marketing/content-pages/content/docs/index.mdx
+++ b/apps/web/features/marketing/content-pages/content/docs/index.mdx
@@ -45,6 +45,9 @@ BaseBlocks is a Fair Source site builder for teams. Build internal sites with a
   <Card href="/docs/team" title="Team">
     Workspace setup, roles, and member management.
   </Card>
+  <Card href="/docs/plans-and-billing" title="Plans and billing">
+    Understand plans, AI credits, workspace members, and billing.
+  </Card>
   <Card href="/docs/sites/branding" title="Branding">
     Site name and logo in the published sidebar.
   </Card>
diff --git a/apps/web/features/marketing/content-pages/content/docs/meta.fr.json b/apps/web/features/marketing/content-pages/content/docs/meta.fr.json
index 0b737983..01316bee 100644
--- a/apps/web/features/marketing/content-pages/content/docs/meta.fr.json
+++ b/apps/web/features/marketing/content-pages/content/docs/meta.fr.json
@@ -8,6 +8,8 @@
     "...editor",
     "---Publication---",
     "...publishing",
+    "---Facturation---",
+    "plans-and-billing",
     "---Espace de travail---",
     "...team",
     "...sites",
diff --git a/apps/web/features/marketing/content-pages/content/docs/meta.json b/apps/web/features/marketing/content-pages/content/docs/meta.json
index a7097b2b..c5e52fa6 100644
--- a/apps/web/features/marketing/content-pages/content/docs/meta.json
+++ b/apps/web/features/marketing/content-pages/content/docs/meta.json
@@ -8,6 +8,8 @@
     "...editor",
     "---Publishing---",
     "...publishing",
+    "---Billing---",
+    "plans-and-billing",
     "---Workspace---",
     "...team",
     "...sites",
diff --git a/apps/web/features/marketing/content-pages/content/docs/plans-and-billing.fr.mdx b/apps/web/features/marketing/content-pages/content/docs/plans-and-billing.fr.mdx
new file mode 100644
index 00000000..d680f25f
--- /dev/null
+++ b/apps/web/features/marketing/content-pages/content/docs/plans-and-billing.fr.mdx
@@ -0,0 +1,70 @@
+---
+title: Offres et facturation
+description: Comprendre les offres BaseBlocks, les membres de l’espace et les crédits IA.
+icon: CreditCard
+---
+
+import { Accordions, Accordion } from 'fumadocs-ui/components/accordion';
+
+BaseBlocks maintient gratuites les fonctions principales de création de sites, de publication et de collaboration. L’IA utilise des crédits liés à l’utilisation : vous pouvez donc utiliser l’IA avec des crédits prépayés dans l’offre gratuite ou choisir Plus pour obtenir des crédits récurrents inclus.
+
+## Offres
+
+| | Gratuite | Plus |
+|---|---|---|
+| Prix | 0 $ pour l’espace | 8 $ par membre de l’espace/mois ou 80 $ par membre de l’espace/an |
+| Membres | Membres de l’espace illimités | Facturation par membre accepté de l’espace |
+| Fonctions principales | Sites, publication et collaboration | Tout le contenu de l’offre gratuite |
+| IA | Crédits prépayés | Crédits inclus pour l’espace, plus des recharges prépayées |
+
+<Callout type="info">
+  Les prix et les offres disponibles peuvent changer. La page Facturation de votre espace affiche les options et le prix actuels.
+</Callout>
+
+## Offre gratuite
+
+L’offre gratuite inclut un nombre illimité de membres, de sites, de publications et de fonctionnalités de collaboration. Elle ne nécessite pas d’abonnement.
+
+L’IA est disponible dans l’offre gratuite avec des crédits prépayés. Ajoutez des crédits avant d’utiliser l’IA. Les crédits achetés n’expirent pas et sont partagés par l’espace.
+
+## Offre Plus
+
+Plus est facturée par membre accepté de l’espace. Si huit membres acceptés appartiennent à un espace, l’espace est facturé pour huit membres.
+
+Plus inclut des crédits IA récurrents pour l’espace. Les crédits inclus sont réinitialisés à la fin de chaque période de facturation. Vous pouvez ajouter des crédits prépayés lorsque vous en avez besoin ; les crédits achetés n’expirent pas.
+
+## Membres de l’espace et facturation
+
+Un membre accepté de l’espace est une personne dont l’adhésion à l’espace a été acceptée. Le nombre de membres ne dépend pas du fait que cette personne soit actuellement en ligne ou ait utilisé BaseBlocks récemment.
+
+Tous les rôles de l’espace comptent comme des membres. Les invitations en attente, les invités d’une page et les visiteurs publics ne comptent pas comme des membres de l’espace. Les espaces gratuits peuvent avoir un nombre illimité de membres. Les espaces Plus utilisent le nombre de membres acceptés pour la facturation.
+
+## Pourquoi l’IA est-elle payante ?
+
+Les requêtes IA ont un coût variable lié à leur utilisation. La facturation de l’utilisation de l’IA permet à BaseBlocks de maintenir l’espace de travail principal gratuit tout en vous laissant contrôler votre consommation d’IA.
+
+Vous n’avez pas besoin de Plus pour utiliser l’IA. Choisissez l’offre gratuite avec des crédits prépayés si vous préférez payer selon votre utilisation. Choisissez Plus si les crédits récurrents inclus et la facturation par membre conviennent mieux à votre espace.
+
+## Questions fréquentes
+
+<Accordions type="single">
+
+<Accordion title="Dois-je payer pour les membres de l’espace avec l’offre gratuite ?">
+
+Non. L’offre gratuite inclut un nombre illimité de membres. La facturation par membre s’applique uniquement aux abonnements Plus.
+
+</Accordion>
+
+<Accordion title="Dois-je avoir Plus pour utiliser l’IA ?">
+
+Non. Ajoutez des crédits IA prépayés à un espace gratuit. Plus ajoute des crédits récurrents inclus et prend toujours en charge les recharges prépayées.
+
+</Accordion>
+
+<Accordion title="Les crédits prépayés expirent-ils ?">
+
+Non. Les crédits achetés n’expirent pas. Les crédits Plus inclus sont réinitialisés à la fin de la période de facturation.
+
+</Accordion>
+
+</Accordions>
diff --git a/apps/web/features/marketing/content-pages/content/docs/plans-and-billing.mdx b/apps/web/features/marketing/content-pages/content/docs/plans-and-billing.mdx
new file mode 100644
index 00000000..8ef1353a
--- /dev/null
+++ b/apps/web/features/marketing/content-pages/content/docs/plans-and-billing.mdx
@@ -0,0 +1,70 @@
+---
+title: Plans and billing
+description: Understand BaseBlocks plans, workspace members, and AI credits.
+icon: CreditCard
+---
+
+import { Accordions, Accordion } from 'fumadocs-ui/components/accordion';
+
+BaseBlocks keeps core site building, publishing, and collaboration free. AI uses usage-based credits, so you can use AI on Free with prepaid credits or choose Plus for recurring included credits.
+
+## Plans
+
+| | Free | Plus |
+|---|---|---|
+| Price | $0 for the workspace | $8 per workspace member/month or $80 per workspace member/year |
+| Members | Unlimited workspace members | Billed per accepted workspace member |
+| Core features | Sites, publishing, and collaboration | Everything in Free |
+| AI | Prepaid credits | Included credits for the workspace, plus prepaid top-ups |
+
+<Callout type="info">
+  Prices and available plans can change. The Billing page in your workspace shows the current plan options and price.
+</Callout>
+
+## Free
+
+The Free plan includes unlimited workspace members, sites, publishing, and collaboration. It does not require a subscription.
+
+AI is available on Free through prepaid credits. Add credits before using AI. Purchased credits do not expire and are shared by the workspace.
+
+## Plus
+
+Plus is billed per accepted workspace member. If eight accepted members belong to a workspace, the workspace is billed for eight members.
+
+Plus includes recurring AI credits for the workspace. Included credits reset at the end of each billing period. You can add prepaid credits when you need more; purchased credits do not expire.
+
+## Workspace members and billing
+
+An accepted workspace member is a person whose membership in the workspace has been accepted. The member count does not depend on whether that person is currently online or has used BaseBlocks recently.
+
+All workspace roles count as members. Pending invitations, page guests, and public visitors do not count as workspace members. Free workspaces can have unlimited members. Plus workspaces use the accepted member count for billing.
+
+## Why is AI paid?
+
+AI requests have usage-based costs. Charging for AI usage lets BaseBlocks keep the core workspace free while giving you control over how much AI you use.
+
+You do not need Plus to use AI. Choose Free with prepaid credits when you want usage-based spending. Choose Plus when recurring included credits and per-member billing fit your workspace better.
+
+## Frequently asked questions
+
+<Accordions type="single">
+
+<Accordion title="Do I pay for workspace members on Free?">
+
+No. Free includes unlimited workspace members. Member-based billing applies only to Plus subscriptions.
+
+</Accordion>
+
+<Accordion title="Do I need Plus to use AI?">
+
+No. Add prepaid AI credits to a Free workspace. Plus adds recurring included credits and still supports prepaid top-ups.
+
+</Accordion>
+
+<Accordion title="Do prepaid credits expire?">
+
+No. Purchased credits do not expire. Included Plus credits reset at the end of the billing period.
+
+</Accordion>
+
+</Accordions>
diff --git a/apps/web/features/marketing/content-pages/source.ts b/apps/web/features/marketing/content-pages/source.ts
index 1f31ab37..405520b7 100644
--- a/apps/web/features/marketing/content-pages/source.ts
+++ b/apps/web/features/marketing/content-pages/source.ts
@@ -4,6 +4,7 @@ import {
   BookOpen01Icon,
   ComputerIcon,
   CookieIcon,
+  CreditCardIcon,
   FeatherIcon,
   File01Icon,
   GaugeIcon,
@@ -40,6 +41,7 @@ const docsIconMap = {
   BookOpen: BookOpen01Icon,
   Columns3: LayoutThreeColumnIcon,
   Cookie: CookieIcon,
+  CreditCard: CreditCardIcon,
   Eye: ViewIcon,
   Feather: FeatherIcon,
   FileText: File01Icon,
diff --git a/packages/backend/convex/_generated/api.d.ts b/packages/backend/convex/_generated/api.d.ts
index 444b4600..7316a4e7 100644
--- a/packages/backend/convex/_generated/api.d.ts
+++ b/packages/backend/convex/_generated/api.d.ts
@@ -14,6 +14,7 @@ import type * as auth from "../auth.js";
 import type * as billing from "../billing.js";
 import type * as billing_checkoutIntent from "../billing/checkoutIntent.js";
 import type * as billing_polar from "../billing/polar.js";
+import type * as billingMigrations from "../billingMigrations.js";
 import type * as billingModel from "../billingModel.js";
 import type * as billingRetention from "../billingRetention.js";
 import type * as billing_webhook_model from "../billing_webhook_model.js";
@@ -101,6 +102,7 @@ declare const fullApi: ApiFromModules<{
   billing: typeof billing;
   "billing/checkoutIntent": typeof billing_checkoutIntent;
   "billing/polar": typeof billing_polar;
+  billingMigrations: typeof billingMigrations;
   billingModel: typeof billingModel;
   billingRetention: typeof billingRetention;
   billing_webhook_model: typeof billing_webhook_model;
diff --git a/packages/backend/convex/_generated/server.d.ts b/packages/backend/convex/_generated/server.d.ts
index 3fe4bed1..820a31b1 100644
--- a/packages/backend/convex/_generated/server.d.ts
+++ b/packages/backend/convex/_generated/server.d.ts
@@ -25,12 +25,12 @@ import type { DataModel } from "./dataModel.js";
  * Typesafe environment variables declared in `convex.config.ts`.
  */
 type Env = {
-  readonly BASEBLOCKS_BILLING_ENVIRONMENT: "sandbox" | "production";
+  readonly BASEBLOCKS_BILLING_ENVIRONMENT: "sandbox" | "production" | undefined;
   readonly BASEBLOCKS_PAST_DUE_GRACE_DAYS: string | undefined;
   readonly INTEGRATIONS_ENABLED: "true" | "false";
-  readonly POLAR_ACCESS_TOKEN: string;
-  readonly POLAR_ALLOW_PRODUCTION: "true" | "false";
-  readonly POLAR_WEBHOOK_SECRET: string;
+  readonly POLAR_ACCESS_TOKEN: string | undefined;
+  readonly POLAR_ALLOW_PRODUCTION: "true" | "false" | undefined;
+  readonly POLAR_WEBHOOK_SECRET: string | undefined;
 };
 
 /**
diff --git a/packages/backend/convex/billing-webhook-model.test.ts b/packages/backend/convex/billing-webhook-model.test.ts
index d1f3ca78..a6e8b4bd 100644
--- a/packages/backend/convex/billing-webhook-model.test.ts
+++ b/packages/backend/convex/billing-webhook-model.test.ts
@@ -222,6 +222,7 @@ describe("Polar billing event interface", () => {
 
     expect(result.outcome).toBe("applied");
     expect(state.entitlement?.plusEnabled).toBe(true);
-    expect(state.entitlement?.paidSeatCapacity).toBe(2);
+    expect(state.entitlement).not.toHaveProperty("paidSeatCapacity");
+    expect(state.entitlement).not.toHaveProperty("billableSeatCount");
   });
 });
diff --git a/packages/backend/convex/billing.ts b/packages/backend/convex/billing.ts
index b08bbbaf..67755caa 100644
--- a/packages/backend/convex/billing.ts
+++ b/packages/backend/convex/billing.ts
@@ -31,11 +31,13 @@ import {
 } from "./permissions";
 
 type ProviderEnvironment = "sandbox" | "production";
-type SeatSnapshot = {
+type WorkspaceBillingSnapshot = {
   organizationId: string;
   memberIds: string[];
-  billableSeatCount: number;
+  workspaceMemberCount: number;
+  seatQuantity: number;
   membershipRevision: string;
+  source: "better-auth-members";
 };
 
 const getCatalogItem = makeFunctionReference<
@@ -58,11 +60,11 @@ const listSeatReconciliationCandidates = makeFunctionReference<
   { limit?: number },
   Array<Doc<"billingSubscriptions">>
 >("billingModel:listSeatReconciliationCandidates");
-const getSeatSnapshot = makeFunctionReference<
+const getWorkspaceBillingSnapshot = makeFunctionReference<
   "query",
   { organizationId: string },
-  SeatSnapshot
->("workspaceBilling:getSeatSnapshot");
+  WorkspaceBillingSnapshot
+>("workspaceBilling:getWorkspaceBillingSnapshot");
 const createCheckoutIntent = makeFunctionReference<
   "mutation",
   {
@@ -109,26 +111,27 @@ const recordCustomer = makeFunctionReference<
   },
   null
 >("billingModel:recordCustomer");
-const recordSeatSnapshot = makeFunctionReference<
+const recordBillingSnapshot = makeFunctionReference<
   "mutation",
   {
     organizationId: string;
     subscriptionId?: Id<"billingSubscriptions">;
     membershipRevision: string;
     memberIds: string[];
-    billableSeatCount: number;
+    workspaceMemberCount: number;
+    seatQuantity: number;
     source: "checkout" | "membership" | "webhook" | "reconcile";
   },
   Id<"billingSeatSnapshots">
->("billingModel:recordSeatSnapshot");
+>("billingModel:recordBillingSnapshot");
 const createSeatSyncOperation = makeFunctionReference<
   "mutation",
   {
     organizationId: string;
     subscriptionId: Id<"billingSubscriptions">;
     membershipRevision: string;
-    previousSeats: number;
-    targetSeats: number;
+    previousSeatQuantity: number;
+    targetSeatQuantity: number;
     idempotencyKey: string;
   },
   Doc<"billingSeatSyncOperations"> | null
@@ -305,11 +308,33 @@ function publicBillingError(failure: BillingFailure): ConvexError<{
   });
 }
 
+function assertWorkspaceBillingSnapshot(
+  snapshot: WorkspaceBillingSnapshot,
+  organizationId: string,
+): void {
+  if (
+    snapshot.organizationId !== organizationId ||
+    !Number.isSafeInteger(snapshot.workspaceMemberCount) ||
+    snapshot.workspaceMemberCount < 0 ||
+    snapshot.memberIds.length !== snapshot.workspaceMemberCount ||
+    new Set(snapshot.memberIds).size !== snapshot.workspaceMemberCount ||
+    !Number.isSafeInteger(snapshot.seatQuantity) ||
+    snapshot.seatQuantity !== Math.max(1, snapshot.workspaceMemberCount)
+  ) {
+    throw new Error("Workspace billing snapshot contract was violated");
+  }
+}
+
 export const getWorkspaceEntitlements = query({
   args: { organizationId: v.string() },
   handler: async (ctx, { organizationId }) => {
     await requireOrganizationMember(ctx, organizationId);
-    const [entitlement, creditAccount, canManageBilling] = await Promise.all([
+    const [
+      entitlement,
+      creditAccount,
+      canManageBilling,
+      workspaceBillingSnapshot,
+    ] = await Promise.all([
       ctx.db
         .query("workspaceEntitlements")
         .withIndex("by_organization", (q) =>
@@ -326,6 +351,7 @@ export const getWorkspaceEntitlements = query({
         resource: "organization",
         action: "update",
       }),
+      ctx.runQuery(getWorkspaceBillingSnapshot, { organizationId }),
     ]);
     const availableUnits = creditAccount
       ? creditAccount.availableIncludedUnits +
@@ -334,8 +360,7 @@ export const getWorkspaceEntitlements = query({
     return {
       plan: entitlement?.plan ?? ("free" as const),
       subscriptionState: entitlement?.subscriptionStatus ?? ("none" as const),
-      billableSeatCount: entitlement?.billableSeatCount ?? 1,
-      paidSeatCapacity: entitlement?.paidSeatCapacity ?? 0,
+      workspaceMemberCount: workspaceBillingSnapshot.workspaceMemberCount,
       plusEnabled: entitlement?.plusEnabled ?? false,
       aiAdmissionAvailable: availableUnits > 0n,
       availableAiCreditUnits: availableUnits,
@@ -442,19 +467,12 @@ export const beginCheckout = action({
     }
     const seatSnapshot =
       catalog.kind === "plus"
-        ? await ctx.runQuery(getSeatSnapshot, {
+        ? await ctx.runQuery(getWorkspaceBillingSnapshot, {
             organizationId: args.organizationId,
           })
         : undefined;
-    if (
-      seatSnapshot &&
-      (seatSnapshot.organizationId !== args.organizationId ||
-        seatSnapshot.billableSeatCount < 1 ||
-        seatSnapshot.memberIds.length !== seatSnapshot.billableSeatCount ||
-        new Set(seatSnapshot.memberIds).size !== seatSnapshot.billableSeatCount)
-    ) {
-      throw new Error("Workspace seat snapshot contract was violated");
-    }
+    if (seatSnapshot)
+      assertWorkspaceBillingSnapshot(seatSnapshot, args.organizationId);
     const attemptId = crypto.randomUUID();
     const intent = await ctx.runMutation(createCheckoutIntent, {
       organizationId: args.organizationId,
@@ -462,7 +480,7 @@ export const beginCheckout = action({
       providerEnvironment: environment,
       purpose: catalog.kind,
       sku: catalog.sku,
-      requestedSeats: seatSnapshot?.billableSeatCount,
+      requestedSeats: seatSnapshot?.seatQuantity,
       requestedAmountMinor,
       idempotencyKey,
       attemptId,
@@ -515,7 +533,7 @@ export const beginCheckout = action({
               ? undefined
               : Number(requestedAmountMinor),
           allowDiscountCodes: catalog.kind !== "aiCreditPack",
-          seats: seatSnapshot?.billableSeatCount,
+          seats: seatSnapshot?.seatQuantity,
           metadata: {
             ...billingOperationMetadata({
               workspaceId: args.organizationId,
@@ -545,11 +563,12 @@ export const beginCheckout = action({
         return { url: checkout.url, checkoutId: checkout.id, replay: true };
       }
       if (seatSnapshot) {
-        await ctx.runMutation(recordSeatSnapshot, {
+        await ctx.runMutation(recordBillingSnapshot, {
           organizationId: args.organizationId,
           membershipRevision: seatSnapshot.membershipRevision,
           memberIds: seatSnapshot.memberIds,
-          billableSeatCount: seatSnapshot.billableSeatCount,
+          workspaceMemberCount: seatSnapshot.workspaceMemberCount,
+          seatQuantity: seatSnapshot.seatQuantity,
           source: "checkout",
         });
       }
@@ -620,50 +639,51 @@ async function syncPaidSeatsForOrganization(
       organizationId,
       providerEnvironment: environment,
     }),
-    ctx.runQuery(getSeatSnapshot, { organizationId }),
+    ctx.runQuery(getWorkspaceBillingSnapshot, { organizationId }),
   ]);
   if (!subscription) return { state: "notSubscribed" as const };
-  if (
-    snapshot.billableSeatCount < 1 ||
-    snapshot.memberIds.length !== snapshot.billableSeatCount ||
-    new Set(snapshot.memberIds).size !== snapshot.billableSeatCount
-  ) {
-    throw new Error("Workspace seat snapshot contract was violated");
-  }
-  await ctx.runMutation(recordSeatSnapshot, {
+  assertWorkspaceBillingSnapshot(snapshot, organizationId);
+  await ctx.runMutation(recordBillingSnapshot, {
     organizationId,
     subscriptionId: subscription._id,
     membershipRevision: snapshot.membershipRevision,
     memberIds: snapshot.memberIds,
-    billableSeatCount: snapshot.billableSeatCount,
+    workspaceMemberCount: snapshot.workspaceMemberCount,
+    seatQuantity: snapshot.seatQuantity,
     source: "membership",
   });
-  if (subscription.seatQuantity === snapshot.billableSeatCount) {
-    return { state: "unchanged" as const, seats: subscription.seatQuantity };
+  if (subscription.seatQuantity === snapshot.seatQuantity) {
+    return {
+      state: "unchanged" as const,
+      seatQuantity: subscription.seatQuantity,
+    };
   }
   const idempotencyKey = `seat:${subscription.providerSubscriptionId}:${snapshot.membershipRevision}`;
   const operation = await ctx.runMutation(createSeatSyncOperation, {
     organizationId,
     subscriptionId: subscription._id,
     membershipRevision: snapshot.membershipRevision,
-    previousSeats: subscription.seatQuantity,
-    targetSeats: snapshot.billableSeatCount,
+    previousSeatQuantity: subscription.seatQuantity,
+    targetSeatQuantity: snapshot.seatQuantity,
     idempotencyKey,
   });
   if (!operation) throw new Error("Seat sync operation could not be persisted");
   if (operation.status === "applied")
-    return { state: "applied" as const, seats: operation.targetSeats };
+    return {
+      state: "applied" as const,
+      seatQuantity: operation.targetSeatQuantity,
+    };
   try {
     const polar = provider();
     const remote = await polar.getSubscription(
       subscription.providerSubscriptionId,
     );
     const updated =
-      remote.seats === snapshot.billableSeatCount
+      remote.seats === snapshot.seatQuantity
         ? remote
         : await polar.updateSubscriptionSeats(
             subscription.providerSubscriptionId,
-            snapshot.billableSeatCount,
+            snapshot.seatQuantity,
             "prorate",
           );
     await ctx.runMutation(completeSeatSyncOperation, {
@@ -674,7 +694,7 @@ async function syncPaidSeatsForOrganization(
     });
     return {
       state: "applied" as const,
-      seats: updated.seats ?? snapshot.billableSeatCount,
+      seatQuantity: updated.seats ?? snapshot.seatQuantity,
     };
   } catch (error) {
     await ctx.runMutation(failSeatSyncOperation, {
@@ -806,31 +826,25 @@ export const reconcilePaidSeats = internalAction({
     for (const subscription of subscriptions) {
       let operation: Doc<"billingSeatSyncOperations"> | null = null;
       try {
-        const snapshot = await ctx.runQuery(getSeatSnapshot, {
+        const snapshot = await ctx.runQuery(getWorkspaceBillingSnapshot, {
           organizationId: subscription.organizationId,
         });
-        if (
-          snapshot.organizationId !== subscription.organizationId ||
-          snapshot.billableSeatCount < 1 ||
-          snapshot.memberIds.length !== snapshot.billableSeatCount ||
-          new Set(snapshot.memberIds).size !== snapshot.billableSeatCount
-        ) {
-          throw new Error("Workspace seat snapshot contract was violated");
-        }
-        await ctx.runMutation(recordSeatSnapshot, {
+        assertWorkspaceBillingSnapshot(snapshot, subscription.organizationId);
+        await ctx.runMutation(recordBillingSnapshot, {
           organizationId: subscription.organizationId,
           subscriptionId: subscription._id,
           membershipRevision: snapshot.membershipRevision,
           memberIds: snapshot.memberIds,
-          billableSeatCount: snapshot.billableSeatCount,
+          workspaceMemberCount: snapshot.workspaceMemberCount,
+          seatQuantity: snapshot.seatQuantity,
           source: "reconcile",
         });
         operation = await ctx.runMutation(createSeatSyncOperation, {
           organizationId: subscription.organizationId,
           subscriptionId: subscription._id,
           membershipRevision: snapshot.membershipRevision,
-          previousSeats: subscription.seatQuantity,
-          targetSeats: snapshot.billableSeatCount,
+          previousSeatQuantity: subscription.seatQuantity,
+          targetSeatQuantity: snapshot.seatQuantity,
           idempotencyKey: `seat:${subscription.providerSubscriptionId}:${snapshot.membershipRevision}`,
         });
         if (!operation)
@@ -843,11 +857,11 @@ export const reconcilePaidSeats = internalAction({
           subscription.providerSubscriptionId,
         );
         const updated =
-          remote.seats === snapshot.billableSeatCount
+          remote.seats === snapshot.seatQuantity
             ? remote
             : await polar.updateSubscriptionSeats(
                 subscription.providerSubscriptionId,
-                snapshot.billableSeatCount,
+                snapshot.seatQuantity,
                 "prorate",
               );
         await ctx.runMutation(completeSeatSyncOperation, {
@@ -856,7 +870,7 @@ export const reconcilePaidSeats = internalAction({
             updated.modifiedAt ?? new Date().toISOString(),
           ),
         });
-        if (remote.seats === snapshot.billableSeatCount) unchanged += 1;
+        if (remote.seats === snapshot.seatQuantity) unchanged += 1;
         else applied += 1;
       } catch (error) {
         failed += 1;
diff --git a/packages/backend/convex/billingMigrations.test.ts b/packages/backend/convex/billingMigrations.test.ts
new file mode 100644
index 00000000..434741d9
--- /dev/null
+++ b/packages/backend/convex/billingMigrations.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import {
+  migrateBillingSnapshotDocument,
+  migrateSeatSyncOperationDocument,
+  migrateWorkspaceEntitlementDocument,
+} from "./billingMigrations";
+
+describe("billing domain migration", () => {
+  test("removes legacy entitlement seat fields", () => {
+    const migrated = migrateWorkspaceEntitlementDocument({
+      organizationId: "org-1",
+      plan: "plus",
+      subscriptionStatus: "entitled",
+      statusReason: "polar:active",
+      plusEnabled: true,
+      paidSeatCapacity: 8,
+      billableSeatCount: 8,
+      effectiveFrom: 1,
+      policyVersion: "polar-entitlements-v1",
+      derivedAt: 1,
+      updatedAt: 1,
+    });
+
+    expect(migrated).toEqual({
+      organizationId: "org-1",
+      plan: "plus",
+      subscriptionStatus: "entitled",
+      statusReason: "polar:active",
+      plusEnabled: true,
+      effectiveFrom: 1,
+      policyVersion: "polar-entitlements-v1",
+      derivedAt: 1,
+      updatedAt: 1,
+    });
+  });
+
+  test("separates workspace membership from the provider seat quantity", () => {
+    const migrated = migrateBillingSnapshotDocument({
+      organizationId: "org-1",
+      membershipRevision: '["m1","m2"]',
+      memberIds: ["m2", "m1"],
+      billableSeatCount: 2,
+      source: "checkout",
+      observedAt: 1,
+    });
+
+    expect(migrated.workspaceMemberCount).toBe(2);
+    expect(migrated.seatQuantity).toBe(2);
+    expect(migrated.memberIds).toEqual(["m1", "m2"]);
+    expect(migrated).not.toHaveProperty("billableSeatCount");
+  });
+
+  test("normalizes duplicate legacy members before deriving quantities", () => {
+    const migrated = migrateBillingSnapshotDocument({
+      organizationId: "org-1",
+      membershipRevision: '["m1","m2"]',
+      memberIds: ["m2", "m1", "m2"],
+      billableSeatCount: 3,
+      source: "checkout",
+      observedAt: 1,
+    });
+
+    expect(migrated.memberIds).toEqual(["m1", "m2"]);
+    expect(migrated.workspaceMemberCount).toBe(2);
+    expect(migrated.seatQuantity).toBe(2);
+  });
+
+  test("renames seat sync quantities without changing the operation", () => {
+    const migrated = migrateSeatSyncOperationDocument({
+      organizationId: "org-1",
+      subscriptionId: "subscription-1" as never,
+      membershipRevision: "revision-1",
+      previousSeats: 2,
+      targetSeats: 3,
+      idempotencyKey: "seat:subscription-1:revision-1",
+      status: "pending",
+      attemptCount: 0,
+      createdAt: 1,
+      updatedAt: 1,
+    });
+
+    expect(migrated.previousSeatQuantity).toBe(2);
+    expect(migrated.targetSeatQuantity).toBe(3);
+    expect(migrated).not.toHaveProperty("previousSeats");
+    expect(migrated).not.toHaveProperty("targetSeats");
+  });
+});
diff --git a/packages/backend/convex/billingMigrations.ts b/packages/backend/convex/billingMigrations.ts
new file mode 100644
index 00000000..6bff29e4
--- /dev/null
+++ b/packages/backend/convex/billingMigrations.ts
@@ -0,0 +1,182 @@
+import { internalMutation } from "./_generated/server";
+import { v } from "convex/values";
+import type { Doc } from "./_generated/dataModel";
+
+const BATCH_SIZE = 100;
+
+type WorkspaceEntitlementValue = Omit<
+  Doc<"workspaceEntitlements">,
+  "_id" | "_creationTime"
+>;
+type BillingSnapshotValue = Omit<
+  Doc<"billingSeatSnapshots">,
+  "_id" | "_creationTime"
+>;
+type SeatSyncOperationValue = Omit<
+  Doc<"billingSeatSyncOperations">,
+  "_id" | "_creationTime"
+>;
+
+type LegacyWorkspaceEntitlement = WorkspaceEntitlementValue & {
+  paidSeatCapacity?: number;
+  billableSeatCount?: number;
+};
+
+type LegacyBillingSnapshot = Omit<
+  BillingSnapshotValue,
+  "workspaceMemberCount" | "seatQuantity"
+> &
+  Partial<
+    Pick<BillingSnapshotValue, "workspaceMemberCount" | "seatQuantity">
+  > & {
+    billableSeatCount?: number;
+  };
+
+type LegacySeatSyncOperation = Omit<
+  SeatSyncOperationValue,
+  "previousSeatQuantity" | "targetSeatQuantity"
+> &
+  Partial<
+    Pick<SeatSyncOperationValue, "previousSeatQuantity" | "targetSeatQuantity">
+  > & {
+    previousSeats?: number;
+    targetSeats?: number;
+  };
+
+export function migrateWorkspaceEntitlementDocument(
+  document: LegacyWorkspaceEntitlement,
+): WorkspaceEntitlementValue {
+  return {
+    organizationId: document.organizationId,
+    plan: document.plan,
+    subscriptionStatus: document.subscriptionStatus,
+    statusReason: document.statusReason,
+    plusEnabled: document.plusEnabled,
+    sourceSubscriptionId: document.sourceSubscriptionId,
+    sourceEventId: document.sourceEventId,
+    effectiveFrom: document.effectiveFrom,
+    effectiveThrough: document.effectiveThrough,
+    policyVersion: document.policyVersion,
+    derivedAt: document.derivedAt,
+    updatedAt: document.updatedAt,
+  };
+}
+
+export function migrateBillingSnapshotDocument(
+  document: LegacyBillingSnapshot,
+): BillingSnapshotValue {
+  const memberIds = [...new Set(document.memberIds)].sort();
+  const workspaceMemberCount = memberIds.length;
+  const seatQuantity =
+    document.seatQuantity ?? Math.max(1, workspaceMemberCount);
+  return {
+    organizationId: document.organizationId,
+    subscriptionId: document.subscriptionId,
+    membershipRevision: document.membershipRevision,
+    memberIds,
+    workspaceMemberCount,
+    seatQuantity,
+    source: document.source,
+    observedAt: document.observedAt,
+  };
+}
+
+export function migrateSeatSyncOperationDocument(
+  document: LegacySeatSyncOperation,
+): SeatSyncOperationValue {
+  const previousSeatQuantity =
+    document.previousSeatQuantity ?? document.previousSeats;
+  const targetSeatQuantity =
+    document.targetSeatQuantity ?? document.targetSeats;
+  if (previousSeatQuantity === undefined || targetSeatQuantity === undefined) {
+    throw new Error("Seat sync operation has no seat quantities");
+  }
+  return {
+    organizationId: document.organizationId,
+    subscriptionId: document.subscriptionId,
+    membershipRevision: document.membershipRevision,
+    previousSeatQuantity,
+    targetSeatQuantity,
+    idempotencyKey: document.idempotencyKey,
+    status: document.status,
+    attemptCount: document.attemptCount,
+    leaseExpiresAt: document.leaseExpiresAt,
+    nextAttemptAt: document.nextAttemptAt,
+    failureCode: document.failureCode,
+    providerModifiedAt: document.providerModifiedAt,
+    createdAt: document.createdAt,
+    updatedAt: document.updatedAt,
+  };
+}
+
+const migrationTable = v.union(
+  v.literal("workspaceEntitlements"),
+  v.literal("billingSeatSnapshots"),
+  v.literal("billingSeatSyncOperations"),
+);
+
+export const migrateBatch = internalMutation({
+  args: {
+    table: migrationTable,
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const batchSize = Math.max(1, Math.min(args.batchSize ?? BATCH_SIZE, 100));
+    const cursor = args.cursor ?? null;
+
+    if (args.table === "workspaceEntitlements") {
+      const page = await ctx.db
+        .query("workspaceEntitlements")
+        .paginate({ numItems: batchSize, cursor });
+      for (const document of page.page) {
+        await ctx.db.replace(
+          document._id,
+          migrateWorkspaceEntitlementDocument(
+            document as LegacyWorkspaceEntitlement,
+          ),
+        );
+      }
+      return {
+        table: args.table,
+        processed: page.page.length,
+        isDone: page.isDone,
+        nextCursor: page.isDone ? null : page.continueCursor,
+      };
+    }
+
+    if (args.table === "billingSeatSnapshots") {
+      const page = await ctx.db
+        .query("billingSeatSnapshots")
+        .paginate({ numItems: batchSize, cursor });
+      for (const document of page.page) {
+        await ctx.db.replace(
+          document._id,
+          migrateBillingSnapshotDocument(document as LegacyBillingSnapshot),
+        );
+      }
+      return {
+        table: args.table,
+        processed: page.page.length,
+        isDone: page.isDone,
+        nextCursor: page.isDone ? null : page.continueCursor,
+      };
+    }
+
+    const page = await ctx.db
+      .query("billingSeatSyncOperations")
+      .paginate({ numItems: batchSize, cursor });
+    for (const document of page.page) {
+      await ctx.db.replace(
+        document._id,
+        migrateSeatSyncOperationDocument(document as LegacySeatSyncOperation),
+      );
+    }
+    return {
+      table: args.table,
+      processed: page.page.length,
+      isDone: page.isDone,
+      nextCursor: page.isDone ? null : page.continueCursor,
+    };
+  },
+});
diff --git a/packages/backend/convex/billingModel.ts b/packages/backend/convex/billingModel.ts
index 23d0094f..3eefcce0 100644
--- a/packages/backend/convex/billingModel.ts
+++ b/packages/backend/convex/billingModel.ts
@@ -144,7 +144,6 @@ export const terminateSubscriptionForWorkspaceDeletion = internalMutation({
         subscriptionStatus: "terminated",
         statusReason: "workspace-deletion",
         plusEnabled: false,
-        paidSeatCapacity: 0,
         effectiveThrough: args.endedAt ?? now,
         derivedAt: now,
         updatedAt: now,
@@ -367,13 +366,14 @@ export const recordCheckoutFailed = internalMutation({
   },
 });
 
-export const recordSeatSnapshot = internalMutation({
+export const recordBillingSnapshot = internalMutation({
   args: {
     organizationId: v.string(),
     subscriptionId: v.optional(v.id("billingSubscriptions")),
     membershipRevision: v.string(),
     memberIds: v.array(v.string()),
-    billableSeatCount: v.number(),
+    workspaceMemberCount: v.number(),
+    seatQuantity: v.number(),
     source: v.union(
       v.literal("checkout"),
       v.literal("membership"),
@@ -383,12 +383,14 @@ export const recordSeatSnapshot = internalMutation({
   },
   handler: async (ctx, args) => {
     if (
-      !Number.isSafeInteger(args.billableSeatCount) ||
-      args.billableSeatCount < 1 ||
-      args.memberIds.length !== args.billableSeatCount ||
-      new Set(args.memberIds).size !== args.billableSeatCount
+      !Number.isSafeInteger(args.workspaceMemberCount) ||
+      args.workspaceMemberCount < 0 ||
+      args.memberIds.length !== args.workspaceMemberCount ||
+      new Set(args.memberIds).size !== args.workspaceMemberCount ||
+      !Number.isSafeInteger(args.seatQuantity) ||
+      args.seatQuantity !== Math.max(1, args.workspaceMemberCount)
     ) {
-      throw new Error("Invalid billable seat snapshot");
+      throw new Error("Invalid workspace billing snapshot");
     }
     const duplicate = await ctx.db
       .query("billingSeatSnapshots")
@@ -412,13 +414,16 @@ export const createSeatSyncOperation = internalMutation({
     organizationId: v.string(),
     subscriptionId: v.id("billingSubscriptions"),
     membershipRevision: v.string(),
-    previousSeats: v.number(),
-    targetSeats: v.number(),
+    previousSeatQuantity: v.number(),
+    targetSeatQuantity: v.number(),
     idempotencyKey: v.string(),
   },
   handler: async (ctx, args) => {
-    for (const seats of [args.previousSeats, args.targetSeats]) {
-      if (!Number.isSafeInteger(seats) || seats < 1) {
+    for (const seatQuantity of [
+      args.previousSeatQuantity,
+      args.targetSeatQuantity,
+    ]) {
+      if (!Number.isSafeInteger(seatQuantity) || seatQuantity < 1) {
         throw new Error("Seat quantities must be positive integers");
       }
     }
@@ -434,7 +439,7 @@ export const createSeatSyncOperation = internalMutation({
       if (
         existing.subscriptionId !== args.subscriptionId ||
         existing.membershipRevision !== args.membershipRevision ||
-        existing.targetSeats !== args.targetSeats
+        existing.targetSeatQuantity !== args.targetSeatQuantity
       ) {
         throw new ConvexError({
           code: "BILLING_IDEMPOTENCY_CONFLICT",
@@ -473,7 +478,7 @@ export const completeSeatSyncOperation = internalMutation({
     const subscription = await ctx.db.get(operation.subscriptionId);
     if (subscription) {
       await ctx.db.patch(subscription._id, {
-        seatQuantity: operation.targetSeats,
+        seatQuantity: operation.targetSeatQuantity,
         providerModifiedAt: args.providerModifiedAt,
         lastReconciledAt: Date.now(),
         updatedAt: Date.now(),
diff --git a/packages/backend/convex/billing_webhook_model.ts b/packages/backend/convex/billing_webhook_model.ts
index 8e723747..d5c1a91a 100644
--- a/packages/backend/convex/billing_webhook_model.ts
+++ b/packages/backend/convex/billing_webhook_model.ts
@@ -299,13 +299,6 @@ export async function applyPolarBillingEvent(
       });
     }
     if (!subscriptionId) throw new Error("Polar subscription was not stored");
-    const latestSeatSnapshot = await ctx.db
-      .query("billingSeatSnapshots")
-      .withIndex("by_organization_observed", (query) =>
-        query.eq("organizationId", command.event.organizationId),
-      )
-      .order("desc")
-      .first();
     const entitlement = await ctx.db
       .query("workspaceEntitlements")
       .withIndex("by_organization", (query) =>
@@ -325,11 +318,6 @@ export async function applyPolarBillingEvent(
       subscriptionStatus: lifecycle.state,
       statusReason: `polar:${command.event.providerStatus}`,
       plusEnabled,
-      paidSeatCapacity: Math.max(1, command.event.seatQuantity),
-      billableSeatCount: Math.max(
-        1,
-        latestSeatSnapshot?.billableSeatCount ?? 1,
-      ),
       sourceSubscriptionId: subscriptionId,
       sourceEventId: billingEventId,
       effectiveFrom: command.event.currentPeriodStart,
diff --git a/packages/backend/convex/schema.ts b/packages/backend/convex/schema.ts
index 7059176b..989e08c4 100644
--- a/packages/backend/convex/schema.ts
+++ b/packages/backend/convex/schema.ts
@@ -15,7 +15,7 @@ import { billingTables } from "./schema/billing";
 import { aiCreditTables } from "./schema/aiCredits";
 import { storageTelemetryTables } from "./schema/storageTelemetry";
 
-export default defineSchema({
+const schema = {
   ...workspaceTables,
   ...billingTables,
   ...aiCreditTables,
@@ -562,4 +562,6 @@ export default defineSchema({
     .index("by_connection", ["connectionId"])
     .index("by_connection_external", ["connectionId", "externalId"])
     .index("by_organization_provider", ["organizationId", "provider"]),
-});
+};
+
+export default defineSchema(schema, { schemaValidation: false });
diff --git a/packages/backend/convex/schema/billing.ts b/packages/backend/convex/schema/billing.ts
index 29b817ba..34c52900 100644
--- a/packages/backend/convex/schema/billing.ts
+++ b/packages/backend/convex/schema/billing.ts
@@ -124,8 +124,6 @@ export const billingTables = {
     ),
     statusReason: v.string(),
     plusEnabled: v.boolean(),
-    paidSeatCapacity: v.number(),
-    billableSeatCount: v.number(),
     sourceSubscriptionId: v.optional(v.id("billingSubscriptions")),
     sourceEventId: v.optional(v.id("billingWebhookEvents")),
     effectiveFrom: v.number(),
@@ -218,7 +216,8 @@ export const billingTables = {
     subscriptionId: v.optional(v.id("billingSubscriptions")),
     membershipRevision: v.string(),
     memberIds: v.array(v.string()),
-    billableSeatCount: v.number(),
+    workspaceMemberCount: v.number(),
+    seatQuantity: v.number(),
     source: v.union(
       v.literal("checkout"),
       v.literal("membership"),
@@ -234,8 +233,8 @@ export const billingTables = {
     organizationId: v.string(),
     subscriptionId: v.id("billingSubscriptions"),
     membershipRevision: v.string(),
-    previousSeats: v.number(),
-    targetSeats: v.number(),
+    previousSeatQuantity: v.number(),
+    targetSeatQuantity: v.number(),
     idempotencyKey: v.string(),
     status: v.union(
       v.literal("pending"),
diff --git a/packages/backend/convex/workspaceBilling.test.ts b/packages/backend/convex/workspaceBilling.test.ts
index 999d83cc..ada8a7ae 100644
--- a/packages/backend/convex/workspaceBilling.test.ts
+++ b/packages/backend/convex/workspaceBilling.test.ts
@@ -1,12 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import { getSeatSnapshot } from "./workspaceBilling";
+import { getWorkspaceBillingSnapshot } from "./workspaceBilling";
 
 type RegisteredFunction = {
   _handler: (ctx: unknown, args: unknown) => Promise<unknown>;
 };
 
-describe("workspace billing seat snapshot", () => {
-  test("counts Better Auth members across pages and applies the paid minimum", async () => {
+describe("workspace billing snapshot", () => {
+  test("counts Better Auth members across pages and keeps the provider minimum separate", async () => {
     const pages = [
       {
         page: [{ _id: "m1", userId: "u1" }],
@@ -16,7 +16,7 @@ describe("workspace billing seat snapshot", () => {
       { page: [{ _id: "m2", userId: "u2" }], continueCursor: "", isDone: true },
     ];
     const result = await (
-      getSeatSnapshot as unknown as RegisteredFunction
+      getWorkspaceBillingSnapshot as unknown as RegisteredFunction
     )._handler(
       {
         runQuery: () => Promise.resolve(pages.shift()),
@@ -26,17 +26,16 @@ describe("workspace billing seat snapshot", () => {
 
     expect(result).toMatchObject({
       organizationId: "org-1",
-      activeMemberCount: 2,
-      billableSeatCount: 2,
+      workspaceMemberCount: 2,
+      seatQuantity: 2,
       memberIds: ["m1", "m2"],
       membershipRevision: '["m1","m2"]',
-      source: "better-auth-members",
     });
   });
 
-  test("never counts fewer than one paid seat", async () => {
+  test("keeps an empty workspace at zero members and one provider seat", async () => {
     const result = await (
-      getSeatSnapshot as unknown as RegisteredFunction
+      getWorkspaceBillingSnapshot as unknown as RegisteredFunction
     )._handler(
       {
         runQuery: () =>
@@ -45,8 +44,8 @@ describe("workspace billing seat snapshot", () => {
       { organizationId: "org-empty" },
     );
     expect(result).toMatchObject({
-      activeMemberCount: 0,
-      billableSeatCount: 1,
+      workspaceMemberCount: 0,
+      seatQuantity: 1,
     });
   });
 });
diff --git a/packages/backend/convex/workspaceBilling.ts b/packages/backend/convex/workspaceBilling.ts
index 847aa087..1917e17b 100644
--- a/packages/backend/convex/workspaceBilling.ts
+++ b/packages/backend/convex/workspaceBilling.ts
@@ -8,6 +8,15 @@ type MemberPage = {
   isDone: boolean;
 };
 
+export type WorkspaceBillingSnapshot = {
+  organizationId: string;
+  memberIds: string[];
+  workspaceMemberCount: number;
+  seatQuantity: number;
+  membershipRevision: string;
+  source: "better-auth-members";
+};
+
 /**
  * Provider-neutral seat input owned by Workspace Foundation.
  *
@@ -15,11 +24,10 @@ type MemberPage = {
  * Auth membership rules. Page guests and published visitors are deliberately
  * absent from the calculation.
  */
-export const getSeatSnapshot = internalQuery({
+export const getWorkspaceBillingSnapshot = internalQuery({
   args: { organizationId: v.string() },
   handler: async (ctx, { organizationId }) => {
     let cursor: string | null = null;
-    let activeMemberCount = 0;
     const memberIds: string[] = [];
 
     do {
@@ -33,18 +41,18 @@ export const getSeatSnapshot = internalQuery({
           paginationOpts: { numItems: 250, cursor },
         },
       )) as MemberPage;
-      activeMemberCount += result.page.length;
       memberIds.push(...result.page.map((member) => member._id));
       cursor = result.isDone ? null : result.continueCursor;
     } while (cursor !== null);
 
     memberIds.sort();
+    const workspaceMemberCount = memberIds.length;
 
     return {
       organizationId,
-      activeMemberCount,
-      billableSeatCount: Math.max(1, activeMemberCount),
       memberIds,
+      workspaceMemberCount,
+      seatQuantity: Math.max(1, workspaceMemberCount),
       membershipRevision: JSON.stringify(memberIds),
       source: "better-auth-members" as const,
     };
diff --git a/packages/i18n/src/messages/en.json b/packages/i18n/src/messages/en.json
index 35d5cd63..a12ca706 100644
--- a/packages/i18n/src/messages/en.json
+++ b/packages/i18n/src/messages/en.json
@@ -544,12 +544,10 @@
     },
     "current": {
       "title": "Current plan",
-      "memberCount": "{count, plural, =1 {1 active member} other {# active members}}",
-      "paidSeatCount": "{count, plural, =1 {1 paid seat} other {# paid seats}}",
+      "memberCount": "{count, plural, =1 {1 workspace member} other {# workspace members}}",
       "aiBalance": "{balance} available",
       "available": "Available",
       "unavailable": "Unavailable",
-      "additionalSeats": "{count, plural, =1 {1 member needs a paid seat} other {# members need paid seats}}",
       "effectiveThrough": "Entitlement confirmed through {date}"
     },
     "plans": {
@@ -557,12 +555,11 @@
       "all": "All plans",
       "current": "Current plan",
       "currentSummary": "You’re on the {plan} plan.",
-      "perMemberMonth": "per member/month",
-      "perMember": "per member/{interval}",
+      "perMember": "per workspace member/{interval}",
       "upgradeTitle": "Upgrade to Plus",
       "free": {
         "name": "Free",
-        "price": "$0",
+        "price": "$0 for the workspace",
         "features": {
           "sites": "Create and organize internal sites",
           "publishing": "Publish pages for your team",
@@ -582,11 +579,10 @@
           "month": "month",
           "year": "year"
         },
-        "pricePerMember": "{price} per member / {interval}",
+        "pricePerMember": "{price} per workspace member / {interval}",
         "features": {
           "everything": "Everything in Free",
-          "ai": "Monthly AI credits that reset each billing period",
-          "seats": "Paid seats for active workspace members"
+          "ai": "Included AI credits that reset at the end of each billing period"
         }
       },
       "comparison": {
@@ -598,17 +594,15 @@
         "publishing": "Publishing",
         "collaboration": "Collaboration",
         "ai": "AI credits",
-        "seats": "Paid seats",
         "included": "Included",
         "unlimited": "Unlimited",
         "prepaid": "Prepaid",
-        "monthly": "Monthly + prepaid",
-        "notIncluded": "—"
+        "includedAndPrepaid": "Included + prepaid"
       }
     },
     "credits": {
       "title": "AI credits",
-      "plusDescription": "Plus credits reset monthly. Purchased credits never expire.",
+      "plusDescription": "Included credits reset at the end of each billing period. Purchased credits never expire.",
       "balance": "Available balance",
       "quickAmounts": "Add credits",
       "customAmount": "Custom amount"
diff --git a/packages/i18n/src/messages/fr.json b/packages/i18n/src/messages/fr.json
index e7664bf6..bff4c1c5 100644
--- a/packages/i18n/src/messages/fr.json
+++ b/packages/i18n/src/messages/fr.json
@@ -544,12 +544,10 @@
     },
     "current": {
       "title": "Offre actuelle",
-      "memberCount": "{count, plural, =1 {1 membre actif} other {# membres actifs}}",
-      "paidSeatCount": "{count, plural, =1 {1 siège payant} other {# sièges payants}}",
+      "memberCount": "{count, plural, =1 {1 membre de l’espace} other {# membres de l’espace}}",
       "aiBalance": "{balance} disponibles",
       "available": "Disponibles",
       "unavailable": "Indisponibles",
-      "additionalSeats": "{count, plural, =1 {1 membre nécessite un siège payant} other {# membres nécessitent des sièges payants}}",
       "effectiveThrough": "Droits confirmés jusqu’au {date}"
     },
     "plans": {
@@ -557,12 +555,11 @@
       "all": "Toutes les offres",
       "current": "Offre actuelle",
       "currentSummary": "Vous utilisez l’offre {plan}.",
-      "perMemberMonth": "par membre/mois",
-      "perMember": "par membre/{interval}",
+      "perMember": "par membre de l’espace/{interval}",
       "upgradeTitle": "Passer à Plus",
       "free": {
         "name": "Gratuite",
-        "price": "0 $",
+        "price": "0 $ pour l’espace",
         "features": {
           "sites": "Créez et organisez des sites internes",
           "publishing": "Publiez des pages pour votre équipe",
@@ -582,11 +579,10 @@
           "month": "mois",
           "year": "an"
         },
-        "pricePerMember": "{price} par membre / {interval}",
+        "pricePerMember": "{price} par membre de l’espace / {interval}",
         "features": {
           "everything": "Tout ce qui est inclus dans l’offre gratuite",
-          "ai": "Crédits IA mensuels réinitialisés à chaque période de facturation",
-          "seats": "Sièges payants pour les membres actifs de l’espace"
+          "ai": "Crédits IA inclus, réinitialisés à la fin de chaque période de facturation"
         }
       },
       "comparison": {
@@ -598,17 +594,15 @@
         "publishing": "Publication",
         "collaboration": "Collaboration",
         "ai": "Crédits IA",
-        "seats": "Sièges payants",
         "included": "Inclus",
         "unlimited": "Illimité",
         "prepaid": "Prépayés",
-        "monthly": "Mensuels + prépayés",
-        "notIncluded": "—"
+        "includedAndPrepaid": "Inclus + prépayés"
       }
     },
     "credits": {
       "title": "Crédits IA",
-      "plusDescription": "Les crédits Plus sont renouvelés chaque mois. Les crédits achetés n’expirent jamais.",
+      "plusDescription": "Les crédits inclus sont réinitialisés à la fin de chaque période de facturation. Les crédits achetés n’expirent jamais.",
       "balance": "Solde disponible",
       "quickAmounts": "Ajouter des crédits",
       "customAmount": "Montant personnalisé"