improvement(billing): make usage ledger-only and close cycles off period advance

Usage is now the attributed usage_log ledger everywhere: the userStats
baselines (currentPeriodCost / currentPeriodCopilotCost), the
includeLegacyBaseline compatibility flag, the pro-snapshot join/leave
machinery, and departedMemberUsage accrual are removed from all read and
write paths. Cycle rollover (final sub-threshold overage collection,
billedOverageThisPeriod reset, last-period bookkeeping) moves off the
invoice.finalized payload parsing — dead for org subscriptions since May —
onto a period-advance sweep with a durable per-subscription close marker
(subscription.last_closed_period_start), transaction-enlisted Stripe
outbox invoicing, and stamp-matched ledger sums. Enterprise closes are
bookkeeping-only; reporting-anchor orgs advance the marker alone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: icecrasher321

apps/sim/app/api/cron/billing-cycle-close/route.ts

@@ -0,0 +1,57 @@
+import { createLogger } from '@sim/logger'
+import { generateShortId } from '@sim/utils/id'
+import { type NextRequest, NextResponse } from 'next/server'
+import { verifyCronAuth } from '@/lib/auth/internal'
+import { sweepBillingCycleCloses } from '@/lib/billing/cycle-close'
+import { acquireLock, releaseLock } from '@/lib/core/config/redis'
+import { runDetached } from '@/lib/core/utils/background'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+
+const logger = createLogger('BillingCycleCloseCron')
+
+const LOCK_KEY = 'billing-cycle-close-lock'
+/** Lock TTL in seconds — generous enough to cover the full sweep. */
+const LOCK_TTL_SECONDS = 15 * 60
+
+export const dynamic = 'force-dynamic'
+
+/**
+ * Cron endpoint that closes elapsed billing periods (final overage collection,
+ * `billedOverageThisPeriod` reset, last-period bookkeeping). Configured in
+ * helm/sim/values.yaml under cronjobs.jobs.billingCycleClose.
+ *
+ * Acknowledges the cron call immediately and sweeps in the background; a Redis
+ * lock prevents overlapping runs, and each subscription's close is durably
+ * marked (`subscription.last_closed_period_start`), so replays are no-ops.
+ */
+export const GET = withRouteHandler(async (request: NextRequest) => {
+  const authError = verifyCronAuth(request, 'Billing cycle close')
+  if (authError) {
+    return authError
+  }
+
+  const lockValue = generateShortId()
+  const locked = await acquireLock(LOCK_KEY, lockValue, LOCK_TTL_SECONDS, {
+    reclaimOnFailure: true,
+  })
+  if (!locked) {
+    return NextResponse.json(
+      { success: true, message: 'Cycle-close sweep already in progress – skipped', status: 'skip' },
+      { status: 202 }
+    )
+  }
+
+  runDetached('billing-cycle-close', async () => {
+    try {
+      const summary = await sweepBillingCycleCloses()
+      logger.info('Billing cycle-close sweep completed', { ...summary })
+    } finally {
+      await releaseLock(LOCK_KEY, lockValue).catch(() => {})
+    }
+  })
+
+  return NextResponse.json(
+    { success: true, message: 'Billing cycle-close sweep started', status: 'started' },
+    { status: 202 }
+  )
+})

apps/sim/app/api/organizations/[id]/members/[memberId]/route.ts

@@ -89,7 +89,6 @@ export const GET = withRouteHandler(
       if (includeUsage && hasAdminAccess) {
         const usageData = await db
           .select({
-            currentPeriodCost: userStats.currentPeriodCost,
             currentUsageLimit: userStats.currentUsageLimit,
             usageLimitUpdatedAt: userStats.usageLimitUpdatedAt,
             lastPeriodCost: userStats.lastPeriodCost,
@@ -99,20 +98,19 @@ export const GET = withRouteHandler(
           .limit(1)
 
         if (usageData.length > 0) {
-          const { billingPeriod, includeLegacyBaseline, usageByUser } =
-            await getOrganizationMemberUsageSnapshot(organizationId, {
+          const { billingPeriod, usageByUser } = await getOrganizationMemberUsageSnapshot(
+            organizationId,
+            {
               executor: dbReplica,
               userIds: [memberId],
-            })
+            }
+          )
           const memberLedger = usageByUser.get(memberId) ?? 0
           memberData = {
             ...memberData,
             usage: {
               ...usageData[0],
-              currentPeriodCost: (
-                (includeLegacyBaseline ? Number(usageData[0].currentPeriodCost ?? 0) : 0) +
-                memberLedger
-              ).toString(),
+              currentPeriodCost: memberLedger.toString(),
               billingPeriodStart: billingPeriod?.start ?? null,
               billingPeriodEnd: billingPeriod?.end ?? null,
             },

apps/sim/app/api/organizations/[id]/members/route.ts

@@ -101,7 +101,6 @@ export const GET = withRouteHandler(
               createdAt: member.createdAt,
               userName: user.name,
               userEmail: user.email,
-              currentPeriodCost: userStats.currentPeriodCost,
               currentUsageLimit: userStats.currentUsageLimit,
               usageLimitUpdatedAt: userStats.usageLimitUpdatedAt,
             })
@@ -115,19 +114,18 @@ export const GET = withRouteHandler(
           totalQuery,
         ])
 
-        const { billingPeriod, includeLegacyBaseline, usageByUser } =
-          await getOrganizationMemberUsageSnapshot(organizationId, {
+        const { billingPeriod, usageByUser } = await getOrganizationMemberUsageSnapshot(
+          organizationId,
+          {
             userIds: base.map((row) => row.userId),
-          })
+          }
+        )
         const billingPeriodStart = billingPeriod?.start ?? null
         const billingPeriodEnd = billingPeriod?.end ?? null
 
         const membersWithUsage = base.map((row) => ({
           ...row,
-          currentPeriodCost: (
-            (includeLegacyBaseline ? Number(row.currentPeriodCost ?? 0) : 0) +
-            (usageByUser.get(row.userId) ?? 0)
-          ).toString(),
+          currentPeriodCost: (usageByUser.get(row.userId) ?? 0).toString(),
           billingPeriodStart,
           billingPeriodEnd,
         }))

apps/sim/app/api/v1/admin/organizations/[id]/members/[memberId]/route.ts

@@ -90,7 +90,6 @@ export const GET = withRouteHandler(
           createdAt: member.createdAt,
           userName: user.name,
           userEmail: user.email,
-          currentPeriodCost: userStats.currentPeriodCost,
           currentUsageLimit: userStats.currentUsageLimit,
           billingBlocked: userStats.billingBlocked,
         })
@@ -104,10 +103,9 @@ export const GET = withRouteHandler(
         return notFoundResponse('Member')
       }
 
-      const { includeLegacyBaseline, usageByUser } = await getOrganizationMemberUsageSnapshot(
-        organizationId,
-        { userIds: [memberData.userId] }
-      )
+      const { usageByUser } = await getOrganizationMemberUsageSnapshot(organizationId, {
+        userIds: [memberData.userId],
+      })
 
       const data: AdminMemberDetail = {
         id: memberData.id,
@@ -117,10 +115,7 @@ export const GET = withRouteHandler(
         createdAt: memberData.createdAt.toISOString(),
         userName: memberData.userName,
         userEmail: memberData.userEmail,
-        currentPeriodCost: (
-          (includeLegacyBaseline ? Number(memberData.currentPeriodCost ?? 0) : 0) +
-          (usageByUser.get(memberData.userId) ?? 0)
-        ).toString(),
+        currentPeriodCost: (usageByUser.get(memberData.userId) ?? 0).toString(),
         currentUsageLimit: memberData.currentUsageLimit,
         billingBlocked: memberData.billingBlocked ?? false,
       }

apps/sim/app/api/v1/admin/organizations/[id]/members/route.ts

@@ -118,7 +118,6 @@ export const GET = withRouteHandler(
             createdAt: member.createdAt,
             userName: user.name,
             userEmail: user.email,
-            currentPeriodCost: userStats.currentPeriodCost,
             currentUsageLimit: userStats.currentUsageLimit,
             billingBlocked: userStats.billingBlocked,
           })
@@ -133,12 +132,9 @@ export const GET = withRouteHandler(
 
       const total = countResult[0].count
 
-      const { includeLegacyBaseline, usageByUser } = await getOrganizationMemberUsageSnapshot(
-        organizationId,
-        {
-          userIds: membersData.map((row) => row.userId),
-        }
-      )
+      const { usageByUser } = await getOrganizationMemberUsageSnapshot(organizationId, {
+        userIds: membersData.map((row) => row.userId),
+      })
 
       const data: AdminMemberDetail[] = membersData.map((m) => ({
         id: m.id,
@@ -148,10 +144,7 @@ export const GET = withRouteHandler(
         createdAt: m.createdAt.toISOString(),
         userName: m.userName,
         userEmail: m.userEmail,
-        currentPeriodCost: (
-          (includeLegacyBaseline ? Number(m.currentPeriodCost ?? 0) : 0) +
-          (usageByUser.get(m.userId) ?? 0)
-        ).toString(),
+        currentPeriodCost: (usageByUser.get(m.userId) ?? 0).toString(),
         currentUsageLimit: m.currentUsageLimit,
         billingBlocked: m.billingBlocked ?? false,
       }))

apps/sim/app/api/v1/admin/users/[id]/billing/route.ts

@@ -12,7 +12,8 @@
  * Body:
  *   - currentUsageLimit?: number | null - Usage limit (null to use default)
  *   - billingBlocked?: boolean - Block/unblock billing
- *   - currentPeriodCost?: number - Reset/adjust current period cost (use with caution)
+ *   - currentPeriodCost?: number - Deprecated no-op: usage is the attributed
+ *     usage_log ledger and cannot be adjusted here
  *   - reason?: string - Reason for the change (for audit logging)
  *
  * Response: AdminSingleResponse<{ success: true, updated: string[], warnings: string[] }>
@@ -79,9 +80,8 @@ export const GET = withRouteHandler(
 
       const [stats] = await db.select().from(userStats).where(eq(userStats.userId, userId)).limit(1)
 
-      // currentPeriodCost is now only a baseline; canonical current-period usage
-      // (baseline + attributed usage_log, refresh-adjusted) comes from the same
-      // helper users see, so admin reflects real usage instead of a stale 0.
+      // Canonical current-period usage (attributed usage_log, refresh-adjusted)
+      // comes from the same helper users see.
       const usage = await getUserUsageData(userId)
 
       const memberOrgs = await db
@@ -197,10 +197,10 @@ export const PATCH = withRouteHandler(
         if (currentUsageLimit === null) {
           updateData.currentUsageLimit = null
         } else {
-          const currentCost = Number.parseFloat(existingStats?.currentPeriodCost || '0')
-          if (currentUsageLimit < currentCost) {
+          const { currentUsage } = await getUserUsageData(userId)
+          if (currentUsageLimit < currentUsage) {
             warnings.push(
-              `New limit ($${currentUsageLimit.toFixed(2)}) is below current usage ($${currentCost.toFixed(2)}). User may be immediately blocked.`
+              `New limit ($${currentUsageLimit.toFixed(2)}) is below current usage ($${currentUsage.toFixed(2)}). User may be immediately blocked.`
             )
           }
           updateData.currentUsageLimit = currentUsageLimit.toFixed(2)
@@ -225,13 +225,9 @@ export const PATCH = withRouteHandler(
       }
 
       if (currentPeriodCost !== undefined) {
-        const previousCost = existingStats?.currentPeriodCost || '0'
         warnings.push(
-          `Manually adjusting currentPeriodCost from $${previousCost} to $${currentPeriodCost.toFixed(2)}. This may affect billing accuracy.`
+          'currentPeriodCost adjustments are deprecated: usage is the attributed usage_log ledger and cannot be edited here. The field was ignored.'
         )
-
-        updateData.currentPeriodCost = currentPeriodCost.toFixed(2)
-        updated.push('currentPeriodCost')
       }
 
       if (updated.length === 0) {
@@ -256,7 +252,6 @@ export const PATCH = withRouteHandler(
           ? {
               currentUsageLimit: existingStats.currentUsageLimit,
               billingBlocked: existingStats.billingBlocked,
-              currentPeriodCost: existingStats.currentPeriodCost,
             }
           : null,
         newValues: updateData,

apps/sim/lib/admin/dashboard-organizations.test.ts

@@ -291,13 +291,13 @@ describe('listDashboardOrganizations', () => {
       externalCollaboratorCount: 0,
       planLabel: 'No plan',
     })
-    // Pagination, membership/collaborators, and two batched usage aggregates.
+    // Pagination, membership/collaborators, and the batched ledger aggregate.
     // This count remains constant regardless of the number of organizations.
-    expect(dbChainMockFns.select).toHaveBeenCalledTimes(6)
+    expect(dbChainMockFns.select).toHaveBeenCalledTimes(5)
     expect(dbChainMockFns.selectDistinctOn).toHaveBeenCalledTimes(1)
   })
 
-  it('preserves the frozen baseline for an Enterprise subscription using its Stripe period', async () => {
+  it('reports ledger usage for an Enterprise subscription using its Stripe period', async () => {
     queueTableRows(organization, [{ total: 1 }])
     queueTableRows(organization, [
       { id: 'org-1', name: 'One', orgUsageLimit: '100', creditBalance: '0' },
@@ -325,13 +325,12 @@ describe('listDashboardOrganizations', () => {
       },
     ])
     queueTableRows(usageLog, [{ organizationId: 'org-1', cost: '2.5', workflowRuns: 3 }])
-    queueTableRows(member, [{ organizationId: 'org-1', cost: '1.5' }])
 
     const result = await listDashboardOrganizations({ search: '', limit: 50, offset: 0 })
 
     expect(result.data[0]).toMatchObject({
       reportingPeriod: { source: 'stripe' },
-      usage: { usedDollars: 4, workflowRuns: 3 },
+      usage: { usedDollars: 2.5, workflowRuns: 3 },
     })
   })
 

apps/sim/lib/admin/dashboard.ts

@@ -254,24 +254,6 @@ async function getDashboardOrganizationUsage(
       }
     }
 
-    const legacyOrganizationIds = contexts
-      .filter((context) => context.period.source !== 'reporting')
-      .map((context) => context.organizationId)
-    if (legacyOrganizationIds.length > 0) {
-      const baselineTotals = await db
-        .select({
-          organizationId: member.organizationId,
-          cost: sql<string>`coalesce(sum(${userStats.currentPeriodCost}), 0)`,
-        })
-        .from(member)
-        .leftJoin(userStats, eq(userStats.userId, member.userId))
-        .where(inArray(member.organizationId, legacyOrganizationIds))
-        .groupBy(member.organizationId)
-      for (const row of baselineTotals) {
-        const usage = result.get(row.organizationId)
-        if (usage) usage.total += Number(row.cost)
-      }
-    }
     return result
   }
 
@@ -307,34 +289,6 @@ async function getDashboardOrganizationUsage(
     )
   }
 
-  const legacyOrganizationIds = contexts
-    .filter((context) => context.period.source !== 'reporting')
-    .map((context) => context.organizationId)
-  if (legacyOrganizationIds.length > 0) {
-    const baselineRows = await db
-      .select({
-        organizationId: member.organizationId,
-        userId: member.userId,
-        cost: userStats.currentPeriodCost,
-      })
-      .from(member)
-      .leftJoin(userStats, eq(userStats.userId, member.userId))
-      .where(
-        options.userIds
-          ? and(
-              inArray(member.organizationId, legacyOrganizationIds),
-              inArray(member.userId, options.userIds)
-            )
-          : inArray(member.organizationId, legacyOrganizationIds)
-      )
-    for (const row of baselineRows) {
-      const usage = result.get(row.organizationId)
-      if (!usage) continue
-      const amount = Number(row.cost ?? 0)
-      usage.total += amount
-      usage.byUser.set(row.userId, (usage.byUser.get(row.userId) ?? 0) + amount)
-    }
-  }
   return result
 }
 
@@ -661,22 +615,6 @@ export async function listDashboardUsers({ search, limit, offset }: PaginationIn
         : []
     )
   )
-  const legacyPersonalIds = personalUserIds.filter(
-    (userId) => personalPeriods.get(userId)?.source !== 'reporting'
-  )
-  if (legacyPersonalIds.length > 0) {
-    const baselineRows = await db
-      .select({ userId: userStats.userId, cost: userStats.currentPeriodCost })
-      .from(userStats)
-      .where(inArray(userStats.userId, legacyPersonalIds))
-    for (const row of baselineRows) {
-      const current = personalUsage.get(row.userId) ?? { dollars: 0, workflowRuns: 0 }
-      personalUsage.set(row.userId, {
-        ...current,
-        dollars: current.dollars + Number(row.cost ?? 0),
-      })
-    }
-  }
 
   return {
     data: rows.map((row) => {

apps/sim/lib/api/contracts/v1/admin/organizations.ts

@@ -137,6 +137,7 @@ export const adminV1TransferOwnershipBodySchema = z.object({
 const adminV1OrganizationMemberMutationResultSchema = adminV1MemberSchema.extend({
   action: z.enum(['created', 'updated', 'already_member']),
   billingActions: z.object({
+    /** @deprecated Always false — ledger entity stamps replaced join-time snapshots. */
     proUsageSnapshotted: z.boolean(),
     proCancelledAtPeriodEnd: z.boolean(),
   }),
@@ -147,9 +148,10 @@ const adminV1RemoveOrganizationMemberResultSchema = z.object({
   memberId: z.string(),
   userId: z.string(),
   billingActions: z.object({
-    /** Dollar amount of departed-member usage captured (0 when none). */
+    /** @deprecated Always 0 — a departed member's ledger rows stay stamped to the org's period. */
     usageCaptured: z.number(),
     proRestored: z.boolean(),
+    /** @deprecated Always false — no snapshot exists to restore. */
     usageRestored: z.boolean(),
     skipBillingLogic: z.boolean(),
   }),