Function handleInvoiceFinalized

apps/sim/lib/billing/webhooks/invoices.ts:982–1241

(event: Stripe.Event)

 * Note: Enterprise plans no longer have overages
 */
export async function handleInvoiceFinalized(event: Stripe.Event) {
  try {
    const invoice = event.data.object as Stripe.Invoice
    const subscription = invoice.parent?.subscription_details?.subscription
    const stripeSubscriptionId = typeof subscription === 'string' ? subscription : subscription?.id
    if (!stripeSubscriptionId) {
      logger.info('No subscription found on invoice; skipping finalized handler', {
        invoiceId: invoice.id,
      })
      return
    }
    if (invoice.billing_reason && invoice.billing_reason !== 'subscription_cycle') return

    const records = await db
      .select()
      .from(subscriptionTable)
      .where(eq(subscriptionTable.stripeSubscriptionId, stripeSubscriptionId))
      .limit(1)

    if (records.length === 0) return
    const sub = records[0]

    const invoicePeriod = getSubscriptionLinePeriod(invoice, stripeSubscriptionId)
    if (!invoicePeriod) {
      logger.error('Missing subscription line period on subscription cycle invoice', {
        invoiceId: invoice.id,
        stripeSubscriptionId,
      })
      if (isEnterprise(sub.plan)) {
        await resetUsageForSubscription({ plan: sub.plan, referenceId: sub.referenceId })
      }
      return
    }

    if (isEnterprise(sub.plan)) {
      await resetUsageForSubscription({
        plan: sub.plan,
        referenceId: sub.referenceId,
        periodStart: invoicePeriod.periodStart,
        periodEnd: invoicePeriod.periodEnd,
      })
      return
    }

    await stripeWebhookIdempotency.executeWithIdempotency(
      'invoice-finalized',
      event.id,
      async () => {
        const stripe = requireStripeClient()
        const periodStart = Math.floor(invoicePeriod.periodStart.getTime() / 1000)
        const periodEnd = Math.floor(invoicePeriod.periodEnd.getTime() / 1000)
        const billingPeriod = new Date(periodEnd * 1000).toISOString().slice(0, 7)

        const totalOverage = await calculateSubscriptionOverage({
          ...sub,
          periodStart: new Date(periodStart * 1000),
          periodEnd: new Date(periodEnd * 1000),
        })