Nightly Deduction Amount Reconciliation Check

Available from: v0.1.261

Overview

The Deduction Amount Reconciliation Check is a scheduled background workflow that runs every night at 2:30 AM UTC. It validates the financial consistency of every active (non-released) deposit release, ensuring that the deduction line items and the three-way deposit split always balance to the total deposit amount held.

This workflow acts as an automated integrity net — catching data inconsistencies caused by partial updates, failed transactions, or manual data corrections before they can affect compliance reporting or dispute outcomes.

What Is Checked

For every deposit_release record where status != 'released', two equations are verified:

1. Deductions Total Consistency

deductionsTotal = SUM(deposit_release_deductions.amount)

The deductionsTotal stored on the deposit_release row must equal the live sum of all associated deposit_release_deductions line items. A mismatch here typically indicates a deduction was added, removed, or amended without the summary field being updated.

2. Deposit Balance Equation

tenantReturnAmount + deductionsTotal + landlordAmount = totalDepositAmount

The three components — what is returned to the tenant, what is deducted, and what is credited to the landlord — must collectively equal the total deposit amount held. Any remainder or shortfall is flagged.

How Discrepancies Are Surfaced

When either check fails for a deposit release, the workflow automatically:

Inserts an error notification for every org admin in the affected organisation, visible in their admin notification feed.
Writes an audit log entry recording the deposit release identifier, the nature of the mismatch, and the timestamp of detection.

No automatic financial correction is applied. The workflow is purely detective — it surfaces the problem so that a human reviewer can investigate and resolve it.

Schedule & Sequencing

Property	Value
Cron expression	`30 2 * * *`
Run time	2:30 AM UTC, every day
Runs after	`compliance-nightly-sweep`

The job is deliberately sequenced after compliance-nightly-sweep to avoid database contention and to ensure compliance checks complete before reconciliation reads the same records.

Entities

Entity	Role
`deposit_releases`	Records evaluated for balance integrity
`deposit_release_deductions`	Line items summed and compared against `deductionsTotal`
`tenancies`	Provides tenancy context for affected releases
`properties`	Provides property context via the tenancy
`notifications`	Receives the error notification on mismatch
`org_members`	Identifies which users hold the org admin role
`audit_log`	Receives an immutable record of every detected discrepancy

Responding to a Reconciliation Alert

When an org admin receives a reconciliation error notification, the recommended investigation steps are:

Identify the affected deposit release from the notification or audit log entry.
Compare deductionsTotal against the individual deposit_release_deductions rows to find any orphaned or missing line items.
Check the balance equation — confirm tenantReturnAmount, deductionsTotal, and landlordAmount against totalDepositAmount.
Correct the discrepancy manually or via the deposit release edit workflow, ensuring both equations balance before proceeding.
Verify the corrected release passes the next nightly run without generating a new alert.

If the same release continues to generate alerts after correction, escalate to your platform support contact and include the relevant audit log entries.

Scope Exclusion

Deposit releases in released status are excluded from evaluation. Once a release has been finalised, its financial figures are considered immutable and are not re-checked by this workflow.