OUT-4010: freeze batched-deposit intent per invoice

[SandipBajracharya]

OUT-4010 — Freeze batched-deposit intent per invoice

https://linear.app/assemblycom/issue/OUT-4010

Problem

bankDepositFeeFlag was read live in both handlePaymentSucceeded and handlePayoutReconciliationCompleted. Toggling it between a payment and its payout desynced the two paths — the fee got booked twice (OFF→ON) or missed while the payment stranded in Undeposited Funds (ON→OFF).

Approach

Freeze the decision per invoice. A new qb_invoice_sync.is_batched_deposit column is set from the live flag at invoice-create time; both handlers read the frozen value.

• resolveDepositToAccountRef takes the frozen flag; the only live read stays at the freeze point (create / paid-on-create).
• payment.succeeded: dedupe + resolve the frozen intent before the claim; a batched invoice defers to the payout with zero rows.
• payout: resolves per-invoice intent via getSuccessfulPaidPaymentIds (now joined to qb_invoice_sync); all-batched books one deposit, all-non-batched skips before claiming, mixed is rejected.

Tests

• New freeze/routing coverage: freezeBatchedIntent, statusPaidDepositRouting, frozenIntentRouting, frozenIntentDefer, plus payout allNonBatched / mixed.
• Reconciled the OUT-4006 payout suite with the frozen model: ported edge-case tests to seedPaidInvoiceForPayout, updated resolvePayments for the new return shape, removed the obsolete live-flag tests, and folded the duplicate happy-path/parallel infra into one directory.
• Full suite green: 350 passing.

Notes for reviewers

• Migration is a plain additive column (default false); no backfill needed since the batched-deposit feature isn't in production yet, so no pre-existing invoice was created under batched behavior.

🤖 Generated with Claude Code

[linear-code]

OUT-4010

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
quickbooks-sync	Building		Jul 28, 2026 6:22am
quickbooks-sync (dev)	Ready	Preview, Comment	Jul 28, 2026 6:22am

[greptile-apps]

Greptile Summary

Freezes batched-deposit routing per invoice and uses that persisted intent throughout payment and payout processing.

• Adds the is_batched_deposit invoice-sync column and captures the setting when invoice mappings are created.
• Routes invoice payments using the frozen value rather than the current setting.
• Resolves payout line items with their frozen intent, skipping all-non-batched payouts and rejecting mixed payouts.
• Adds integration coverage for frozen routing, deferred fees, and payout intent combinations.

Confidence Score: 4/5

The PR appears safe to merge, with the previously reported payment-redelivery recovery delay still outstanding.

The frozen invoice intent is propagated consistently through payment and payout routing, but payment webhook redeliveries still exit on any existing FAILED or PENDING log and must wait for asynchronous recovery.

Files Needing Attention: src/app/api/quickbooks/webhook/webhook.service.ts

Important Files Changed

Filename	Overview
src/app/api/quickbooks/invoice/invoice.service.ts	Captures the live batched-deposit setting when creating invoice-sync rows and uses the persisted value for payment routing.
src/app/api/quickbooks/syncLog/syncLog.service.ts	Joins successful paid-payment logs to invoice-sync records and returns each payment ID with its frozen deposit intent.
src/app/api/quickbooks/webhook/webhook.service.ts	Defers batched payment fees, skips all-non-batched payouts, rejects mixed-intent payouts, and centralizes absorbed-fee failure logging.
src/db/migrations/20260724091542_add_is_batched_deposit.sql	Adds the non-null frozen-intent column with a false default.

Sequence Diagram

sequenceDiagram
    participant I as Invoice creation
    participant DB as qb_invoice_sync
    participant P as payment.succeeded
    participant PO as payout reconciliation
    I->>DB: Persist is_batched_deposit
    P->>DB: Read frozen intent
    alt Batched
        P-->>PO: Defer absorbed fee
        PO->>DB: Resolve each invoice intent
        PO->>PO: Create one bank deposit
    else Non-batched
        P->>P: Book fee immediately
        PO->>PO: Skip all-non-batched payout
    end

Loading

_{Reviews (2): Last reviewed commit: "style(OUT-4010): trim verbose comments t..." | Re-trigger Greptile}

[SandipBajracharya]

@greptileai review PR again

[priosshrsth]

@SandipBajracharya I think better to use ? rather than ! imo.

[SandipBajracharya]

Converted to optional chaining

[priosshrsth]

lgtm