fix(billing): settle zero fal estimates and fix the settlement fixture payer

Author: waleedlatif1

apps/sim/lib/tools/falai-settlement.integration.ts

@@ -4,14 +4,15 @@
  * billing-events API is stubbed.
  */
 import { db } from '@sim/db'
-import { usageLog, user, userStats } from '@sim/db/schema'
+import { organization, usageLog, user, userStats } from '@sim/db/schema'
 import { generateId } from '@sim/utils/id'
 import { eq, inArray } from 'drizzle-orm'
 import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { type FalAICostSettlementPayload, settleFalAICost } from '@/lib/tools/falai-settlement'
 
 const HOSTED_KEY_ENV_VAR = 'FALAI_API_KEY_1'
 const userIds: string[] = []
+const organizationIds: string[] = []
 
 async function createUser(): Promise<string> {
   const id = `falai-settlement-user-${generateId()}`
@@ -29,8 +30,17 @@ async function createUser(): Promise<string> {
   return id
 }
 
+async function createOrganization(): Promise<string> {
+  const id = `falai-settlement-org-${generateId()}`
+  await db.insert(organization).values({ id, name: 'Fal Settlement Org', slug: id })
+  organizationIds.push(id)
+  return id
+}
+
+/** A settlement billed to an organization payer, the snapshot shape for a run outside a workspace. */
 function payloadFor(
   userId: string,
+  organizationId: string,
   billedProviderCostDollars: number,
   billingPeriod = { start: '2026-11-01T00:00:00.000Z', end: '2026-12-01T00:00:00.000Z' }
 ): FalAICostSettlementPayload {
@@ -45,9 +55,9 @@ function payloadFor(
       billingAttribution: {
         actorUserId: userId,
         workspaceId: null,
-        organizationId: null,
+        organizationId,
         billedAccountUserId: userId,
-        billingEntity: { type: 'user', id: userId },
+        billingEntity: { type: 'organization', id: organizationId },
         billingPeriod,
         payerSubscription: null,
       },
@@ -103,12 +113,16 @@ afterAll(async () => {
     await db.delete(usageLog).where(inArray(usageLog.userId, userIds))
     await db.delete(user).where(inArray(user.id, userIds))
   }
+  if (organizationIds.length > 0) {
+    await db.delete(organization).where(inArray(organization.id, organizationIds))
+  }
 })
 
 describe('settleFalAICost', () => {
   it('bills the shortfall once when the exact charge exceeds the estimate, however often it runs', async () => {
     const userId = await createUser()
-    const payload = payloadFor(userId, 6.49)
+    const organizationId = await createOrganization()
+    const payload = payloadFor(userId, organizationId, 6.49)
     stubFalBillingEvents({ requestId: payload.requestId, costDollars: 15 })
 
     expect(await settleFalAICost(payload)).toBe('charged')
@@ -125,8 +139,9 @@ describe('settleFalAICost', () => {
 
   it('bills a settlement that outlives its billing period to the payer current period', async () => {
     const userId = await createUser()
+    const organizationId = await createOrganization()
     const endedPeriod = { start: '2026-01-01T00:00:00.000Z', end: '2026-02-01T00:00:00.000Z' }
-    const payload = payloadFor(userId, 6.49, endedPeriod)
+    const payload = payloadFor(userId, organizationId, 6.49, endedPeriod)
     stubFalBillingEvents({ requestId: payload.requestId, costDollars: 15 })
 
     expect(await settleFalAICost(payload)).toBe('charged')
@@ -138,19 +153,21 @@ describe('settleFalAICost', () => {
 
   it('bills nothing while fal has not recorded the charge', async () => {
     const userId = await createUser()
+    const organizationId = await createOrganization()
     stubFalBillingEvents(null)
 
-    expect(await settleFalAICost(payloadFor(userId, 0.25))).toBe('pending')
+    expect(await settleFalAICost(payloadFor(userId, organizationId, 0.25))).toBe('pending')
 
     expect(await settlementRows(userId)).toHaveLength(0)
   })
 
   it('refuses to settle when the hosted key that ran the request is not configured', async () => {
     const userId = await createUser()
+    const organizationId = await createOrganization()
     vi.stubEnv(HOSTED_KEY_ENV_VAR, '')
     const fetchMock = stubFalBillingEvents(null)
 
-    await expect(settleFalAICost(payloadFor(userId, 6.49))).rejects.toThrow(
+    await expect(settleFalAICost(payloadFor(userId, organizationId, 6.49))).rejects.toThrow(
       'Hosted fal key FALAI_API_KEY_1 is not configured'
     )
     expect(fetchMock).not.toHaveBeenCalled()

apps/sim/tools/index.test.ts

@@ -116,8 +116,10 @@ const {
   mockGetInternalToolOperationHandler,
   mockExecuteInternalToolOperation,
   mockPayerHasPaidAccess,
+  mockScheduleFalAICostSettlement,
 } = vi.hoisted(() => ({
   mockPayerHasPaidAccess: vi.fn(),
+  mockScheduleFalAICostSettlement: vi.fn(),
   mockGetToolAsync: vi.fn(),
   mockRateLimiterFns: {
     acquireKey: vi.fn(),
@@ -183,6 +185,10 @@ vi.mock('@/lib/billing/core/chat-access', () => ({
   payerHasPaidAccess: mockPayerHasPaidAccess,
 }))
 
+vi.mock('@/lib/tools/falai-settlement', () => ({
+  scheduleFalAICostSettlement: mockScheduleFalAICostSettlement,
+}))
+
 vi.mock('@/lib/billing/core/attribution', () => billingAttributionMock)
 
 vi.mock('@/lib/uploads/contexts/workspace/file-manager', () => workspaceFileManagerMock)
@@ -6564,6 +6570,74 @@ describe('Hosted Key Injection', () => {
     }
   })
 
+  it('schedules the exact-cost settlement for a hosted fal charge estimated at zero', async () => {
+    setEnvFlags({ isHosted: true })
+    mockGetBYOKKey.mockResolvedValue(null)
+    mockRateLimiterFns.acquireKey.mockResolvedValue({
+      success: true,
+      key: 'platform-fixture-key',
+      keyIndex: 0,
+      envVarName: 'FALAI_API_KEY_1',
+    })
+    mockValidateUrlWithDNS.mockResolvedValue({ isValid: true, resolvedIP: '93.184.216.34' })
+    mockSecureFetchWithPinnedIP.mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      headers: { get: () => null, toRecord: () => ({}) },
+      json: async () => ({ ok: true }),
+      text: async () => '{"ok":true}',
+    })
+    tools.test_fal_zero_estimate = {
+      id: 'test_fal_zero_estimate',
+      name: 'Zero-estimate fal fixture',
+      description: 'Hosted fal charge whose estimate is zero',
+      version: '1.0.0',
+      params: {},
+      request: { url: 'https://example.com/fixture', method: 'GET', headers: () => ({}) },
+      hosting: {
+        envKeyPrefix: 'FALAI_API_KEY',
+        apiKeyParam: 'apiKey',
+        byokProviderId: 'falai',
+        exactCostSettlement: 'falai',
+        pricing: {
+          type: 'custom',
+          getCost: () => ({
+            cost: 0,
+            metadata: {
+              endpointId: 'fal-ai/fixture/text-to-video',
+              requestId: 'fal-request-1',
+              source: 'historical_estimate',
+              providerCostDollars: 0,
+              markupMultiplier: 1.5,
+            },
+          }),
+        },
+        rateLimit: { mode: 'per_request', requestsPerMinute: 100 },
+      },
+      transformResponse: async () => ({ success: true, output: {} }),
+    }
+    try {
+      const result = await executeTool(
+        'test_fal_zero_estimate',
+        {},
+        { executionContext: createToolExecutionContext({ userId: 'user-1' }) }
+      )
+
+      expect(result.success).toBe(true)
+      expect(mockScheduleFalAICostSettlement).toHaveBeenCalledWith(
+        expect.objectContaining({
+          cost: expect.objectContaining({ requestId: 'fal-request-1', costDollars: 0 }),
+          envVarName: 'FALAI_API_KEY_1',
+          source: 'workflow',
+        })
+      )
+    } finally {
+      Reflect.deleteProperty(tools, 'test_fal_zero_estimate')
+      resetEnvFlagsMock()
+    }
+  })
+
   describe('requiresPaidPlan', () => {
     const PAID_ONLY_TOOL_ID = 'test_paid_only_hosting'
 

apps/sim/tools/index.ts

@@ -957,7 +957,7 @@ async function processHostedKeyCost(
 
   const { cost, metadata } = calculateToolCost(tool.hosting.pricing, params, response, tool.id)
 
-  if (cost <= 0) return { cost: 0 }
+  if (cost <= 0) return { cost: 0, metadata }
 
   logger.debug(`Hosted key cost for ${tool.id}: $${cost}`, metadata ? { metadata } : {}, {
     requestId,
@@ -1126,11 +1126,13 @@ async function applyHostedKeyCostToResult(
   hostedKeyMetrics.recordUsed({ provider, tool: tool.id, key })
   hostedKeyMetrics.recordCostCharged(hostedKeyCost, { provider, tool: tool.id })
 
+  const scope = resolveToolScope(params, executionContext)
+  // A zero estimate is not proof the generation was free; settlement bills the receipt.
+  await scheduleExactCostSettlement(tool, metadata, scope, envVarName)
+
   if (hostedKeyCost > 0) {
-    const scope = resolveToolScope(params, executionContext)
     const { copilotToolExecution } = scope
     if (copilotToolExecution) await recordServiceCost(provider, hostedKeyCost)
-    await scheduleExactCostSettlement(tool, metadata, scope, envVarName)
     finalResult.output = {
       ...finalResult.output,
       cost: {