@stamhoofd/backend 2.141.0 → 2.143.0

package/src/helpers/StripeSettlementSyncRunner.ts

@@ -1,5 +1,6 @@
 import { StripeAccount } from '@stamhoofd/models';
 import { Settlement } from '@stamhoofd/models/models/Settlement.js';
+import { AbortSignal } from '@stamhoofd/queues';
 import { PaymentProvider } from '@stamhoofd/structures';
 import { SettlementStatus } from '@stamhoofd/structures/settlements/SettlementStatus.js';
 
@@ -44,12 +45,14 @@ export class StripeSettlementSyncRunner implements ProviderSettlementSyncRunner
      * Walks the window month by month: fees first, then our platform payouts, then the connected
      * accounts.
      */
-    async run({ start, end, summary, onProgress }: ProviderSyncRunOptions): Promise<void> {
+    async run({ start, end, summary, onProgress, abort }: ProviderSyncRunOptions): Promise<void> {
         const platformSync = new StripeSettlementSync({ secretKey: this.#secretKey });
 
         let currentMonth = new Date(start.getFullYear(), start.getMonth(), 1);
 
         while (true) {
+            abort.throwIfAborted();
+
             const { start: monthStartUnix, end: monthEndUnix } = SettlementService.getMonthUnixStartEnd(currentMonth);
             if (monthStartUnix * 1000 > end.getTime()) {
                 break;
@@ -59,21 +62,23 @@ export class StripeSettlementSyncRunner implements ProviderSettlementSyncRunner
             const windowEnd = new Date(Math.min(monthEndUnix * 1000, end.getTime()));
 
             try {
-                await platformSync.syncFees({ start: windowStart, end: windowEnd });
+                await platformSync.syncFees({ start: windowStart, end: windowEnd, abort });
                 summary.feeMonths += 1;
             } catch (e) {
+                abort.throwIfAborted();
+
                 // syncFees already emailed nothing: it throws an aggregate, the month is retried by
                 // the next run and the month is not invoiced until it completes
                 console.error('Fee sync failed for month ' + currentMonth.toISOString(), e);
                 summary.failedFeeMonths += 1;
             }
 
-            const platformResult = await platformSync.syncPayouts({ start: windowStart, end: windowEnd, force: this.#force });
+            const platformResult = await platformSync.syncPayouts({ start: windowStart, end: windowEnd, force: this.#force, abort });
             summary.synced += platformResult.synced;
             summary.skipped += platformResult.skipped;
             summary.failed += platformResult.failed;
 
-            const connectedResult = await this.syncConnectedPayouts({ start: windowStart, end: windowEnd });
+            const connectedResult = await this.syncConnectedPayouts({ start: windowStart, end: windowEnd, abort });
             summary.synced += connectedResult.synced;
             summary.skipped += connectedResult.skipped;
             summary.failed += connectedResult.failed;
@@ -83,26 +88,40 @@ export class StripeSettlementSyncRunner implements ProviderSettlementSyncRunner
         }
 
         if (this.#retryUnsynced) {
-            await this.retryUnsyncedSettlements({ windowStart: start });
+            await this.retryUnsyncedSettlements({ windowStart: start, abort });
         }
     }
 
     /**
      * Walks the payouts of every active connected account.
      */
-    async syncConnectedPayouts({ start, end }: { start: Date; end?: Date }): Promise<{ synced: number; skipped: number; failed: number }> {
+    async syncConnectedPayouts({ start, end, abort = new AbortSignal() }: { start: Date; end?: Date; abort?: AbortSignal }): Promise<{ synced: number; skipped: number; failed: number }> {
         const totals = { synced: 0, skipped: 0, failed: 0 };
 
         const accounts = await StripeAccount.select().where('status', 'active').fetch();
 
         for (const account of accounts) {
+            abort.throwIfAborted();
+
             try {
                 const sync = new StripeSettlementSync({ secretKey: this.#secretKey, stripeAccount: account });
-                const result = await sync.syncPayouts({ start, end, force: this.#force });
+                const result = await sync.syncPayouts({ start, end, force: this.#force, abort });
                 totals.synced += result.synced;
                 totals.skipped += result.skipped;
                 totals.failed += result.failed;
             } catch (e) {
+                // An interrupted account is not an account with a problem: it may not be marked
+                // inaccessible, counted or reported
+                abort.throwIfAborted();
+
+                if (e !== null && typeof e === 'object' && 'type' in e && e.type === 'StripePermissionError' && e.message.includes(account.accountId) && e.message.includes('does not have access to account')) {
+                    // Stripe account no longer in active use
+                    console.error(e, 'marking stripe account', account.id, account.accountId, 'as inaccessible because we do not seem to have access to it any longer');
+                    account.status = 'inaccessible';
+                    await account.save();
+                    totals.skipped += 1;
+                    continue;
+                }
                 console.error('Failed to sync payouts of Stripe account ' + account.accountId, e);
                 totals.failed += 1;
 
@@ -119,7 +138,7 @@ export class StripeSettlementSyncRunner implements ProviderSettlementSyncRunner
      * after MAXIMUM_FAILURE_COUNT attempts and waits in the problem report instead. Always forced,
      * regardless of the force configuration.
      */
-    async retryUnsyncedSettlements({ windowStart }: { windowStart: Date }): Promise<void> {
+    async retryUnsyncedSettlements({ windowStart, abort = new AbortSignal() }: { windowStart: Date; abort?: AbortSignal }): Promise<void> {
         const settlements = await Settlement.select()
             .where('provider', PaymentProvider.Stripe)
             .where('syncedAt', null)
@@ -132,12 +151,18 @@ export class StripeSettlementSyncRunner implements ProviderSettlementSyncRunner
             .fetch();
 
         for (const settlement of settlements) {
+            abort.throwIfAborted();
+
             const failureCountBefore = settlement.syncFailureCount;
             try {
                 const stripeAccount = settlement.stripeAccountId ? await StripeAccount.getByID(settlement.stripeAccountId) : null;
                 const sync = new StripeSettlementSync({ secretKey: this.#secretKey, stripeAccount: stripeAccount ?? null });
-                await sync.syncPayoutById(settlement.externalId, { force: true });
+                await sync.syncPayoutById(settlement.externalId, { force: true, abort });
             } catch (e) {
+                // An interrupted retry may not count towards the cap: the payout is still waiting
+                // for a real attempt
+                abort.throwIfAborted();
+
                 console.error('Retry of settlement ' + settlement.externalId + ' failed', e);
 
                 // Errors before the walk (e.g. the payout can't be retrieved anymore) don't pass

package/src/helpers/waitUntilDeadline.test.ts

@@ -0,0 +1,48 @@
+import { sleep } from '@stamhoofd/utility';
+import { vi } from 'vitest';
+
+import { waitUntilDeadline } from './waitUntilDeadline.js';
+
+describe('Helper.waitUntilDeadline', () => {
+    let errors: string[];
+
+    beforeEach(() => {
+        errors = [];
+        vi.spyOn(console, 'error').mockImplementation((message: unknown) => {
+            errors.push(typeof message === 'string' ? message : String(message));
+        });
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    const deadlineIn = (ms: number) => new Date(Date.now() + ms);
+
+    test('returns as soon as the work finishes', async () => {
+        const started = Date.now();
+        await waitUntilDeadline(sleep(10), { deadline: deadlineIn(60_000), description: 'work' });
+
+        expect(Date.now() - started).toBeLessThan(1000);
+        expect(errors).toHaveLength(0);
+    });
+
+    test('gives up on work that never finishes', async () => {
+        await waitUntilDeadline(new Promise(() => {}), { deadline: deadlineIn(20), description: 'work' });
+
+        expect(errors).toContain('Gave up waiting for work to finish');
+    });
+
+    test('a deadline that already passed does not wait', async () => {
+        await waitUntilDeadline(sleep(60_000), { deadline: deadlineIn(-1000), description: 'work' });
+
+        expect(errors).toContain('Gave up waiting for work to finish');
+    });
+
+    test('a failure in the work is logged instead of thrown', async () => {
+        await waitUntilDeadline(Promise.reject(new Error('Broken')), { deadline: deadlineIn(60_000), description: 'work' });
+
+        expect(errors).toContain('Failed to wait for work:');
+        expect(errors).not.toContain('Gave up waiting for work to finish');
+    });
+});

package/src/helpers/waitUntilDeadline.ts

@@ -0,0 +1,28 @@
+/**
+ * Waits for `promise`, but gives up at `deadline`: a shutdown may not hang on work that never
+ * checks its abort signal, or that is stuck on a network call. What is left behind runs again after
+ * the restart.
+ *
+ * A failure in the awaited work is logged instead of thrown: it may not stop the shutdown either.
+ */
+export async function waitUntilDeadline(promise: Promise<unknown>, { deadline, description }: { deadline: Date; description: string }): Promise<void> {
+    let timer: NodeJS.Timeout | undefined;
+
+    const timedOut = await Promise.race([
+        promise.then(() => false).catch((error) => {
+            console.error('Failed to wait for ' + description + ':');
+            console.error(error);
+            return false;
+        }),
+        new Promise<boolean>((resolve) => {
+            timer = setTimeout(() => resolve(true), Math.max(deadline.getTime() - Date.now(), 0));
+        }),
+    ]);
+
+    // Or the timer keeps the process alive until the deadline it no longer needs
+    clearTimeout(timer);
+
+    if (timedOut) {
+        console.error('Gave up waiting for ' + description + ' to finish');
+    }
+}

package/src/services/ApplicationFeeService.ts

@@ -31,10 +31,11 @@ export type ApplicationFeeData = {
      */
     organizationId: string;
 
-    payingOrganizationId: string;
-    payingStripeAccountId: string;
+    payingOrganizationId?: string | null;
+    payingStripeAccountId?: string | null;
     payingPaymentId?: string | null;
-    settlementChargeId: string;
+
+    settlementChargeId?: string | null;
     settlementId?: string | null;
     occurredAt: Date;
 };
@@ -85,17 +86,28 @@ export class ApplicationFeeService {
         fee.type = data.type;
         fee.amount = data.amount;
         fee.organizationId = data.organizationId;
-        fee.payingOrganizationId = data.payingOrganizationId;
-        fee.payingStripeAccountId = data.payingStripeAccountId;
-        fee.settlementChargeId = data.settlementChargeId;
         fee.occurredAt = data.occurredAt;
 
         if (data.settlementId !== undefined) {
             fee.settlementId = data.settlementId;
         }
+
         if (data.payingPaymentId !== undefined) {
             fee.payingPaymentId = data.payingPaymentId;
         }
+
+        if (data.settlementChargeId !== undefined) {
+            fee.settlementChargeId = data.settlementChargeId;
+        }
+
+        if (data.payingOrganizationId !== undefined) {
+            fee.payingOrganizationId = data.payingOrganizationId;
+        }
+
+        if (data.payingStripeAccountId !== undefined) {
+            fee.payingStripeAccountId = data.payingStripeAccountId;
+        }
+
         await fee.save();
 
         if (fee.balanceItemId === null) {
@@ -130,14 +142,32 @@ export class ApplicationFeeService {
         periodStart: Date;
     }): Promise<Payment[]> {
         const reference = LEGACY_FEE_PAYMENT_REFERENCE_PREFIX + Formatter.dateIso(periodStart);
-        const key = organizationId + ':' + payingStripeAccountId + ':' + reference;
+        const key = organizationId + ':' + payingOrganizationId + ':' + payingStripeAccountId + ':' + reference;
 
         const cached = this.legacyFeePayments.get(key);
         if (cached && cached.length > 0) {
             return cached;
         }
 
-        const payments = await Payment.select()
+        // Prefer matching stripeAccountId
+        let payments = await Payment.select()
+            .where('organizationId', organizationId)
+            .where('payingOrganizationId', payingOrganizationId)
+            .where(
+                SQL.where('stripeAccountId', payingStripeAccountId),
+            )
+            .where('reference', reference)
+            .where('method', PaymentMethod.AccountDeductions)
+            .where('provider', PaymentProvider.Stripe)
+            .where('status', PaymentStatus.Succeeded)
+            .fetch();
+
+        if (payments.length) {
+            this.legacyFeePayments.set(key, payments);
+            return payments;
+        }
+
+        payments = await Payment.select()
             .where('organizationId', organizationId)
             .where('payingOrganizationId', payingOrganizationId)
             .where(
@@ -162,7 +192,7 @@ export class ApplicationFeeService {
      * from being billed twice.
      */
     private static async linkLegacyInvoicedFee(fee: ApplicationFee) {
-        if (!fee.payingStripeAccountId) {
+        if (!fee.payingStripeAccountId || !fee.payingOrganizationId) {
             return;
         }
 
@@ -217,7 +247,9 @@ export class ApplicationFeeService {
             .where('id', balanceItemPayments.map(b => b.balanceItemId))
             .fetch();
         const balanceItemType = type === ApplicationFeeType.Service ? BalanceItemType.ServiceFee : BalanceItemType.TransferFee;
-        return balanceItems.find(item => item.type === balanceItemType) ?? null;
+
+        // In legacy migrations, the type has been set to 'Other' - fallback to that (contains both service fees and transfer fees in one balance item)
+        return balanceItems.find(item => item.type === balanceItemType) ?? (balanceItems.length === 1 ? balanceItems.find(item => item.type === BalanceItemType.Other) : null) ?? null;
     }
 
     /**
@@ -226,6 +258,10 @@ export class ApplicationFeeService {
      * no stamp: stampInvoicedPayments runs when the invoice is created later.
      */
     private static async stampProviderInvoiceId(fee: ApplicationFee, { payment }: { payment?: Payment } = {}) {
+        if (!fee.settlementChargeId) {
+            return;
+        }
+
         if (!payment) {
             if (!fee.balanceItemId) {
                 return;
@@ -275,7 +311,7 @@ export class ApplicationFeeService {
             .where('balanceItemId', balanceItemPayments.map(b => b.balanceItemId))
             .limit(FEE_BATCH_SIZE)
             .allBatched()) {
-            settlementChargeIds.push(...fees.map(fee => fee.settlementChargeId));
+            settlementChargeIds.push(...fees.map(fee => fee.settlementChargeId).filter((id): id is string => id !== null));
         }
 
         await SettlementService.setChargeProviderInvoiceIds(settlementChargeIds, invoice?.number ?? null);

package/src/services/BalanceItemService.ts

@@ -11,6 +11,7 @@ import { OrderService } from './OrderService.js';
 import { PaymentReallocationService } from './PaymentReallocationService.js';
 import { RegistrationService } from './RegistrationService.js';
 import { STPackageService } from './STPackageService.js';
+import { WebshopCrowdfundingService } from './WebshopCrowdfundingService.js';
 
 const memberUpdateQueue = new GroupedThrottledQueue(async (organizationId: string, memberIds: string[]) => {
     await CachedBalance.updateForMembers(organizationId, memberIds);
@@ -183,6 +184,10 @@ export class BalanceItemService {
             if (item.registrationId) {
                 registrationUpdateQueue.addItem(item.organizationId, item.registrationId);
             }
+
+            if (item.orderId) {
+                WebshopCrowdfundingService.scheduleUpdateForOrder(item.orderId);
+            }
         }
     }
 

package/src/services/SettlementService.test.ts

@@ -13,9 +13,11 @@ import { ReportedRows, SettlementService } from './SettlementService.js';
 
 describe('SettlementService', () => {
     let organization: Organization;
+    let stripeAccount: StripeAccount;
 
     beforeAll(async () => {
         organization = await new OrganizationFactory({}).create();
+        stripeAccount = await createStripeAccount();
     });
 
     async function createPayment(price = 50_00_00, method = PaymentMethod.Bancontact, organizationId = organization.id) {
@@ -30,25 +32,25 @@ describe('SettlementService', () => {
         return payment;
     }
 
-    async function createStripeAccount() {
-        const stripeAccount = new StripeAccount();
-        stripeAccount.organizationId = organization.id;
-        stripeAccount.accountId = 'acct_' + uuidv4();
-        await stripeAccount.save();
-        return stripeAccount;
+    async function createStripeAccount(organizationId = organization.id) {
+        const account = new StripeAccount();
+        account.organizationId = organizationId;
+        account.accountId = 'acct_' + uuidv4();
+        await account.save();
+        return account;
     }
 
     /**
      * A fee with its deduction charge, as the sync stores them.
      */
-    async function createApplicationFee({ amount = 1_00_00, type = ApplicationFeeType.Service, settlement = null as SettlementModel | null, balanceItemId = null as string | null, occurredAt = new Date(2026, 0, 14) } = {}) {
+    async function createApplicationFee({ amount = 1_00_00, type = ApplicationFeeType.Service, settlement = null as SettlementModel | null, balanceItemId = null as string | null, occurredAt = new Date(2026, 0, 14), payingOrganizationId = organization.id, payingStripeAccountId = null as string | null } = {}) {
         const externalId = 'fee_' + uuidv4();
         const charge = await SettlementService.upsertCharge({
             type: type === ApplicationFeeType.Service ? SettlementChargeType.ApplicationFeeService : SettlementChargeType.ApplicationFeeTransfer,
             externalId: externalId + ':' + type,
             amount: -amount,
             applicationFeeId: externalId,
-            organizationId: organization.id,
+            organizationId: payingOrganizationId,
             occurredAt,
         });
 
@@ -57,7 +59,8 @@ describe('SettlementService', () => {
         fee.type = type;
         fee.amount = amount;
         fee.organizationId = organization.id;
-        fee.payingOrganizationId = organization.id;
+        fee.payingOrganizationId = payingOrganizationId;
+        fee.payingStripeAccountId = payingStripeAccountId ?? stripeAccount.id;
         fee.settlementChargeId = charge.id;
         fee.settlementId = settlement?.id ?? null;
         fee.balanceItemId = balanceItemId;
@@ -66,6 +69,22 @@ describe('SettlementService', () => {
         return { fee, charge };
     }
 
+    /**
+     * A fee the invoicer will never bill: its payer is gone, so there is no payout of theirs to
+     * deduct it from either.
+     */
+    async function createUncollectibleApplicationFee({ amount = 1_00_00, settlement = null as SettlementModel | null, occurredAt = new Date(2026, 0, 14) } = {}) {
+        const fee = new ApplicationFee();
+        fee.externalId = 'fee_' + uuidv4();
+        fee.type = ApplicationFeeType.Service;
+        fee.amount = amount;
+        fee.organizationId = organization.id;
+        fee.settlementId = settlement?.id ?? null;
+        fee.occurredAt = occurredAt;
+        await fee.save();
+        return fee;
+    }
+
     /**
      * A fee payment with one balance item, like the invoicer creates.
      */
@@ -471,6 +490,60 @@ describe('SettlementService', () => {
             expect(unlinked!.pendingFees).toBe(0);
             expect(unlinked!.unexplainedAmount).toBe(1_00_00);
         });
+
+        test('fees the invoicer will never bill explain the payout without ever being invoiced', async () => {
+            const settlement = await SettlementService.upsertSettlement(settlementData({ amount: 3_00_00 }));
+            await createApplicationFee({ settlement, amount: 1_00_00 });
+            await createUncollectibleApplicationFee({ settlement, amount: 1_00_00 });
+
+            // A payer we know, but not the account the fee was deducted from: the invoicer skips it
+            const accountless = await createApplicationFee({ settlement, amount: 1_00_00 });
+            accountless.fee.payingStripeAccountId = null;
+            await accountless.fee.save();
+
+            await SettlementService.finishSync(settlement, { transactionCount: 3 });
+
+            // Only the fee that can still be billed is worth waiting for
+            expect(settlement.pendingFees).toBe(1_00_00);
+            expect(settlement.uncollectibleFees).toBe(2_00_00);
+            expect(settlement.unexplainedAmount).toBe(0);
+        });
+    });
+
+    describe('getApplicationFeeSettlementIdsForPayingOrganization', () => {
+        test('deleting the paying organization keeps its fees as uncollectible income', async () => {
+            const payer = await new OrganizationFactory({}).create();
+            const payerAccount = await createStripeAccount(payer.id);
+            const settlement = await SettlementService.upsertSettlement(settlementData({ amount: 1_00_00 }));
+            const { fee, charge } = await createApplicationFee({ settlement, amount: 1_00_00, payingOrganizationId: payer.id, payingStripeAccountId: payerAccount.id });
+
+            // An organization that took Stripe payments is the only kind that owes fees: its
+            // payments reference the account the delete has to cascade through
+            const payerPayment = await createPayment(10_00_00, PaymentMethod.Bancontact, payer.id);
+            payerPayment.stripeAccountId = payerAccount.id;
+            await payerPayment.save();
+
+            await SettlementService.finishSync(settlement, { transactionCount: 1 });
+            expect(settlement.pendingFees).toBe(1_00_00);
+
+            const settlementIds = await SettlementService.getApplicationFeeSettlementIdsForPayingOrganization(payer.id);
+            expect(settlementIds).toEqual([settlement.id]);
+
+            await payer.delete();
+            await SettlementService.refreshTotalsForIds(settlementIds);
+
+            // The deduction charge went with the organization; the fee itself is our income and stays
+            expect(await SettlementCharge.getByID(charge.id)).toBeUndefined();
+            const stored = await ApplicationFee.getByID(fee.id);
+            expect(stored).toBeDefined();
+            expect(stored!.payingOrganizationId).toBeNull();
+            expect(stored!.settlementChargeId).toBeNull();
+
+            const after = await Settlement.getByID(settlement.id);
+            expect(after!.pendingFees).toBe(0);
+            expect(after!.uncollectibleFees).toBe(1_00_00);
+            expect(after!.unexplainedAmount).toBe(0);
+        });
     });
 
     describe('updateLegacySettlementReference', () => {

package/src/services/SettlementService.ts

@@ -6,7 +6,7 @@ import { ApplicationFee } from '@stamhoofd/models/models/ApplicationFee.js';
 import { PaymentSettlement } from '@stamhoofd/models/models/PaymentSettlement.js';
 import { Settlement } from '@stamhoofd/models/models/Settlement.js';
 import { SettlementCharge } from '@stamhoofd/models/models/SettlementCharge.js';
-import { QueueHandler } from '@stamhoofd/queues';
+import { AbortSignal, QueueHandler } from '@stamhoofd/queues';
 import { SQL } from '@stamhoofd/sql';
 import type { PaymentProvider } from '@stamhoofd/structures';
 import { PaymentMethod, SettlementReference } from '@stamhoofd/structures';
@@ -62,6 +62,11 @@ export type ChargeData = {
  */
 const CHARGE_UPDATE_BATCH_SIZE = 500;
 
+/**
+ * Fees read per batch when a whole organization's fees are walked.
+ */
+const FEE_BATCH_SIZE = 500;
+
 /**
  * Collects which rows the provider still reports in a settlement while a sync walks it. A stored
  * row of the settlement that is not in here after the walk has moved or disappeared at the
@@ -109,9 +114,20 @@ export class SettlementService {
      * Serializes syncs of the same settlement, so cron and manual backfill can't race. In-process
      * only: across multiple API instances the tables' unique keys are the real guard, so a
      * concurrent sync surfaces as a duplicate-key error and is retryable.
+     *
+     * Interrupting a walk is opt-in: the caller's signal governs the whole sync (so it stops as
+     * one, and every caller in it recognizes the abort), and a caller without one walks to the end.
      */
-    static lock<T>(provider: PaymentProvider, externalId: string, handler: () => Promise<T>): Promise<T> {
-        return QueueHandler.schedule('settlement-sync-' + provider + '-' + externalId, handler);
+    static lock<T>(provider: PaymentProvider, externalId: string, handler: (abort: AbortSignal) => Promise<T>, { abort }: { abort?: AbortSignal } = {}): Promise<T> {
+        return QueueHandler.schedule('settlement-sync-' + provider + '-' + externalId, async (o) => {
+            const signal = abort ?? o.abort;
+
+            // Waiting behind another settlement may have taken a while: don't start a walk that is
+            // interrupted at its first step anyway
+            signal.throwIfAborted();
+
+            return await handler(signal);
+        });
     }
 
     /**
@@ -306,7 +322,7 @@ export class SettlementService {
      * settlement (a transaction can move to another payout). Rows that only exist because of the
      * payout are deleted; rows that outlive the payout link are only unlinked: derived fee lines
      * (owned by updatePaymentSettlementsForAccountDeductionPayment), deduction charges referenced
-     * by an application fee (RESTRICT FK), and the application fee rows themselves.
+     * by an application fee, and the application fee rows themselves.
      *
      * Returns the fees unlinked from this settlement, so the caller can refresh the derived lines
      * of their fee payments.
@@ -376,7 +392,9 @@ export class SettlementService {
      * Recomputes the cached reconciliation columns from the stored rows: `unexplainedAmount` should
      * be 0 — a non-zero value is a real question to answer — and `pendingFees` holds what is
      * received but not invoiced yet, which takes up to a month and only becomes a problem when it
-     * stays non-zero too long.
+     * stays non-zero too long. Fees the invoicer can never bill land in `uncollectibleFees`
+     * instead: they explain their part of the payout, but waiting for them to be invoiced is
+     * waiting forever.
      *
      * Every write that changes what a payout holds ends here, or the export and the problem report
      * keep reading numbers from the last sync.
@@ -405,10 +423,46 @@ export class SettlementService {
         const pendingFees = await ApplicationFee.select()
             .where('settlementId', settlement.id)
             .where('balanceItemId', null)
+            .where('payingOrganizationId', '!=', null)
+            .where('payingStripeAccountId', '!=', null)
+            .sum(SQL.column('amount')) ?? 0;
+
+        // The negation of what the invoicer bills (ApplicationFeeInvoicer#selectBillableFees), so
+        // every uninvoiced fee sits in exactly one of the two sums
+        const uncollectibleFees = await ApplicationFee.select()
+            .where('settlementId', settlement.id)
+            .where('balanceItemId', null)
+            .where(
+                SQL.where('payingOrganizationId', null)
+                    .or('payingStripeAccountId', null),
+            )
             .sum(SQL.column('amount')) ?? 0;
 
         settlement.pendingFees = pendingFees;
-        settlement.unexplainedAmount = settlement.amount - paymentSum - chargeSum - pendingFees;
+        settlement.uncollectibleFees = uncollectibleFees;
+        settlement.unexplainedAmount = settlement.amount - paymentSum - chargeSum - pendingFees - uncollectibleFees;
+    }
+
+    /**
+     * The payouts holding application fees this organization paid: after deleting it, they have to
+     * recount, because those fees moved from pending to uncollectible.
+     */
+    static async getApplicationFeeSettlementIdsForPayingOrganization(organizationId: string): Promise<string[]> {
+        // An organization has one fee row per payment per type, so they are never all loaded at
+        // once just to collect the handful of payouts behind them
+        const settlementIds = new Set<string>();
+
+        for await (const fees of ApplicationFee.select()
+            .where('payingOrganizationId', organizationId)
+            .where('settlementId', '!=', null)
+            .limit(FEE_BATCH_SIZE)
+            .allBatched()) {
+            for (const fee of fees) {
+                settlementIds.add(fee.settlementId!);
+            }
+        }
+
+        return [...settlementIds];
     }
 
     /**
@@ -532,6 +586,18 @@ export class SettlementService {
         }
     }
 
+    /**
+     * A walk that was interrupted halfway (a restart aborted it) stored only part of what the
+     * provider reports, so the settlement may not keep claiming it is synced: the next run walks it
+     * again. Unlike a failed sync it doesn't count towards the retry cap — nothing is wrong with
+     * this settlement.
+     */
+    static async markSyncInterrupted(settlement: Settlement): Promise<Settlement> {
+        settlement.syncedAt = null;
+        await settlement.save();
+        return settlement;
+    }
+
     /**
      * A failed sync leaves syncedAt NULL: that is the whole error queue.
      */