Your accountant opens Payment Reconciliation, picks the customer, clicks "Get Unreconciled Entries", and the page hangs until the request times out. The customer has hundreds of open payments against hundreds of open invoices, and across fifty active customers, manual matching becomes a full-time job. This guide covers what ERPNext already gives you (fetch limits and the Auto Reconcile Payments background job), then a custom layer on top: batching by party, matching rules (exact amount, reference number, date proximity) and a nightly job that leaves the accountant only the exceptions.
Payment Reconciliation slows down with the product of payments and invoices: the allocation step walks unreconciled payments against unreconciled invoices for the same party. A hundred of each is quick; thousands of each in one web request is not. The fix is not a bigger server. It is smaller pieces of work, moved off the web request, with rules that settle the easy matches. I am Manoj, and I lead ERPNext and Frappe programmes at MithTech, a team of Frappe specialists in Bengaluru. Automating month-end reconciliation is one of the changes our client accounting teams notice most.
Why does Payment Reconciliation time out?
"Get Unreconciled Entries" loads the unreconciled payments and invoices for the selected party, and "Allocate" then walks payments against invoices. Work grows with payments × invoices.
Calculator
Timeout Calculator
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.
The calculator uses a conservative 60-second limit; a standard bench sets the web worker's timeout from http_timeout, 120 seconds unless someone changed it. Either way the root cause is the same: everything happens in one web request. Check two things first:
- Invoice Limit and Payment Limit on the Payment Reconciliation form default to 50. When someone sets them to 0 to "see everything", the tool fetches every open entry for the party and the request runs out of time. Put the limits back and use the date and amount filters to work through the party in slices.
- Auto Reconcile Payments in Accounts Settings. With it on (and the scheduler running), reconciliation is queued as a Process Payment Reconciliation document and runs in the background in batches, sized by Reconciliation Queue Size, instead of inside the browser request.
For many companies those two settings are enough. The rest of this guide is for when you also want ERPNext to decide the matches, not only to process the ones you allocate.
How does auto-matching work?
Auto-matching applies three rules in priority order. The Reconciliation Simulator shows them in action:
Interactive
Reconciliation Simulator
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). The payment amount matches the invoice amount within ₹0.01. For customers who pay invoice by invoice, this rule settles most entries.
- Reference number match (medium confidence). The payment's reference number contains the invoice number. This catches customers who quote the invoice number in the bank transfer.
- 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 and advance payments, and an accountant should review these.
How do you fix it with batching, matching rules and a schedule?
Code recipe
Reconciliation Recipe
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.
0 of 5 steps done
Tick a step’s number when it is done; the ticks stay on this device.
Deploy the batch reconciler
Create a custom app or add the batch_reconcile function to your existing app. It processes unreconciled entries by party, 100 payments at a time, so each chunk finishes well inside the timeout. 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. It applies the three matching rules and returns matches with confidence scores. Call it in the batch reconciler before pr.allocate_entries, so the allocation follows your rules instead of ERPNext's default oldest-first allocation.
Set up the scheduled job
Add the daily_reconcile function to your app's hooks.py under scheduler_events → daily. It runs once a day when the scheduler fires daily events, goes through each company, checks for unreconciled entries and runs the batch reconciler. Check the Error Log daily for the first week to catch matching problems.
Import bank statements
Use the import_bank_statement function to create Payment Entries from bank statement CSVs. Adjust the identify_party function to match your bank's description format to customer names. Once the Payment Entries exist, the nightly job matches them to invoices.
Monitor and tune
After a week of scheduled runs, check: what share of entries were auto-matched, how many exceptions need review, and whether any match was wrong (a payment allocated to the wrong invoice). Adjust the date_threshold parameter (default 7 days) to your customers' payment habits.
Matching payments to invoices is one part of reconciliation. Another part compares the books with an outside record on a schedule and leaves a short list of differences. Reconciliation as a job runs that on sample data and says when it is overkill.
What is on the readiness checklist?
Before enabling auto-reconciliation, check your setup:
Interactive
Reconciliation Readiness Checklist
Eight configuration items to verify before enabling automated Payment Reconciliation — from account setup to error monitoring.
What should you know before you commit?
Auto-matching is auto-reconciling. The batch reconciler allocates and reconciles, which is the same as clicking "Reconcile" in the form: it links the payment to the invoice and changes both outstanding amounts (and posts an exchange gain or loss entry where currencies differ). A wrong match has to be undone with Unreconcile on the payment. For the first month, review the daily log before trusting it.
Partial payments need their own handling. If a customer pays ₹40,000 against a ₹45,000 invoice, the exact-amount rule won't match. The date-proximity rule might, at low confidence. Consider a fourth rule, "same party, amount within 10% of the invoice, closest date", also at low confidence.
Multi-currency. The scripts assume single-currency (INR) matching. For foreign-currency parties, filter by the party's account currency and decide whether you match on transaction or base amounts; ERPNext stores both, and the exchange difference posts at reconciliation. ERPNext multi-currency setup covers the accounts that difference needs.
Credit and debit notes. Payment Reconciliation can also match credit notes against invoices. The batch reconciler handles them: credit notes come through on the payments side, and the matching rules treat them like payments.
Suppliers. The scripts work for 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 receivables and payables overnight.
| Approach | Volume handled | Manual effort | Setup |
|---|---|---|---|
| Default form with fetch limits | Works party by party in slices | Every match by hand | None |
| Auto Reconcile Payments (built in) | Large parties, in background batches | You still decide the allocations | A setting + a running scheduler |
| Custom batching + matching rules | Large parties, in chunks | Low-confidence matches only | A custom app with the scripts |
| Batching + rules + nightly job | All parties, overnight | Exceptions reviewed daily | The custom app + hooks.py |
At a glance
| Answer | |
|---|---|
| Why does it time out? | One web request fetches and allocates every open entry for the party |
| First check | Invoice Limit and Payment Limit (default 50; 0 fetches everything) |
| Built-in fix | Accounts Settings → Auto Reconcile Payments, with the scheduler running |
| Custom fix | Batch by party, match by amount → reference → date, run nightly |
| Undoing a wrong match | Unreconcile on the payment |
| Who reviews what | An accountant reviews low-confidence matches and exceptions |
Frequently asked questions
Why does ERPNext Payment Reconciliation time out?
It fetches the unreconciled payments and invoices for a party and allocates them inside one web request, and the work grows with payments × invoices. Once a party has thousands of open entries, or the fetch limits are set to 0, the request runs past the web worker's timeout. Keep the Invoice and Payment Limits, turn on Auto Reconcile Payments so reconciliation runs in the background, or process one party at a time in chunks.
How do I automate payment reconciliation in ERPNext?
Start with Accounts Settings → Auto Reconcile Payments, which runs reconciliation as a background job. To have ERPNext also choose the matches: (1) deploy the batch reconciler that processes by party in chunks, (2) add matching rules by exact amount, reference number and date proximity, (3) schedule it daily in hooks.py. Accountants review the low-confidence matches and exceptions.
Can ERPNext match payments to invoices automatically?
Out of the box, Payment Reconciliation allocates the payments you fetch to invoices oldest first, and you review and reconcile. With the matching rules in this guide, a custom app can match by exact amount and party (high confidence), reference number (medium) and date proximity within 7 days (low), and reconcile the confident ones on a schedule.
How do I import bank statements into ERPNext?
Use Bank Statement Import (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 the Payment Entries exist, the nightly reconciler matches them to invoices. ERPNext also has a Plaid integration for bank feeds in the countries Plaid supports.
What happens if auto-reconciliation matches the wrong payment to an invoice?
Reconciling links the payment to the invoice and changes both outstanding amounts. To undo a wrong match, use Unreconcile on the payment and pick the allocation to remove, then reconcile it correctly. For the first month, review the daily log to catch wrong matches, and tighten the rules (a higher confidence threshold or a shorter date_threshold) if they recur.
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 matching rules work the same for payables. Run customer and supplier reconciliation in the same scheduled job.
How do I handle partial payments in auto-reconciliation?
The exact-amount rule doesn't match partial payments, and the date-proximity rule may match them at low confidence. Add a fourth rule: "same party, payment within 10% of the invoice amount, closest date". Keep these at low confidence for manual review, because a partial payment often needs a judgment about which invoice it settles.
Which ERPNext version does this guide apply to?
The scripts target ERPNext v15. The Payment Reconciliation DocType and its allocate_entries and reconcile methods behave the same on v14 and v15, and the scripts use standard Frappe ORM calls. Auto Reconcile Payments and Process Payment Reconciliation are in v15; check your version's Accounts Settings before building custom code, because the built-in job may already be enough.
Payment Reconciliation at scale is a batching problem, not a screen problem. Keep the fetch limits, let the built-in background job carry large parties, and add the matching rules and nightly job when you want ERPNext to choose the matches too. Review the exceptions for the first month, then let it run.
Comments & ratings
No comments yet. Start a new discussion.
Manoj · Published on 4 August 2026
Worked with us? Leave a Google review