ns_erpnext_app/docs/CUSTOMER_STATEMENTS.md

Customer Statements & Late Payment Fees

Branch: feature/customer-statements

Generates printable, one-page-per-customer account statements — formatted to fit a standard #9 (9x4) double-window envelope — for customers with overdue invoices, and (optionally) bills a late-payment fee that posts to the ledger and is collectible through the app's existing payment flow.

---

1. What it does

From either the Customer list or a Customer form, a user can generate account statements:

1. Pick customers. On the list, Generate Statements opens a dialog listing every customer with overdue invoices (overdue count, max days overdue, total outstanding) with select-all. On a Customer form, Generate Statement targets that one customer.
2. Choose whether to bill a late fee via a checkbox in the popup (Generate late payment fee, on by default).
3. Get a printable report. A new browser tab opens with one statement per page — each showing the customer's open invoices, aging buckets (Current / 1–30 / 31–60 / 61–90 / 90+), and a Total Due. The customer and company (return) addresses sit in the two envelope-window positions.

Each generation is recorded on the customer's timeline as an audit-trail entry.

---

2. Late payment fees

How the fee is calculated

Interest uses ERPNext's own Dunning formula, accrued from the last fee run rather than from each invoice's due date, so no period is ever billed twice:

accrue_from = max(invoice.due_date, last_billed_upto)
interest    = Σ(invoice.outstanding × rate_of_interest/100/365 × days_since(accrue_from))
charge      = interest + dunning_fee   # flat fee only when raising a new fee invoice
            = interest                 # when topping up an existing one

The Σ runs over every overdue invoice, unpaid late-fee invoices included — they are receivables like any other and are charged on the same terms.

last_billed_upto is stored on the fee invoice itself (custom_late_fee_billed_upto). Fee invoices raised before that field existed fall back to their posting date, which is when they were billed.

The flat dunning_fee is a one-off charge for falling into collections, applied when a fee invoice is first raised — not again on every top-up.

Where the settings live — ERPNext Dunning Type

All fee configuration comes from the existing Dunning Type doctype (Accounting ▸ Dunning Type). Nothing is auto-created; generation stops with a clear error until it is configured. The default (is_default) Dunning Type for the company is used. Fields consumed:

Dunning Type field	Purpose
rate_of_interest	Annual interest rate (%)
dunning_fee	Flat fee, charged once when a fee invoice is raised
income_account	Credited when the fee is billed
cost_center	Cost center for the fee line (falls back to company default)
custom_late_fee_item	Late Fee Item — the Item used to bill the fee (custom field added by this app)

How the fee posts, and how it gets paid

The fee is billed as a submitted Sales Invoice (item → the Dunning Type income account). This is deliberate: because it is a real Sales Invoice it

• increases the customer's receivable balance immediately, and
• appears in get_unpaid_invoices and is charged/settled automatically by the app's existing payment paths (Run Payment / AutoPay / multi-invoice → create_payment_entry), which allocate against Sales Invoices.

A bare Journal Entry (or an ERPNext Dunning document) would raise the balance but sit uncollectible by those flows — hence the Sales Invoice.

Fee invoice specifics

• Dedicated naming series LPF-.YYYY.- (e.g. LPF-2026-00001) so late-fee invoices are easy to spot and filter. Registered on Sales Invoice's naming_series via after_migrate.
• Never taxed. A single zero-amount "Actual" tax line keeps ERPNext from auto-applying company/item tax templates, so the invoice total equals the computed fee exactly and nothing extra hits the ledger.
• Idempotent — at most one charge per customer / company / calendar month. An unpaid fee invoice accrues interest on the same terms as any other overdue receivable (see below).

On the statement the fee shows as a normal invoice line tagged “late fee”, folded into a single Total Due that equals the customer's balance.

One fee invoice per collections episode

While an earlier fee invoice still carries a balance, the next run amends it and appends the new period's interest as a further line item, instead of raising a second invoice. The customer sees one growing charge, itemised by period.

Amending means cancelling and re-raising, so the invoice number gains a suffix (LPF-2026-00001 → LPF-2026-00001-1). The original posting and due dates are carried over deliberately: re-dating to today would reset the invoice to Current in the statement's aging buckets and hide how long the balance has been owed.

Partially paid fee invoices. Cancelling unlinks any Payment Entries, leaving the cash unallocated on them. After the amended invoice is submitted, each payment is re-applied to it via reconcile_against_document — the same primitive the Payment Reconciliation tool uses — so the outstanding amount and the Payment Ledger reflect what the customer actually owes. (As with any reconciliation, ERPNext clears against_voucher on the payment's GL rows and tracks the allocation on the Payment Ledger; the AR reports read the latter.)

When it can't amend. Cancelling is only reversible for links this app knows how to restore. If the open fee invoice has a Journal Entry or credit note applied, a negative payment allocation, or a posting date inside a frozen accounting period, it is left alone, the charge goes onto a new invoice, and the reason is recorded on the customer's timeline:

Late fee LPF-2026-00001 could not be amended (a Journal Entry is applied against it); the charge was billed on a new invoice.

Unpaid fee invoices accrue too

A late-fee invoice is an overdue receivable like any other, and once past its due date its outstanding balance is part of the interest base. Because the charge lands back on the invoice carrying that balance, interest compounds: each run adds interest on the fee balance the previous runs built up.

A customer whose only remaining overdue item is an unpaid fee invoice therefore keeps accruing — the balance grows by outstanding × rate/365 × days_since_last_run every run until it is paid. No new flat fee is raised while a fee invoice is open, so the growth is interest alone.

---

3. Configuration / prerequisites

1. Migrate the app (bench --site <site> migrate) — creates the Late Fee Item custom field on Dunning Type, the Late Fee Billed Upto custom field on Sales Invoice, and registers the LPF- series.
2. Create an Item to represent the fee (a non-stock sales item, e.g. "Late Payment Fee").
3. Create/complete a Dunning Type for the company with: rate of interest, dunning fee, income account, and the Late Fee Item. Mark it default.

If any of these is missing, statement generation throws a clear, actionable error and posts nothing.

---

4. Audit trail

Each generated statement adds an Info comment to the customer's timeline, e.g.

Statement generated — Total Due $557.17 (late fee charged on LPF-2026-00001-1).

The note reflects the outcome: the fee invoice raised, no late fee, or late fee skipped (when the fee checkbox was cleared). It is attributed to the generating user.

---

5. Files

File	Role
ns_app/api/statements.py	Overdue-customer query, statement builder, printable HTML, late-fee billing (Sales Invoice), audit-trail entry
ns_app/templates/statements/customer_statement.html	Jinja template for one customer page (envelope windows + aging table)
ns_app/public/js/customer_statements.js	List action + Customer-form button + selection/fee-toggle popups (loaded globally)
ns_app/setup.py	after_migrate: creates the Late Fee Item / Late Fee Billed Upto custom fields, registers the LPF- naming series
ns_app/hooks.py	Wires the JS (app_include_js) and after_migrate

Server API (ns_app.api.statements)

• get_customers_with_overdue_invoices() — customers with overdue invoices.
• generate_statements(customers, skip_late_fee=0) — bills fees (unless skipped), renders the printable HTML, records the audit entry. Returns {html, rendered, skipped}.
• get_statement_data(customer) — the per-customer statement data (internal).

Access is restricted to System Manager, Sales User/Manager, Accounts User/Manager.

---

6. Notes / non-goals

• No persisted "Statement" doctype — statements are generated on demand.
• No email/fax delivery — print only.
• Whether the fee should be taxed and the interest rate/fee amounts are business settings, controlled entirely through Dunning Type.