Function calculateSubscriptionOverage

apps/sim/lib/billing/core/billing.ts:216–389

(sub: {
  id: string
  plan: string | null
  referenceId: string
  seats?: number | null
  periodStart?: Date | null
  periodEnd?: Date | null
})

 * Shared logic between invoice.finalized and customer.subscription.deleted handlers
 */
export async function calculateSubscriptionOverage(sub: {
  id: string
  plan: string | null
  referenceId: string
  seats?: number | null
  periodStart?: Date | null
  periodEnd?: Date | null
}): Promise<number> {
  // Enterprise plans have no overages
  if (isEnterprise(sub.plan)) {
    logger.info('Enterprise plan has no overages', {
      subscriptionId: sub.id,
      plan: sub.plan,
    })
    return 0
  }

  let totalOverageDecimal = new Decimal(0)

  const isOrgScoped = await isSubscriptionOrgScoped(sub)

  if (isOrgScoped) {
    const pooled = await aggregateOrgMemberStats(sub.referenceId)
    const ledgerUsage =
      sub.periodStart && sub.periodEnd
        ? await getBillingPeriodUsageCost(
            { type: 'organization', id: sub.referenceId },
            { start: sub.periodStart, end: sub.periodEnd }
          )
        : 0

    const orgData = await db
      .select({ departedMemberUsage: organization.departedMemberUsage })
      .from(organization)
      .where(eq(organization.id, sub.referenceId))
      .limit(1)

    const departedMemberUsage =
      orgData.length > 0 ? toNumber(toDecimal(orgData[0].departedMemberUsage)) : 0

    const { totalOverage, effectiveUsage, baseSubscriptionAmount } = await computeOrgOverageAmount({
      plan: sub.plan,
      seats: sub.seats ?? null,
      periodStart: sub.periodStart ?? null,
      periodEnd: sub.periodEnd ?? null,
      organizationId: sub.referenceId,
      pooledCurrentPeriodCost: pooled.currentPeriodCost + ledgerUsage,
      departedMemberUsage,
      memberIds: pooled.memberIds,
    })

    totalOverageDecimal = toDecimal(totalOverage)

    logger.info('Calculated org-scoped overage', {
      subscriptionId: sub.id,
      plan: sub.plan,
      currentMemberUsage: pooled.currentPeriodCost + ledgerUsage,
      departedMemberUsage,