Skip to main content

ERPNext how-to & fixes

How to Automate Payment Reconciliation in ERPNext (Fix the Timeout)

ERPNext Payment Reconciliation times out on parties with thousands of open entries. Fix it with fetch limits, background jobs, batching and matching rules.

Updated 14 Oct 202612 min readBy ManojFirst published 4 Aug 2026

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.

Without batching
Total comparisons1,00,00,000
Estimated time55.6h

Timeout

With batching (chunks of 100)
Comparisons per batch5,00,000
Time per batch2.8h
Total batches20

At ~50 comparisons/sec (typical for Payment Reconciliation with DB lookups). Timeout threshold: 60 seconds. See GitHub #41581 (timeout), #43272 (performance improvement).

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.

Unreconciled Payments
PE-001₹45,000
Customer A · 2026-07-15
PE-002₹1,23,500
Customer B · 2026-07-18
PE-003₹45,000
Customer A · 2026-07-22
PE-004₹78,200
Customer C · 2026-07-25
PE-005₹2,34,000
Customer D · 2026-07-28
Unreconciled Invoices
SINV-001₹45,000
Customer A · 2026-07-10
SINV-002₹1,23,500
Customer B · 2026-07-12
SINV-003₹45,000
Customer A · 2026-07-20
SINV-004₹78,200
Customer C · 2026-07-23
SINV-005₹2,34,000
Customer E · 2026-07-26

The three matching rules:

  1. 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.
  2. 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.
  3. 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.

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.

python
# 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}

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.

0 of 8 done

Nothing here is saved — this is a checklist for your current setup, not your ERPNext instance.

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.

ApproachVolume handledManual effortSetup
Default form with fetch limitsWorks party by party in slicesEvery match by handNone
Auto Reconcile Payments (built in)Large parties, in background batchesYou still decide the allocationsA setting + a running scheduler
Custom batching + matching rulesLarge parties, in chunksLow-confidence matches onlyA custom app with the scripts
Batching + rules + nightly jobAll parties, overnightExceptions reviewed dailyThe custom app + hooks.py
Payment Reconciliation approaches, from manual to automated

At a glance

Answer
Why does it time out?One web request fetches and allocates every open entry for the party
First checkInvoice Limit and Payment Limit (default 50; 0 fetches everything)
Built-in fixAccounts Settings → Auto Reconcile Payments, with the scheduler running
Custom fixBatch by party, match by amount → reference → date, run nightly
Undoing a wrong matchUnreconcile on the payment
Who reviews whatAn 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.

Live demo

Your next step

Payment reconciliation eating your accounting team's time?

Accounts and payments

The bank statement matches itself

1 screen · about 3 min · you end with the bank reconciled

Bank TransactionReconciled

A line from the bank statement, matched to the invoice it pays; you review only the odd one.

From
The bank statement
Matched to
Its invoice

Mith Demo Traders · demo company

ERPNext how-to & fixes

Now see what an audit finds in yours

When the same problems keep coming back, tick what you see and get an audit of the ERPNext you have, then fixes in order of what costs you most.

Comments & ratings

No comments yet. Start a new discussion.

0

Manoj · Published on 4 August 2026

Worked with us? Leave a Google review

Questions about this? Talk to the team.

Book a 30-minute Google Meet, WhatsApp us, or send a message. The engineer who works on this replies.

Send us a message

Your details go to our team's CRM and are used only to reply.