Your accountant opens Payment Reconciliation, selects the customer, clicks "Get Unreconciled Entries", and the page hangs. After 60 seconds, a timeout error. The customer has 200 unreconciled payments against 800 invoices — 160,000 comparisons. Multiply that across 50 active customers, and manual reconciliation is a full-time job that ERPNext's default tool cannot handle at scale. GitHub #41581 reports the timeout. GitHub #43272 discusses performance improvements. This guide fixes the timeout with batch processing, adds auto-matching rules (exact amount, reference number, date proximity), and sets up a daily scheduled job that reconciles overnight.
Manufacturing or quality inspection?
Payment Reconciliation is the accounting side. For production planning, see the Production Plan partial fulfillment guide. For quality control in manufacturing, see the Quality Inspection guide.
Payment Reconciliation in ERPNext is an O(n × m) problem — every unreconciled payment is compared against every unreconciled invoice for the same party. At 100 payments × 200 invoices, this is 20,000 comparisons and takes a few seconds. At 2000 × 5000, it is 10 million comparisons and exceeds the HTTP timeout. The fix is not a bigger server — it is processing in batches by party and applying auto-matching rules to eliminate the need for manual intervention. I am Manoj, ERP implementation lead at Mith Tech in Bengaluru, and automating month-end reconciliation is one of the most impactful improvements we make for our accounting teams.
Why reconciliation times out
Payment Reconciliation's "Get Unreconciled Entries" button loads every unreconciled payment and every unreconciled invoice for the selected party, then compares them in the browser. The comparison is O(n × m) — payments × invoices.
Enter your number of unreconciled payments and invoices to see the total comparisons needed, estimated processing time, and whether you will hit the 60-second timeout — with and without batching.
At ~50 comparisons/sec (typical for Payment Reconciliation with DB lookups). Timeout threshold: 60 seconds. See GitHub #41581 (timeout), #43272 (performance improvement).
The root cause is not the comparison logic — it is loading everything in one request. ERPNext's default Payment Reconciliation fetches all unreconciled entries for a party before matching. For a customer with 200 payments and 800 invoices, this is 160,000 comparisons in a single HTTP request. The Gunicorn worker thread hits the 60-second timeout and the request fails.
How auto-matching works
Auto-matching eliminates manual work by applying three rules in priority order. The Reconciliation Simulator shows this in action:
Watch five sample payments auto-match to five invoices using exact amount, customer match, and date proximity rules. Each match gets a confidence score — High, Medium, or Low — and unmatched entries show the reason.
The three matching rules:
- Exact amount + same party (High confidence). Payment amount matches invoice amount within ₹0.01. This catches the majority of cases — 60–70% of payments match an invoice exactly.
- Reference number match (Medium confidence). The payment's reference number contains the invoice number. This catches cases where the customer includes the invoice number in the bank transfer description.
- Date proximity + same party (Low confidence). Payment and invoice are for the same party and within 7 days of each other. This is the fallback for partial payments and advance payments. These matches should be reviewed by the accountant.
The fix — batch processing + auto-matching + scheduling
Four-tab Python recipe: batch reconciler that processes by party in chunks, auto-match rules with confidence scoring, scheduled daily job, and bank statement CSV import. Deploy all four for fully automated reconciliation.
Processes payments in chunks to avoid the 60-second timeout on large datasets. Each batch commits independently so a failure in batch N does not roll back batches 1 through N-1.
# Batch Payment Reconciliation
# Processes in chunks to avoid timeout
# See: GitHub #41581, #43272
import frappe
def batch_reconcile(
company: str,
party_type: str = "Customer",
batch_size: int = 100,
):
"""Reconcile payments in batches to avoid
the 60-second timeout on large datasets."""
parties = frappe.get_all(
"Payment Entry",
filters={
"company": company,
"party_type": party_type,
"docstatus": 1,
"unallocated_amount": [">", 0],
},
fields=["party"],
group_by="party",
)
total_reconciled = 0
for party_row in parties:
party = party_row.party
pr = frappe.new_doc("Payment Reconciliation")
pr.company = company
pr.party_type = party_type
pr.party = party
pr.receivable_payable_account = (
frappe.get_cached_value(
"Company", company, "default_receivable_account"
)
)
# Get unreconciled entries
pr.get_unreconciled_entries()
if not pr.invoices or not pr.payments:
continue
# Process in batches
for i in range(0, len(pr.payments), batch_size):
batch_payments = pr.payments[i : i + batch_size]
# Match by amount and party
pr.allocate_entries({
"payments": batch_payments,
"invoices": pr.invoices,
})
if pr.allocation:
try:
pr.reconcile()
total_reconciled += len(pr.allocation)
frappe.db.commit()
except Exception as e:
frappe.log_error(
f"Reconciliation failed for {party}: {e}"
)
frappe.db.rollback()
return {"total_reconciled": total_reconciled}Deploy the batch reconciler
Create a custom app or add the batch_reconcile function to your existing app. This processes unreconciled entries by party, in chunks of 100 payments at a time. Each chunk runs within the timeout window. Call it from a Whitelisted API endpoint or from the bench console: bench execute your_app.reconciliation.batch_reconcile --kwargs '{"company": "Your Company"}'.
Add auto-matching rules
Deploy the auto_match_entries function. This applies the three matching rules and returns matches with confidence scores. Integrate it into the batch reconciler — call auto_match_entries before pr.allocate_entries to use smart matching instead of ERPNext's default first-match approach.
Set up the scheduled job
Add the daily_reconcile function to your app's hooks.py under scheduler_events → daily. This runs every night at midnight (or whenever the scheduler fires daily events). It iterates over all companies, checks for unreconciled entries, and runs the batch reconciler for each. Check the Error Log daily for the first week to catch any matching issues.
Import bank statements
Use the import_bank_statement function to create Payment Entries from bank statement CSVs. Customise the identify_party function to match your bank's description format to customer names. Once Payment Entries exist, the scheduled reconciler matches them to invoices overnight.
Monitor and tune
After a week of scheduled reconciliation, check: (1) what percentage of entries are auto-matched? (2) How many exceptions need manual review? (3) Are any false matches occurring (wrong invoice matched to wrong payment)? Adjust the date_threshold parameter (default 7 days) based on your business patterns.
Readiness checklist
Before enabling auto-reconciliation, verify your setup:
Eight configuration items to verify before enabling automated Payment Reconciliation — from account setup to error monitoring.
Payment Reconciliation pre-flight
Nothing here is saved — this is a checklist for your current setup, not your ERPNext instance.
What to know before you commit
Auto-matching is not auto-approving. The batch reconciler creates allocations and reconciles them, which is the same as clicking "Reconcile" in the UI. This creates Journal Entries that adjust the outstanding amounts. If a match is wrong, you need to reverse the Journal Entry. For the first month, review the daily reconciliation log before trusting it fully.
Partial payments need special handling. If a customer pays ₹40,000 against a ₹45,000 invoice, the exact-amount rule will not match. The date-proximity rule might match it, but with low confidence. Consider adding a fourth rule: "same party, amount within 10% of invoice" for partial payments.
Multi-currency reconciliation. The scripts above assume single-currency (INR) matching. For multi-currency, add a currency_code filter to the matching rules and handle exchange rate differences. ERPNext stores amounts in base currency on Payment Entry and invoice — match on base currency amounts.
Credit notes and debit notes. Payment Reconciliation in ERPNext can also match credit notes against invoices. The batch reconciler handles this — credit notes appear as negative amounts in the invoices list. The auto-match rules work the same way.
Supplier reconciliation. The scripts work for both Customers and Suppliers — change party_type from "Customer" to "Supplier" and switch from default_receivable_account to default_payable_account. Run both in the scheduled job to reconcile payables and receivables overnight.
+Why does ERPNext Payment Reconciliation time out?
Payment Reconciliation loads all unreconciled payments and invoices for a party in a single HTTP request, then compares them in O(n × m) time. With 2000+ payments and 5000+ invoices, this exceeds 10 million comparisons and hits the 60-second Gunicorn timeout. The fix is batch processing — process one party at a time in chunks of 100 payments.
+How do I automate payment reconciliation in ERPNext?
Three steps: (1) Deploy the batch reconciler script that processes by party in chunks, (2) add auto-matching rules that match by exact amount, reference number, and date proximity, (3) set up a daily scheduled job in hooks.py. This runs overnight and matches 80–90% of entries automatically. Accountants review the remaining exceptions.
+Can ERPNext match payments to invoices automatically?
ERPNext's default Payment Reconciliation requires manual matching in the UI. With the auto-matching rules in this guide, you can automatically match payments to invoices by: exact amount + party (high confidence), reference number (medium), and date proximity within 7 days (low). Deploy as a custom app function.
+How do I import bank statements into ERPNext?
Use the Bank Statement Import tool (Accounting → Bank Statement Import) or the CSV import script in this guide. The script creates Payment Entries from bank statement rows, matching bank descriptions to customer names. Once Payment Entries exist, the auto-reconciler matches them to invoices. ERPNext also supports Plaid integration for automatic bank feeds in supported countries.
+What happens if auto-reconciliation matches the wrong payment to an invoice?
The reconciliation creates a Journal Entry adjusting outstanding amounts. If the match is wrong, reverse the Journal Entry (amend and cancel or create a reversal entry). For the first month, review the daily reconciliation log to catch false matches. Tune the matching rules — increase the confidence threshold or reduce the date_threshold if false matches are too frequent.
+Can I reconcile supplier payments the same way?
Yes. Change party_type from "Customer" to "Supplier" and switch the account from default_receivable_account to default_payable_account. The batch reconciler and auto-match rules work identically for payables. Run both Customer and Supplier reconciliation in the scheduled job.
+How do I handle partial payments in auto-reconciliation?
The exact-amount rule does not match partial payments. The date-proximity rule might match them with low confidence. For better partial payment handling, add a fourth rule: "same party, payment amount within 10% of invoice amount, closest date". Mark these as low confidence for manual review — partial payments often need judgment about which invoice the payment applies to.
+What ERPNext version does this guide apply to?
This guide targets ERPNext v15. The Payment Reconciliation doctype, allocate_entries method, and reconcile method have been stable across v14 and v15. The batch processing and auto-matching scripts use standard Frappe ORM calls. GitHub #43272 introduced some core performance improvements in v15 — check if your version includes them before deploying custom fixes.
Payment Reconciliation at scale is a batch processing problem, not a UI problem. ERPNext's default tool works for small volumes but breaks at 500+ entries per party. The batch reconciler fixes the timeout. The auto-matching rules eliminate 80–90% of manual work. The scheduled job means reconciliation happens overnight instead of at month-end. Deploy all three, review exceptions for the first month, then let it run.
Payment reconciliation eating your accounting team's time?
We automate accounting workflows in ERPNext — payment reconciliation, bank imports, and month-end closing. If your team spends days on manual matching, we will set up the batch reconciler and auto-matching rules.