fix(billing): complete the chargeback + overage financial trail

Address Cursor review:
- handleDisputeClosed now records CHARGE_DISPUTE_CLOSED for every closed
  dispute (won/lost/warning_closed), unblocking only on favorable outcomes.
  dispute.status in the metadata distinguishes the outcome, so lost
  chargebacks are no longer missing from the trail.
- Threshold overage now emits OVERAGE_BILLED + overage_billed even when credits
  fully cover the overage (settledVia: 'credits' vs 'stripe'), so credit-settled
  overages are audited instead of silently returning null.

Author: waleedlatif1

apps/sim/lib/billing/threshold-billing.ts

@@ -121,7 +121,13 @@ export async function checkAndBillOverageThreshold(userId: string): Promise<void
     const totalOverageCents = Math.round(currentOverage * 100)
 
     const billedResult = await db.transaction(
-      async (tx): Promise<{ amount: number; creditsApplied: number } | null> => {
+      async (
+        tx
+      ): Promise<{
+        amount: number
+        creditsApplied: number
+        settledVia: 'stripe' | 'credits'
+      } | null> => {
         await tx.execute(sql.raw(`SET LOCAL lock_timeout = '${BILLING_LOCK_TIMEOUT_MS}ms'`))
 
         const statsRecords = await tx
@@ -200,7 +206,7 @@ export async function checkAndBillOverageThreshold(userId: string): Promise<void
             creditsApplied,
             unbilledOverage,
           })
-          return null
+          return { amount: unbilledOverage, creditsApplied, settledVia: 'credits' }
         }
 
         const amountCents = Math.round(amountToBill * 100)
@@ -240,25 +246,27 @@ export async function checkAndBillOverageThreshold(userId: string): Promise<void
           newBilledTotal: billedOverageThisPeriod + unbilledOverage,
         })
 
-        return { amount: amountToBill, creditsApplied }
+        return { amount: amountToBill, creditsApplied, settledVia: 'stripe' }
       }
     )
 
     if (billedResult) {
-      const { amount, creditsApplied } = billedResult
+      const { amount, creditsApplied, settledVia } = billedResult
+      const settledLabel = settledVia === 'credits' ? 'covered by credits' : 'billed'
       recordAudit({
         actorId: userId,
         action: AuditAction.OVERAGE_BILLED,
         resourceType: AuditResourceType.BILLING,
         resourceId: userSubscription.id,
-        description: `Overage of $${amount.toFixed(2)} billed for user ${userId}`,
+        description: `Overage of $${amount.toFixed(2)} ${settledLabel} for user ${userId}`,
         metadata: {
           entityType: 'user',
           referenceId: userId,
           plan: userSubscription.plan,
           amount,
           currency: 'usd',
           creditsApplied,
+          settledVia,
           billingPeriod,
         },
       })
@@ -267,6 +275,7 @@ export async function checkAndBillOverageThreshold(userId: string): Promise<void
         currency: 'usd',
         entity_type: 'user',
         reference_id: userId,
+        settled_via: settledVia,
       })
     }
   } catch (error) {
@@ -405,7 +414,14 @@ async function checkAndBillOrganizationOverageThreshold(organizationId: string):
     const totalOverageCents = Math.round(currentOverage * 100)
 
     const orgBilledResult = await db.transaction(
-      async (tx): Promise<{ amount: number; creditsApplied: number; ownerId: string } | null> => {
+      async (
+        tx
+      ): Promise<{
+        amount: number
+        creditsApplied: number
+        ownerId: string
+        settledVia: 'stripe' | 'credits'
+      } | null> => {
         await tx.execute(sql.raw(`SET LOCAL lock_timeout = '${BILLING_LOCK_TIMEOUT_MS}ms'`))
 
         const lockedOwnerRows = await tx
@@ -529,7 +545,12 @@ async function checkAndBillOrganizationOverageThreshold(organizationId: string):
             creditsApplied,
             unbilledOverage,
           })
-          return null
+          return {
+            amount: unbilledOverage,
+            creditsApplied,
+            ownerId: lockedOwnerId,
+            settledVia: 'credits',
+          }
         }
 
         const amountCents = Math.round(amountToBill * 100)
@@ -570,25 +591,32 @@ async function checkAndBillOrganizationOverageThreshold(organizationId: string):
           billingPeriod,
         })
 
-        return { amount: amountToBill, creditsApplied, ownerId: lockedOwnerId }
+        return {
+          amount: amountToBill,
+          creditsApplied,
+          ownerId: lockedOwnerId,
+          settledVia: 'stripe',
+        }
       }
     )
 
     if (orgBilledResult) {
-      const { amount, creditsApplied, ownerId } = orgBilledResult
+      const { amount, creditsApplied, ownerId, settledVia } = orgBilledResult
+      const settledLabel = settledVia === 'credits' ? 'covered by credits' : 'billed'
       recordAudit({
         actorId: ownerId,
         action: AuditAction.OVERAGE_BILLED,
         resourceType: AuditResourceType.BILLING,
         resourceId: orgSubscription.id,
-        description: `Overage of $${amount.toFixed(2)} billed for organization ${organizationId}`,
+        description: `Overage of $${amount.toFixed(2)} ${settledLabel} for organization ${organizationId}`,
         metadata: {
           entityType: 'organization',
           referenceId: organizationId,
           plan: orgSubscription.plan,
           amount,
           currency: 'usd',
           creditsApplied,
+          settledVia,
           billingPeriod,
         },
       })
@@ -597,6 +625,7 @@ async function checkAndBillOrganizationOverageThreshold(organizationId: string):
         currency: 'usd',
         entity_type: 'organization',
         reference_id: organizationId,
+        settled_via: settledVia,
       })
     }
   } catch (error) {

apps/sim/lib/billing/webhooks/disputes.ts

@@ -147,39 +147,37 @@ export async function handleChargeDispute(event: Stripe.Event): Promise<void> {
 export async function handleDisputeClosed(event: Stripe.Event): Promise<void> {
   const dispute = event.data.object as Stripe.Dispute
 
-  // Only unblock if we won or the warning was closed without a full dispute
-  const shouldUnblock = dispute.status === 'won' || dispute.status === 'warning_closed'
-
-  if (!shouldUnblock) {
-    logger.info('Dispute resolved against us, user remains blocked', {
-      disputeId: dispute.id,
-      status: dispute.status,
-    })
-    return
-  }
-
   const customerId = await getCustomerIdFromDispute(dispute)
   if (!customerId) {
     return
   }
 
-  // Find and unblock user (Pro plans) - only if blocked for dispute, not other reasons
+  // Unblock only when we won or the warning closed without a full dispute; a
+  // 'lost' dispute keeps the customer blocked (they owe us). The close is
+  // audited in every case so the chargeback trail is complete — `dispute.status`
+  // in the metadata distinguishes the outcome.
+  const shouldUnblock = dispute.status === 'won' || dispute.status === 'warning_closed'
+
   const users = await db
     .select({ id: user.id })
     .from(user)
     .where(eq(user.stripeCustomerId, customerId))
     .limit(1)
 
   if (users.length > 0) {
-    await db
-      .update(userStats)
-      .set({ billingBlocked: false, billingBlockedReason: null })
-      .where(and(eq(userStats.userId, users[0].id), eq(userStats.billingBlockedReason, 'dispute')))
-
-    logger.info('Unblocked user after dispute resolved in our favor', {
+    if (shouldUnblock) {
+      await db
+        .update(userStats)
+        .set({ billingBlocked: false, billingBlockedReason: null })
+        .where(
+          and(eq(userStats.userId, users[0].id), eq(userStats.billingBlockedReason, 'dispute'))
+        )
+    }
+    logger.info('Dispute closed for user', {
       disputeId: dispute.id,
       userId: users[0].id,
       status: dispute.status,
+      unblocked: shouldUnblock,
     })
 
     recordDisputeInstrumentation('closed', dispute, customerId, users[0].id, {
@@ -189,7 +187,6 @@ export async function handleDisputeClosed(event: Stripe.Event): Promise<void> {
     return
   }
 
-  // Find and unblock all org members (Team/Enterprise) - consistent with payment success
   const subs = await db
     .select({ referenceId: subscription.referenceId })
     .from(subscription)
@@ -198,13 +195,14 @@ export async function handleDisputeClosed(event: Stripe.Event): Promise<void> {
 
   if (subs.length > 0) {
     const orgId = subs[0].referenceId
-    const memberCount = await unblockOrgMembers(orgId, 'dispute')
-
-    logger.info('Unblocked all org members after dispute resolved in our favor', {
+    if (shouldUnblock) {
+      await unblockOrgMembers(orgId, 'dispute')
+    }
+    logger.info('Dispute closed for organization', {
       disputeId: dispute.id,
       organizationId: orgId,
-      memberCount,
       status: dispute.status,
+      unblocked: shouldUnblock,
     })
 
     const actorId = (await getOrganizationOwnerId(orgId)) ?? orgId

apps/sim/lib/posthog/events.ts

@@ -743,6 +743,7 @@ export interface PostHogEventMap {
     currency: string
     entity_type: 'user' | 'organization'
     reference_id: string
+    settled_via: 'stripe' | 'credits'
   }
 
   credits_purchased: {