improvement(billing): route scope by subscription referenceId, sync plan from Stripe, transfer storage on org join, outbox service (#4219)

* fix(billing): route scope by subscription referenceId, sync plan from Stripe, transfer storage on org join

Route every billing decision (usage limits, credits, storage, rate
limit, threshold billing, webhooks, UI permissions) through the
subscription's `referenceId` instead of plan-name heuristics. Fixes
the production state where a `pro_6000` subscription attached to an
organization was treated as personal Pro by display/edit code while
execution correctly enforced the org cap.

Scope
- Add `isOrgScopedSubscription(sub, userId)` (pure) and
  `isSubscriptionOrgScoped(sub)` (async DB-backed) helpers. One is
  used wherever a user perspective is available; the other in webhook
  handlers that only have a subscription row.
- Replace plan-name scope checks in ~20 files: usage/limit readers,
  credits balance + purchase, threshold billing, storage limits +
  tracking, rate limiter, invoice + subscription webhooks, seat
  management, membership join/leave, `switch-plan` admin gate,
  admin credits/billing routes, copilot 402 handler, UI subscription
  settings + permissions + sidebar indicator, React Query types.

Plan sync
- Add `syncSubscriptionPlan(subscriptionId, currentPlan, planFromStripe)`
  called from `onSubscriptionComplete` and `onSubscriptionUpdate` so
  the DB `plan` column heals on every Stripe event. Pro->Team upgrades
  previously updated price, seats, and referenceId but left `plan`
  stale — this is what produced the `pro_6000`-on-org row.

Priority + grace period
- `getHighestPrioritySubscription` now prefers org over personal
  within each tier (Enterprise > Team > Pro, org > personal at each).
  A user with a `cancelAtPeriodEnd` personal Pro who joins a paid org
  routes pooled resources to the org through the grace window.
- `calculateSubscriptionOverage` personal-Pro branch reads user_stats
  directly (bypassing priority) and bills only `proPeriodCostSnapshot`
  when the user joined a paid org mid-cycle, so post-join org usage
  isn't double-charged on the personal Pro's final invoice.
  `resetUsageForSubscription` mirrors this: preserves
  `currentPeriodCost` / `currentPeriodCopilotCost` when
  `proPeriodCostSnapshot > 0` so the org's next cycle-close captures
  post-join usage correctly.

Uniform base-price formula
- `basePrice × (seats ?? 1)` everywhere: `getOrgUsageLimit`,
  `updateOrganizationUsageLimit`, `setUsageLimitForCredits`,
  `calculateSubscriptionOverage`, threshold billing,
  `syncSubscriptionUsageLimits`, `getOrganizationBillingData`.
  Admin dashboard math now agrees with enforcement math.

Storage transfer on join
- Invitation-accept flow moves `user_stats.storageUsedBytes` into
  `organization.storageUsedBytes` inside the same transaction when
  the org is paid.
- `syncSubscriptionUsageLimits` runs a bulk-backfill version so
  members who joined before this fix, or orgs that upgraded from
  free to paid after members joined, get pulled into the org pool
  on the next subscription event. Idempotent.

UX polish
- Copilot 402 handler differentiates personal-scoped ("increase your
  usage limit") from org-scoped ("ask an owner or admin to raise the
  limit") while keeping the `increase_limit` action code the parser
  already understands.
- Duplicate-subscription error on team upgrade names the existing
  plan via `getDisplayPlanName`.
- Invitation-accept invalidates subscription + organization React
  Query caches before redirect so settings doesn't flash the user's
  pre-join personal view.

Dead code removal
- Remove unused `calculateUserOverage`, and the following fields on
  `SubscriptionBillingData` / `getSimplifiedBillingSummary` that no
  consumer in the monorepo read: `basePrice`, `overageAmount`,
  `totalProjected`, `tierCredits`, `basePriceCredits`,
  `currentUsageCredits`, `overageAmountCredits`, `totalProjectedCredits`,
  `usageLimitCredits`, `currentCredits`, `limitCredits`,
  `lastPeriodCostCredits`, `lastPeriodCopilotCostCredits`,
  `copilotCostCredits`, and the `organizationData` subobject. Add
  `metadata: unknown` to match what the server returns.

Notes for the triggering customer
- The `pro_6000`-on-org row self-heals on the next Stripe event via
  `syncSubscriptionPlan`. For the one known customer, a direct
  UPDATE is sufficient:
  `UPDATE subscription SET plan='team_6000' WHERE id='aq2...' AND plan='pro_6000'`.

Made-with: Cursor

* fix tests

* address more comments

* progress

* harden further

* outbox service

* address comments

* address comment on check

* simplify

* cleanup code

* minor improvement

Author: icecrasher321

apps/sim/app/api/billing/route.ts

@@ -7,8 +7,6 @@ import { getSession } from '@/lib/auth'
 import { getEffectiveBillingStatus } from '@/lib/billing/core/access'
 import { getSimplifiedBillingSummary } from '@/lib/billing/core/billing'
 import { getOrganizationBillingData } from '@/lib/billing/core/organization'
-import { dollarsToCredits } from '@/lib/billing/credits/conversion'
-import { getPlanTierCredits } from '@/lib/billing/plan-helpers'
 
 const logger = createLogger('UnifiedBillingAPI')
 
@@ -47,7 +45,20 @@ export async function GET(request: NextRequest) {
     let billingData
 
     if (context === 'user') {
-      // Get user billing and billing blocked status in parallel
+      if (contextId) {
+        const membership = await db
+          .select({ role: member.role })
+          .from(member)
+          .where(and(eq(member.organizationId, contextId), eq(member.userId, session.user.id)))
+          .limit(1)
+        if (membership.length === 0) {
+          return NextResponse.json(
+            { error: 'Access denied - not a member of this organization' },
+            { status: 403 }
+          )
+        }
+      }
+
       const [billingResult, billingStatus] = await Promise.all([
         getSimplifiedBillingSummary(session.user.id, contextId || undefined),
         getEffectiveBillingStatus(session.user.id),
@@ -107,7 +118,6 @@ export async function GET(request: NextRequest) {
         )
       }
 
-      // Transform data to match component expectations
       billingData = {
         organizationId: rawBillingData.organizationId,
         organizationName: rawBillingData.organizationName,
@@ -122,17 +132,10 @@ export async function GET(request: NextRequest) {
         averageUsagePerMember: rawBillingData.averageUsagePerMember,
         billingPeriodStart: rawBillingData.billingPeriodStart?.toISOString() || null,
         billingPeriodEnd: rawBillingData.billingPeriodEnd?.toISOString() || null,
-        tierCredits: getPlanTierCredits(rawBillingData.subscriptionPlan),
-        totalCurrentUsageCredits: dollarsToCredits(rawBillingData.totalCurrentUsage),
-        totalUsageLimitCredits: dollarsToCredits(rawBillingData.totalUsageLimit),
-        minimumBillingAmountCredits: dollarsToCredits(rawBillingData.minimumBillingAmount),
-        averageUsagePerMemberCredits: dollarsToCredits(rawBillingData.averageUsagePerMember),
         members: rawBillingData.members.map((m) => ({
           ...m,
           joinedAt: m.joinedAt.toISOString(),
           lastActive: m.lastActive?.toISOString() || null,
-          currentUsageCredits: dollarsToCredits(m.currentUsage),
-          usageLimitCredits: dollarsToCredits(m.usageLimit),
         })),
       }
 

apps/sim/app/api/billing/switch-plan/route.ts

@@ -9,12 +9,13 @@ import { getEffectiveBillingStatus } from '@/lib/billing/core/access'
 import { isOrganizationOwnerOrAdmin } from '@/lib/billing/core/organization'
 import { getHighestPrioritySubscription } from '@/lib/billing/core/plan'
 import { writeBillingInterval } from '@/lib/billing/core/subscription'
-import { getPlanType, isEnterprise, isOrgPlan } from '@/lib/billing/plan-helpers'
+import { getPlanType, isEnterprise } from '@/lib/billing/plan-helpers'
 import { getPlanByName } from '@/lib/billing/plans'
 import { requireStripeClient } from '@/lib/billing/stripe-client'
 import {
   hasUsableSubscriptionAccess,
   hasUsableSubscriptionStatus,
+  isOrgScopedSubscription,
 } from '@/lib/billing/subscriptions/utils'
 import { isBillingEnabled } from '@/lib/core/config/feature-flags'
 import { toError } from '@/lib/core/utils/helpers'
@@ -93,7 +94,7 @@ export async function POST(request: NextRequest) {
       )
     }
 
-    if (isOrgPlan(sub.plan)) {
+    if (isOrgScopedSubscription(sub, userId)) {
       const hasPermission = await isOrganizationOwnerOrAdmin(userId, sub.referenceId)
       if (!hasPermission) {
         return NextResponse.json({ error: 'Only team admins can change the plan' }, { status: 403 })

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

@@ -14,17 +14,18 @@ import {
   workspaceInvitation,
 } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
-import { and, eq, inArray } from 'drizzle-orm'
+import { and, eq, inArray, sql } from 'drizzle-orm'
 import { type NextRequest, NextResponse } from 'next/server'
 import { z } from 'zod'
 import { getEmailSubject, renderInvitationEmail } from '@/components/emails'
 import { AuditAction, AuditResourceType, recordAudit } from '@/lib/audit/log'
 import { getSession } from '@/lib/auth'
 import { hasAccessControlAccess } from '@/lib/billing'
 import { syncUsageLimitsFromSubscription } from '@/lib/billing/core/usage'
-import { isOrgPlan, sqlIsPro } from '@/lib/billing/plan-helpers'
-import { requireStripeClient } from '@/lib/billing/stripe-client'
+import { isPaid, sqlIsPro } from '@/lib/billing/plan-helpers'
 import { ENTITLED_SUBSCRIPTION_STATUSES } from '@/lib/billing/subscriptions/utils'
+import { OUTBOX_EVENT_TYPES } from '@/lib/billing/webhooks/outbox-handlers'
+import { enqueueOutboxEvent } from '@/lib/core/outbox/service'
 import { getBaseUrl } from '@/lib/core/utils/urls'
 import { generateId } from '@/lib/core/utils/uuid'
 import { syncWorkspaceEnvCredentials } from '@/lib/credentials/environment'
@@ -328,8 +329,6 @@ export async function PUT(
       }
     }
 
-    let personalProToCancel: any = null
-
     await db.transaction(async (tx) => {
       await tx.update(invitation).set({ status }).where(eq(invitation.id, invitationId))
 
@@ -342,8 +341,7 @@ export async function PUT(
           createdAt: new Date(),
         })
 
-        // Snapshot Pro usage and cancel Pro subscription when joining a paid team
-        try {
+        {
           const orgSubs = await tx
             .select()
             .from(subscriptionTable)
@@ -356,7 +354,7 @@ export async function PUT(
             .limit(1)
 
           const orgSub = orgSubs[0]
-          const orgIsPaid = orgSub && isOrgPlan(orgSub.plan)
+          const orgIsPaid = orgSub && isPaid(orgSub.plan)
 
           if (orgIsPaid) {
             const userId = session.user.id
@@ -393,8 +391,9 @@ export async function PUT(
                   .update(userStats)
                   .set({
                     proPeriodCostSnapshot: currentProUsage,
-                    currentPeriodCost: '0', // Reset so new usage is attributed to team
-                    currentPeriodCopilotCost: '0', // Reset copilot cost for new period
+                    proPeriodCostSnapshotAt: new Date(),
+                    currentPeriodCost: '0',
+                    currentPeriodCopilotCost: '0',
                   })
                   .where(eq(userStats.userId, userId))
 
@@ -405,19 +404,48 @@ export async function PUT(
                 })
               }
 
-              // Mark for cancellation after transaction
-              if (personalPro.cancelAtPeriodEnd !== true) {
-                personalProToCancel = personalPro
+              if (personalPro.cancelAtPeriodEnd !== true && personalPro.stripeSubscriptionId) {
+                await tx
+                  .update(subscriptionTable)
+                  .set({ cancelAtPeriodEnd: true })
+                  .where(eq(subscriptionTable.id, personalPro.id))
+
+                await enqueueOutboxEvent(tx, OUTBOX_EVENT_TYPES.STRIPE_SYNC_CANCEL_AT_PERIOD_END, {
+                  stripeSubscriptionId: personalPro.stripeSubscriptionId,
+                  subscriptionId: personalPro.id,
+                  reason: 'member-joined-paid-org',
+                })
               }
             }
+
+            const storageRows = await tx
+              .select({ storageUsedBytes: userStats.storageUsedBytes })
+              .from(userStats)
+              .where(eq(userStats.userId, userId))
+              .for('update')
+              .limit(1)
+
+            const bytesToTransfer = storageRows[0]?.storageUsedBytes ?? 0
+            if (bytesToTransfer > 0) {
+              await tx
+                .update(organization)
+                .set({
+                  storageUsedBytes: sql`${organization.storageUsedBytes} + ${bytesToTransfer}`,
+                })
+                .where(eq(organization.id, organizationId))
+
+              await tx
+                .update(userStats)
+                .set({ storageUsedBytes: 0 })
+                .where(eq(userStats.userId, userId))
+
+              logger.info('Transferred personal storage bytes to org pool on join', {
+                userId,
+                organizationId,
+                bytes: bytesToTransfer,
+              })
+            }
           }
-        } catch (error) {
-          logger.error('Failed to handle Pro user joining team', {
-            userId: session.user.id,
-            organizationId,
-            error,
-          })
-          // Don't fail the whole invitation acceptance due to this
         }
 
         // Auto-assign to permission group if one has autoAddNewMembers enabled
@@ -557,44 +585,6 @@ export async function PUT(
       }
     }
 
-    // Handle Pro subscription cancellation after transaction commits
-    if (personalProToCancel) {
-      try {
-        const stripe = requireStripeClient()
-        if (personalProToCancel.stripeSubscriptionId) {
-          try {
-            await stripe.subscriptions.update(personalProToCancel.stripeSubscriptionId, {
-              cancel_at_period_end: true,
-            })
-          } catch (stripeError) {
-            logger.error('Failed to set cancel_at_period_end on Stripe for personal Pro', {
-              userId: session.user.id,
-              subscriptionId: personalProToCancel.id,
-              stripeSubscriptionId: personalProToCancel.stripeSubscriptionId,
-              error: stripeError,
-            })
-          }
-        }
-
-        await db
-          .update(subscriptionTable)
-          .set({ cancelAtPeriodEnd: true })
-          .where(eq(subscriptionTable.id, personalProToCancel.id))
-
-        logger.info('Auto-cancelled personal Pro at period end after joining paid team', {
-          userId: session.user.id,
-          personalSubscriptionId: personalProToCancel.id,
-          organizationId,
-        })
-      } catch (dbError) {
-        logger.error('Failed to update DB cancelAtPeriodEnd for personal Pro', {
-          userId: session.user.id,
-          subscriptionId: personalProToCancel.id,
-          error: dbError,
-        })
-      }
-    }
-
     if (status === 'accepted') {
       try {
         await syncUsageLimitsFromSubscription(session.user.id)

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

@@ -1,12 +1,19 @@
 import { db } from '@sim/db'
-import { invitation, member, organization, user, userStats } from '@sim/db/schema'
+import {
+  invitation,
+  member,
+  organization,
+  subscription as subscriptionTable,
+  user,
+  userStats,
+} from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
-import { and, eq } from 'drizzle-orm'
+import { and, eq, inArray } from 'drizzle-orm'
 import { type NextRequest, NextResponse } from 'next/server'
 import { getEmailSubject, renderInvitationEmail } from '@/components/emails'
 import { AuditAction, AuditResourceType, recordAudit } from '@/lib/audit/log'
 import { getSession } from '@/lib/auth'
-import { getUserUsageData } from '@/lib/billing/core/usage'
+import { ENTITLED_SUBSCRIPTION_STATUSES } from '@/lib/billing/subscriptions/utils'
 import { validateSeatAvailability } from '@/lib/billing/validation/seat-management'
 import { getBaseUrl } from '@/lib/core/utils/urls'
 import { generateId } from '@/lib/core/utils/uuid'
@@ -83,16 +90,32 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
         .leftJoin(userStats, eq(user.id, userStats.userId))
         .where(eq(member.organizationId, organizationId))
 
-      const membersWithUsage = await Promise.all(
-        base.map(async (row) => {
-          const usage = await getUserUsageData(row.userId)
-          return {
-            ...row,
-            billingPeriodStart: usage.billingPeriodStart,
-            billingPeriodEnd: usage.billingPeriodEnd,
-          }
+      // The billing period is the same for every member — it comes from
+      // whichever subscription covers them. Fetch once and attach to
+      // every row instead of calling `getUserUsageData` per-member,
+      // which would run an O(N) pooled query for each of N rows.
+      const [orgSub] = await db
+        .select({
+          periodStart: subscriptionTable.periodStart,
+          periodEnd: subscriptionTable.periodEnd,
         })
-      )
+        .from(subscriptionTable)
+        .where(
+          and(
+            eq(subscriptionTable.referenceId, organizationId),
+            inArray(subscriptionTable.status, ENTITLED_SUBSCRIPTION_STATUSES)
+          )
+        )
+        .limit(1)
+
+      const billingPeriodStart = orgSub?.periodStart ?? null
+      const billingPeriodEnd = orgSub?.periodEnd ?? null
+
+      const membersWithUsage = base.map((row) => ({
+        ...row,
+        billingPeriodStart,
+        billingPeriodEnd,
+      }))
 
       return NextResponse.json({
         success: true,

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

@@ -13,6 +13,8 @@ import {
   hasUsableSubscriptionStatus,
   USABLE_SUBSCRIPTION_STATUSES,
 } from '@/lib/billing/subscriptions/utils'
+import { toDecimal, toNumber } from '@/lib/billing/utils/decimal'
+import { syncSeatsFromStripeQuantity } from '@/lib/billing/validation/seat-management'
 import { isBillingEnabled } from '@/lib/core/config/feature-flags'
 
 const logger = createLogger('OrganizationSeatsAPI')
@@ -164,8 +166,6 @@ export async function PUT(request: NextRequest, { params }: { params: Promise<{
       userId: session.user.id,
     })
 
-    // Update the subscription item quantity using Stripe's recommended approach
-    // This will automatically prorate the billing
     const updatedSubscription = await stripe.subscriptions.update(
       orgSubscription.stripeSubscriptionId,
       {
@@ -176,19 +176,16 @@ export async function PUT(request: NextRequest, { params }: { params: Promise<{
           },
         ],
         proration_behavior: 'always_invoice',
-      }
+      },
+      { idempotencyKey: `seats-update:${orgSubscription.stripeSubscriptionId}:${newSeatCount}` }
     )
 
-    // Update our local database to reflect the change
-    // Note: This will also be updated via webhook, but we update immediately for UX
-    await db
-      .update(subscription)
-      .set({
-        seats: newSeatCount,
-      })
-      .where(eq(subscription.id, orgSubscription.id))
+    await syncSeatsFromStripeQuantity(
+      orgSubscription.id,
+      orgSubscription.seats,
+      updatedSubscription.items.data[0]?.quantity ?? newSeatCount
+    )
 
-    // Update orgUsageLimit to reflect new seat count (seats × basePrice as minimum)
     const { basePrice } = getPlanPricing(orgSubscription.plan)
     const newMinimumLimit = newSeatCount * basePrice
 
@@ -200,7 +197,7 @@ export async function PUT(request: NextRequest, { params }: { params: Promise<{
 
     const currentOrgLimit =
       orgData.length > 0 && orgData[0].orgUsageLimit
-        ? Number.parseFloat(orgData[0].orgUsageLimit)
+        ? toNumber(toDecimal(orgData[0].orgUsageLimit))
         : 0
 
     // Update if new minimum is higher than current limit

apps/sim/app/api/v1/admin/credits/route.ts

@@ -30,10 +30,11 @@ import { and, eq, inArray } from 'drizzle-orm'
 import { getHighestPrioritySubscription } from '@/lib/billing/core/subscription'
 import { addCredits } from '@/lib/billing/credits/balance'
 import { setUsageLimitForCredits } from '@/lib/billing/credits/purchase'
-import { isOrgPlan, isPaid } from '@/lib/billing/plan-helpers'
+import { isPaid } from '@/lib/billing/plan-helpers'
 import {
   ENTITLED_SUBSCRIPTION_STATUSES,
   getEffectiveSeats,
+  isOrgScopedSubscription,
 } from '@/lib/billing/subscriptions/utils'
 import { generateShortId } from '@/lib/core/utils/uuid'
 import { withAdminAuth } from '@/app/api/v1/admin/middleware'
@@ -110,7 +111,8 @@ export const POST = withAdminAuth(async (request) => {
     const plan = userSubscription.plan
     let seats: number | null = null
 
-    if (isOrgPlan(plan)) {
+    // Route admin credits to the subscription's entity (org if org-scoped).
+    if (isOrgScopedSubscription(userSubscription, resolvedUserId)) {
       entityType = 'organization'
       entityId = userSubscription.referenceId