HMRC Obligation Reconciliation — Local vs Remote Drift Detection

HMRC Obligation Reconciliation

Overview

The HMRC Obligation Reconciliation workflow is a scheduled background process that automatically detects and corrects discrepancies between the platform's locally stored quarterly submission records and the live obligation data held by HMRC's Making Tax Digital (MTD) API.

Because submission outcomes can occasionally diverge from what HMRC records — due to network failures, API timeouts, or delayed processing — this weekly sweep ensures your submission history is always accurate and trustworthy.

Schedule

The reconciliation workflow runs automatically every Sunday at 01:00 UTC.

Cron expression: 0 1 * * 0

No manual intervention is required. The sweep is fully automated.

Eligibility

The sweep processes every organisation that meets both of the following criteria:

Has at least one connected HMRC credential on record
Has at least one quarterly_summary that has previously been submitted

Organisations without a connected HMRC credential or with no submission history are skipped.

Drift Detection

For each eligible organisation, the workflow:

Re-fetches the current obligation status for all relevant periods directly from the HMRC MTD API
Compares the HMRC-reported status against the locally stored hmrcObligationStatus and status fields on each quarterly_summary
Identifies mismatches and applies the appropriate correction

Scenario A — False Submitted

Condition: A local quarterly_summary is marked as submitted, but HMRC reports the corresponding obligation as Open.

This indicates the submission was not successfully recorded by HMRC, despite the local record suggesting otherwise.

Action:

hmrcObligationStatus is reset to Open
status is set to failed
The organisation is notified so the submission can be reviewed and resubmitted

Scenario B — Unacknowledged Fulfilment

Condition: A local quarterly_summary is in draft or failed state, but HMRC reports the corresponding obligation as Fulfilled.

This indicates HMRC accepted a submission that was not properly acknowledged on the platform side.

Action:

status is updated to submitted
hmrcObligationStatus is updated to Fulfilled
The organisation is notified that their obligation is confirmed as met

Notifications

When a drift correction is applied, the affected organisation receives a notification informing them of:

Which quarterly period was affected
The previous local status
The corrected status, as confirmed by HMRC

This ensures landlords are always aware of any changes to their submission records.

Audit Log

Every discrepancy detected by the sweep — whether correctable or not — is written to the audit_log. Each log entry captures:

The organisation and period affected
The before and after state of the quarterly_summary
The timestamp of the reconciliation run
The source of truth used (HMRC API response)

This provides a full compliance trail for every correction made by the system.

Entities Involved

Entity	Role
`hmrc_credentials`	Identifies organisations with an active HMRC connection
`hmrc_businesses`	Resolves MTD-registered businesses for each organisation
`quarterly_summaries`	The primary records checked and updated during the sweep
`audit_log`	Receives a log entry for every discrepancy detected
`notifications`	Delivers status-change alerts to affected organisations

Frequently Asked Questions

Will this workflow change a submission that HMRC has marked as Fulfilled? No. If HMRC reports a period as Fulfilled, the workflow will only update a local record that is in draft or failed state to reflect that fulfilment. It will never downgrade a locally submitted record that HMRC has confirmed.

What happens if HMRC's API is unavailable during the sweep? If the HMRC API cannot be reached for a given organisation during a sweep run, that organisation is skipped for that cycle and will be re-evaluated in the following week's run. No incorrect corrections are applied on the basis of a failed API call.

Can I trigger a reconciliation manually? Currently, reconciliation runs on the weekly schedule only. Manual triggering is not available through the UI.

Where can I see what was changed? All changes are recorded in the audit_log. Contact your account administrator for access to audit log entries.