fix(payments): time-slice revenue split so plan changes don't reprice historical payouts (#496)

computeOwedBalances() applied one CURRENT school_percentage to the entire
all-time sum of a tenant's platform-settled transactions. Every plan change
rewrites revenue_splits, so the next payout calculation silently repriced
every historical transaction at the new percentage, not just new sales
(e.g. a school doing $10k at 0% platform fee, then auto-downgraded to free's
10% fee, would show ~$1k less owed on that already-settled $10k than agreed
at the time of sale).

Adds transactions.school_percentage_snapshot, populated at transaction
creation time (app/api/payments/checkout/route.ts — the single insert site
that matters for payout math, since Stripe/manual/binance_personal don't
settle to the platform account and mock-checkout transactions never carry a
payment_provider that matches the payout filter). computeOwedBalances now
sums amount * that transaction's own snapshotted split, falling back to the
tenant's current split only for transactions with no snapshot (pre-#496
rows) — old data isn't retroactively wrong either way.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: guillermoscript

app/actions/platform/payouts.ts

@@ -6,7 +6,7 @@ import { isSuperAdmin } from '@/lib/supabase/get-user-role'
 import { revalidatePath } from 'next/cache'
 import { getCurrentUserId } from '@/lib/supabase/tenant'
 import { PROVIDER_CAPABILITIES, type PaymentProvider } from '@/lib/payments/types'
-import { computeOwedBalances, type TenantOwed } from '@/lib/payments/payouts-owed'
+import { computeOwedBalances, DEFAULT_SCHOOL_PERCENTAGE, type TenantOwed } from '@/lib/payments/payouts-owed'
 
 async function verifySuperAdmin() {
   const supabase = await createClient()
@@ -20,8 +20,6 @@ const PLATFORM_SETTLED_PROVIDERS = (Object.keys(PROVIDER_CAPABILITIES) as Paymen
   (provider) => PROVIDER_CAPABILITIES[provider].settlesToPlatformAccount
 )
 
-const DEFAULT_SCHOOL_PERCENTAGE = 80
-
 export async function getPayoutsOwed(): Promise<TenantOwed[]> {
   await verifySuperAdmin()
   const admin = createAdminClient()
@@ -31,7 +29,7 @@ export async function getPayoutsOwed(): Promise<TenantOwed[]> {
     admin.from('revenue_splits').select('tenant_id, school_percentage'),
     admin
       .from('transactions')
-      .select('tenant_id, payment_provider, amount')
+      .select('tenant_id, payment_provider, amount, school_percentage_snapshot')
       .eq('status', 'successful')
       .in('payment_provider', PLATFORM_SETTLED_PROVIDERS),
     admin.from('payouts').select('tenant_id, amount').eq('payout_method', 'manual').eq('status', 'paid'),
@@ -49,7 +47,12 @@ export async function getPayoutsOwed(): Promise<TenantOwed[]> {
     })),
     (txns || [])
       .filter((t) => t.tenant_id && t.payment_provider && t.amount != null)
-      .map((t) => ({ tenantId: t.tenant_id as string, paymentProvider: t.payment_provider as string, amount: t.amount as number })),
+      .map((t) => ({
+        tenantId: t.tenant_id as string,
+        paymentProvider: t.payment_provider as string,
+        amount: t.amount as number,
+        schoolPercentageSnapshot: t.school_percentage_snapshot as number | null,
+      })),
     (paid || []).map((p) => ({ tenantId: p.tenant_id, amount: p.amount }))
   )
 }

app/api/payments/checkout/route.ts

@@ -20,12 +20,14 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { createClient } from '@/lib/supabase/server'
+import { createAdminClient } from '@/lib/supabase/admin'
 import { getCurrentTenantId } from '@/lib/supabase/tenant'
 import { getPaymentProvider } from '@/lib/payments'
 import type { CreateCheckoutParams, PaymentProvider } from '@/lib/payments/types'
 import { getSolUsdPrice, usdToLamports } from '@/lib/payments/sol-price'
 import { getSolanaSettlementOptions } from '@/app/actions/admin/settings'
 import { paymentAuthLimiter } from '@/lib/rate-limit'
+import { DEFAULT_SCHOOL_PERCENTAGE } from '@/lib/payments/payouts-owed'
 import {
   findConflictingSubscription,
   PARALLEL_SUBSCRIPTION_CODE,
@@ -203,6 +205,19 @@ export async function POST(req: NextRequest) {
       }
     }
 
+    // Snapshot the tenant's CURRENT revenue split onto this transaction (#496)
+    // so a later plan change doesn't retroactively reprice it in the payouts
+    // computation — revenue_splits is super-admin-only under RLS, so this
+    // needs the admin client even though the rest of this route uses the
+    // user-scoped one.
+    const adminClientForSplit = createAdminClient()
+    const { data: revenueSplit } = await adminClientForSplit
+      .from('revenue_splits')
+      .select('school_percentage')
+      .eq('tenant_id', tenantId)
+      .maybeSingle()
+    const schoolPercentageSnapshot = revenueSplit?.school_percentage ?? DEFAULT_SCHOOL_PERCENTAGE
+
     // 1. Pending transaction — our correlation id (transaction_id) round-trips
     //    back on the webhook (LS) or the verify endpoint (Solana).
     const { data: transaction, error: txError } = await supabase
@@ -216,6 +231,7 @@ export async function POST(req: NextRequest) {
         currency,
         status: 'pending',
         payment_provider: providerSlug,
+        school_percentage_snapshot: schoolPercentageSnapshot,
         ...(settlement
           ? {
               settlement_currency: settlement.currency,

lib/payments/payouts-owed.ts

@@ -4,16 +4,29 @@
  * PLATFORM's own account (see `ProviderCapabilities.settlesToPlatformAccount`
  * in `lib/payments/types.ts`), with no automatic split like Stripe Connect or
  * Solana. The platform owner owes each school its share and pays it out
- * manually; this computes a running balance: all-time collected × the
- * tenant's school_percentage, minus all-time manual payouts already marked
- * paid. Callers pre-filter transactions to platform-settled providers only —
- * this module has no DB/provider knowledge, just arithmetic.
+ * manually; this computes a running balance: all-time collected minus
+ * all-time manual payouts already marked paid. Callers pre-filter
+ * transactions to platform-settled providers only — this module has no
+ * DB/provider knowledge, just arithmetic.
+ *
+ * Owed amounts are computed PER TRANSACTION using the split percentage that
+ * was in effect when each transaction happened (`schoolPercentageSnapshot`,
+ * snapshotted at insert time in `app/api/payments/checkout/route.ts` — see
+ * issue #496), not the tenant's current split applied retroactively to the
+ * whole sum. A plan change (which rewrites `revenue_splits`) therefore only
+ * affects transactions created after the change. Transactions predating the
+ * snapshot column (`schoolPercentageSnapshot: null`) fall back to the
+ * tenant's current `schoolPercentage` — the same behavior this module had
+ * before #496, so old data isn't retroactively wrong either way.
  */
 
+/** Used when a tenant has no `revenue_splits` row yet (shouldn't normally happen, but keeps callers from dividing by an absent value). */
+export const DEFAULT_SCHOOL_PERCENTAGE = 80
+
 export interface TenantOwedInput {
   tenantId: string
   tenantName: string
-  /** revenue_splits.school_percentage for this tenant (0–100). */
+  /** revenue_splits.school_percentage for this tenant today (0–100); used as the fallback for transactions with no snapshot. */
   schoolPercentage: number
 }
 
@@ -22,6 +35,8 @@ export interface PlatformSettledTxn {
   paymentProvider: string
   /** Successful transaction amount, major units. */
   amount: number
+  /** revenue_splits.school_percentage in effect when this transaction was created (0–100), or null for pre-#496 rows. */
+  schoolPercentageSnapshot: number | null
 }
 
 export interface ManualPayoutRecord {
@@ -35,7 +50,7 @@ export interface TenantOwed {
   schoolPercentage: number
   /** Sum of platform-settled transaction amounts (100% of what was collected). */
   grossCollected: number
-  /** grossCollected * schoolPercentage / 100 — the school's all-time share. */
+  /** Sum over transactions of amount × (that transaction's snapshotted split, or the tenant's current split if unsnapshotted) — the school's all-time share. */
   grossOwed: number
   /** Sum of manual payouts already recorded as paid for this tenant. */
   alreadyPaid: number
@@ -50,10 +65,17 @@ export function computeOwedBalances(
   txns: PlatformSettledTxn[],
   paidPayouts: ManualPayoutRecord[],
 ): TenantOwed[] {
+  const schoolPercentageByTenant = new Map(tenants.map((t) => [t.tenantId, t.schoolPercentage]))
+
   const collectedByTenant = new Map<string, number>()
+  const owedByTenant = new Map<string, number>()
   const byProviderByTenant = new Map<string, Record<string, number>>()
   for (const txn of txns) {
     collectedByTenant.set(txn.tenantId, (collectedByTenant.get(txn.tenantId) ?? 0) + txn.amount)
+
+    const effectivePercentage = txn.schoolPercentageSnapshot ?? schoolPercentageByTenant.get(txn.tenantId) ?? 0
+    owedByTenant.set(txn.tenantId, (owedByTenant.get(txn.tenantId) ?? 0) + (txn.amount * effectivePercentage) / 100)
+
     const byProvider = byProviderByTenant.get(txn.tenantId) ?? {}
     byProvider[txn.paymentProvider] = (byProvider[txn.paymentProvider] ?? 0) + txn.amount
     byProviderByTenant.set(txn.tenantId, byProvider)
@@ -66,7 +88,7 @@ export function computeOwedBalances(
 
   return tenants.map((tenant) => {
     const grossCollected = collectedByTenant.get(tenant.tenantId) ?? 0
-    const grossOwed = (grossCollected * tenant.schoolPercentage) / 100
+    const grossOwed = owedByTenant.get(tenant.tenantId) ?? 0
     const alreadyPaid = paidByTenant.get(tenant.tenantId) ?? 0
     const netOwed = Math.max(grossOwed - alreadyPaid, 0)
     return {

supabase/migrations/20260724140000_transaction_split_snapshot.sql

@@ -0,0 +1,17 @@
+-- #496: revenue_splits.school_percentage isn't time-sliced today — the
+-- payouts-owed computation applies the tenant's CURRENT split to the
+-- entire all-time sum of platform-settled transactions, so any plan change
+-- (which rewrites revenue_splits) silently reprices every historical
+-- transaction, not just new ones.
+--
+-- Snapshot the split percentage in effect at the moment each transaction is
+-- created (app/api/payments/checkout/route.ts), so a later plan change only
+-- affects future transactions. NULL for transactions created before this
+-- column existed; lib/payments/payouts-owed.ts falls back to the tenant's
+-- current split for those, matching the pre-#496 behavior for old data.
+
+ALTER TABLE transactions
+  ADD COLUMN school_percentage_snapshot numeric;
+
+COMMENT ON COLUMN transactions.school_percentage_snapshot IS
+  'revenue_splits.school_percentage in effect for this tenant when this transaction was created. NULL for transactions predating this column (#496) — payout computation falls back to the tenant''s current split for those.';

tests/unit/payouts-owed.test.ts

@@ -5,7 +5,7 @@ describe('computeOwedBalances', () => {
   it('single tenant, single provider, nothing paid yet', () => {
     const result = computeOwedBalances(
       [{ tenantId: 't1', tenantName: 'School A', schoolPercentage: 80 }],
-      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100 }],
+      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100, schoolPercentageSnapshot: null }],
       [],
     )
     expect(result).toEqual([
@@ -26,9 +26,9 @@ describe('computeOwedBalances', () => {
     const result = computeOwedBalances(
       [{ tenantId: 't1', tenantName: 'School A', schoolPercentage: 80 }],
       [
-        { tenantId: 't1', paymentProvider: 'paypal', amount: 100 },
-        { tenantId: 't1', paymentProvider: 'paypal', amount: 50 },
-        { tenantId: 't1', paymentProvider: 'binance', amount: 25 },
+        { tenantId: 't1', paymentProvider: 'paypal', amount: 100, schoolPercentageSnapshot: null },
+        { tenantId: 't1', paymentProvider: 'paypal', amount: 50, schoolPercentageSnapshot: null },
+        { tenantId: 't1', paymentProvider: 'binance', amount: 25, schoolPercentageSnapshot: null },
       ],
       [],
     )
@@ -40,7 +40,7 @@ describe('computeOwedBalances', () => {
   it('subtracts already-paid manual payouts from the gross owed', () => {
     const result = computeOwedBalances(
       [{ tenantId: 't1', tenantName: 'School A', schoolPercentage: 80 }],
-      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100 }],
+      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100, schoolPercentageSnapshot: null }],
       [{ tenantId: 't1', amount: 30 }],
     )
     expect(result[0].grossOwed).toBe(80)
@@ -51,7 +51,7 @@ describe('computeOwedBalances', () => {
   it('sums multiple manual payouts already paid', () => {
     const result = computeOwedBalances(
       [{ tenantId: 't1', tenantName: 'School A', schoolPercentage: 80 }],
-      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100 }],
+      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100, schoolPercentageSnapshot: null }],
       [{ tenantId: 't1', amount: 30 }, { tenantId: 't1', amount: 50 }],
     )
     expect(result[0].alreadyPaid).toBe(80)
@@ -61,7 +61,7 @@ describe('computeOwedBalances', () => {
   it('floors netOwed at 0 when payouts exceed what was owed (overpay/rounding)', () => {
     const result = computeOwedBalances(
       [{ tenantId: 't1', tenantName: 'School A', schoolPercentage: 80 }],
-      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100 }],
+      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100, schoolPercentageSnapshot: null }],
       [{ tenantId: 't1', amount: 500 }],
     )
     expect(result[0].netOwed).toBe(0)
@@ -85,7 +85,7 @@ describe('computeOwedBalances', () => {
   it('boundary schoolPercentage=0 → platform keeps everything, nothing owed', () => {
     const result = computeOwedBalances(
       [{ tenantId: 't1', tenantName: 'School A', schoolPercentage: 0 }],
-      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100 }],
+      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100, schoolPercentageSnapshot: null }],
       [],
     )
     expect(result[0].netOwed).toBe(0)
@@ -94,7 +94,7 @@ describe('computeOwedBalances', () => {
   it('boundary schoolPercentage=100 → school is owed the full amount collected', () => {
     const result = computeOwedBalances(
       [{ tenantId: 't1', tenantName: 'School A', schoolPercentage: 100 }],
-      [{ tenantId: 't1', paymentProvider: 'lemonsqueezy', amount: 100 }],
+      [{ tenantId: 't1', paymentProvider: 'lemonsqueezy', amount: 100, schoolPercentageSnapshot: null }],
       [],
     )
     expect(result[0].netOwed).toBe(100)
@@ -107,8 +107,8 @@ describe('computeOwedBalances', () => {
         { tenantId: 't2', tenantName: 'School B', schoolPercentage: 90 },
       ],
       [
-        { tenantId: 't1', paymentProvider: 'paypal', amount: 100 },
-        { tenantId: 't2', paymentProvider: 'paypal', amount: 200 },
+        { tenantId: 't1', paymentProvider: 'paypal', amount: 100, schoolPercentageSnapshot: null },
+        { tenantId: 't2', paymentProvider: 'paypal', amount: 200, schoolPercentageSnapshot: null },
       ],
       [{ tenantId: 't1', amount: 10 }],
     )
@@ -124,9 +124,47 @@ describe('computeOwedBalances', () => {
         { tenantId: 't1', tenantName: 'School A', schoolPercentage: 80 },
         { tenantId: 't2', tenantName: 'School B', schoolPercentage: 80 },
       ],
-      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100 }],
+      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100, schoolPercentageSnapshot: null }],
       [],
     )
     expect(result).toHaveLength(2)
   })
+
+  it('#496: a plan change after a sale does not retroactively reprice it — uses the snapshotted split, not the current one', () => {
+    // School was on business (0% fee → 100% school_percentage) when this $10k sale
+    // happened, then got auto-downgraded to free (10% fee → 90% school_percentage
+    // *today*). The historical sale must still be owed at the 100% that was live
+    // when it happened, not repriced down to 90% just because the tenant's
+    // current split changed since.
+    const result = computeOwedBalances(
+      [{ tenantId: 't1', tenantName: 'School A', schoolPercentage: 90 }],
+      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 10000, schoolPercentageSnapshot: 100 }],
+      [],
+    )
+    expect(result[0].grossOwed).toBe(10000)
+  })
+
+  it('#496: transactions predating the snapshot column fall back to the tenant\'s current split', () => {
+    const result = computeOwedBalances(
+      [{ tenantId: 't1', tenantName: 'School A', schoolPercentage: 80 }],
+      [{ tenantId: 't1', paymentProvider: 'paypal', amount: 100, schoolPercentageSnapshot: null }],
+      [],
+    )
+    expect(result[0].grossOwed).toBe(80)
+  })
+
+  it('#496: mixes snapshotted and legacy (null-snapshot) transactions correctly in the same tenant', () => {
+    const result = computeOwedBalances(
+      [{ tenantId: 't1', tenantName: 'School A', schoolPercentage: 90 }],
+      [
+        // Sold at the old 80% split — snapshotted, unaffected by the later change.
+        { tenantId: 't1', paymentProvider: 'paypal', amount: 100, schoolPercentageSnapshot: 80 },
+        // A pre-#496 legacy row with no snapshot — falls back to the current 90%.
+        { tenantId: 't1', paymentProvider: 'paypal', amount: 100, schoolPercentageSnapshot: null },
+      ],
+      [],
+    )
+    expect(result[0].grossCollected).toBe(200)
+    expect(result[0].grossOwed).toBe(80 + 90) // 100*0.8 + 100*0.9
+  })
 })