nsinnovations/ns_erpnext_app
2
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(statements): top up open late-fee invoices instead of stacking new ones

Browse Source 
Statement generation raised a fresh LPF invoice every month, so a customer
who never paid accumulated a pile of small invoices, each carrying the flat
dunning_fee again. Interest was also recomputed from each invoice's due date
every run, re-billing periods already charged for.

Now a customer gets 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, rather
  than creating a second invoice.
- Payment Entries allocated to a partly paid fee invoice are unlinked by the
  cancellation and re-applied to the amended invoice via
  reconcile_against_document (the primitive Payment Reconciliation uses), so
  the outstanding amount and Payment Ledger stay correct.
- Original posting and due dates are carried over. 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.
- Interest accrues from the last run, tracked by a new
  custom_late_fee_billed_upto field on Sales Invoice, so no period is billed
  twice. Fee invoices predating the field fall back to their posting date,
  which is when they were billed, so no migration patch is needed.
- The flat dunning_fee is charged once, when a fee invoice is first raised,
  not again on every top-up.
- Unpaid fee invoices are in the interest base on the same terms as any
  other overdue receivable, so interest compounds onto the fee balance.

Amending means cancelling, which is only reversible for links we can
restore. If the open fee invoice has a Journal Entry or credit note applied,
a negative payment allocation, or a posting date in a frozen period, it is
left alone, the charge goes on a new invoice, and the reason is recorded on
the customer's timeline.

Verified against nsi.local with two rolled-back integration probes covering
the amend + re-link path (including two consecutive amendments) and the
blocked-amend fallback.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Norman King
2026-08-13 06:15:55 -04:00
parent 192af42614
commit a08a02ad4b
3 changed files with 392 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

370
ns_app/api/statements.py
View File

@@ -16,6 +16,10 @@ from frappe.utils import flt, fmt_money, getdate, nowdate
# Dedicated naming series so late-fee invoices are easy to spot and filter.
LATE_FEE_NAMING_SERIES = "LPF-.YYYY.-"
# Custom field on Sales Invoice recording the date interest was last charged, so
# the next run accrues from there instead of re-charging from the due date.
BILLED_UPTO_FIELD = "custom_late_fee_billed_upto"
# Roles allowed to run collections/statement actions.
ALLOWED_ROLES = [
"System Manager",
@@ -264,6 +268,16 @@ def _wrap_document(pages):
# (item -> Dunning Type income account) so it both hits the ledger and is
# collectible by the app's existing payment flow (Run Payment / AutoPay /
# multi-invoice), which settles Sales Invoices.
#
# A customer gets **one** fee invoice per collections episode, not one per
# month: while an earlier fee invoice still carries a balance, the next run
# amends it and appends the new period's interest as another line, so the
# customer sees a single growing charge instead of a stack of small ones. The
# flat dunning_fee is a one-off for falling into collections and is charged only
# when a fee invoice is first raised. Interest accrues from the last run
# (BILLED_UPTO_FIELD), not from each invoice's due date, so no period is billed
# twice. An unpaid fee invoice is itself an overdue receivable and accrues on
# the same terms as any other, so interest compounds onto the fee balance.
DUNNING_TYPE_FIELDS = [
"name",
@@ -308,26 +322,270 @@ def _late_fee_period():
def _get_fee_invoices(customer, company, fee_item):
"""Return submitted late-fee Sales Invoices for a customer (by fee item)."""
"""Submitted late-fee Sales Invoices for a customer/company, newest first.
`distinct` matters: an amended fee invoice carries one item row per period
billed, so the join would otherwise return it several times.
"""
if not fee_item:
return []
return frappe.db.sql(
"""
select si.name, si.posting_date
select distinct si.name, si.posting_date, si.due_date, si.debit_to,
si.outstanding_amount, si.creation, si.{billed_upto} as billed_upto
from `tabSales Invoice` si
inner join `tabSales Invoice Item` sii on sii.parent = si.name
where si.customer = %s and si.company = %s and si.docstatus = 1
and sii.item_code = %s
""",
order by si.posting_date desc, si.creation desc
""".format(billed_upto=BILLED_UPTO_FIELD),
(customer, company, fee_item),
as_dict=True,
)
def _post_late_fee_invoice(customer, company, overdue_invoices, period):
"""Bill a late fee as a submitted Sales Invoice (idempotent per month).
def _last_billed_upto(fee_invoices):
"""Date late-fee interest was last charged, or None if it never has been.
Returns the fee invoice name, or None if nothing was billed.
Fee invoices raised before the marker field existed fall back to their
posting date, which is exactly when they were billed.
"""
dates = [getdate(fi.billed_upto or fi.posting_date) for fi in fee_invoices]
return max(dates) if dates else None
def _open_fee_invoice(fee_invoices):
"""The most recent fee invoice still carrying a balance, or None."""
for fi in fee_invoices:
if flt(fi.outstanding_amount) > 0:
return fi
return None
def _accrued_interest(overdue_invoices, rate_of_interest, last_billed_upto):
"""Interest accrued since the last fee run (or since each invoice fell due).
Charging on `days_overdue` every run would re-bill every period already
paid for, so each invoice accrues only from whichever is later: its due date
or the last time a fee was charged.
An unpaid late-fee invoice is an overdue receivable like any other and is
charged on the same terms — its balance accrues interest too, which then
lands back on the invoice carrying it.
"""
today = getdate(nowdate())
daily_interest = flt(rate_of_interest) / 100.0 / 365.0
interest = 0.0
for inv in overdue_invoices:
accrue_from = getdate(inv["due_date"])
if last_billed_upto and last_billed_upto > accrue_from:
accrue_from = last_billed_upto
days = (today - accrue_from).days
if days > 0:
interest += flt(inv["outstanding_amount"]) * daily_interest * days
return interest
def _amend_blockers(fee_invoice):
"""Reasons this fee invoice cannot safely be cancelled and re-raised.
Amending means cancelling, and cancelling is only reversible for the links
we know how to restore (plain Payment Entry allocations). Anything else is
left alone and billed on a fresh invoice instead.
"""
reasons = []
frozen = frappe.db.get_single_value("Accounts Settings", "acc_frozen_upto")
if frozen and getdate(fee_invoice.posting_date) <= getdate(frozen):
reasons.append(_("its posting date falls in a frozen accounting period"))
if frappe.db.exists(
"Journal Entry Account",
{"reference_type": "Sales Invoice", "reference_name": fee_invoice.name, "docstatus": 1},
):
reasons.append(_("a Journal Entry is applied against it"))
if frappe.db.exists(
"Sales Invoice", {"return_against": fee_invoice.name, "docstatus": 1}
):
reasons.append(_("a credit note is applied against it"))
if frappe.db.exists(
"Payment Entry Reference",
{
"reference_doctype": "Sales Invoice",
"reference_name": fee_invoice.name,
"docstatus": 1,
"allocated_amount": ("<", 0),
},
):
reasons.append(_("a payment allocates a negative amount to it"))
return reasons
def _payment_allocations(invoice_name):
"""Submitted Payment Entry allocations against an invoice, one row per entry.
Grouped per payment because re-linking consumes a payment's unallocated
balance in one go; two rows for the same entry would double-count it.
"""
return frappe.db.sql(
"""
select pe.name as payment_entry, pe.party_type, pe.party,
sum(per.allocated_amount) as allocated_amount,
max(per.account) as account
from `tabPayment Entry Reference` per
inner join `tabPayment Entry` pe on pe.name = per.parent
where per.reference_doctype = 'Sales Invoice'
and per.reference_name = %s
and per.docstatus = 1 and pe.docstatus = 1
and per.allocated_amount > 0
group by pe.name, pe.party_type, pe.party
""",
invoice_name,
as_dict=True,
)
def _relink_payments(amended, allocations):
"""Re-apply payments freed by the cancellation onto the amended invoice.
Cancelling unlinks the payments, leaving them sitting as unallocated cash on
their Payment Entries; this puts them back so the amended invoice shows the
balance the customer actually owes. `reconcile_against_document` is the same
primitive the Payment Reconciliation tool uses, so the ledger and the
invoice's outstanding amount are reposted the standard way.
"""
from erpnext.accounts.utils import reconcile_against_document
company_currency = frappe.get_cached_value("Company", amended.company, "default_currency")
in_company_currency = amended.party_account_currency == company_currency
remaining = flt(amended.outstanding_amount)
args = []
for alloc in allocations:
if remaining <= 0:
break
# The freed cash sits in unallocated_amount; that total is also what
# ERPNext validates the allocation against.
unallocated = flt(
frappe.db.get_value("Payment Entry", alloc.payment_entry, "unallocated_amount")
)
amount = min(flt(alloc.allocated_amount), unallocated, remaining)
if amount <= 0:
continue
args.append(
frappe._dict(
{
"voucher_type": "Payment Entry",
"voucher_no": alloc.payment_entry,
"voucher_detail_no": None,
"against_voucher_type": "Sales Invoice",
"against_voucher": amended.name,
"account": alloc.account or amended.debit_to,
"party_type": alloc.party_type,
"party": alloc.party,
"is_advance": "No",
"dr_or_cr": "credit_in_account_currency",
"unadjusted_amount": unallocated,
"allocated_amount": amount,
"exchange_rate": 1 if in_company_currency else amended.conversion_rate,
"grand_total": (
amended.base_grand_total if in_company_currency else amended.grand_total
),
"outstanding_amount": remaining,
"difference_account": frappe.get_cached_value(
"Company", amended.company, "exchange_gain_loss_account"
),
}
)
)
remaining -= amount
if args:
reconcile_against_document(args)
def _amend_fee_invoice(fee_invoice, charge, billed_upto):
"""Add a charge to an open fee invoice by amending it; return the new name.
The whole sequence runs inside the caller's transaction, so a failure
anywhere rolls back the unlink and the cancellation with it.
"""
from erpnext.accounts.utils import unlink_ref_doc_from_payment_entries
allocations = _payment_allocations(fee_invoice.name)
doc = frappe.get_doc("Sales Invoice", fee_invoice.name)
# Unlinking and reconciling narrate themselves with msgprint dialogs. A run
# covering fifty customers would bury the user in them, and the timeline
# comment already records what happened.
muted = frappe.flags.mute_messages
frappe.flags.mute_messages = True
try:
if allocations:
unlink_ref_doc_from_payment_entries(doc)
doc.cancel()
amended = frappe.copy_doc(doc, ignore_no_copy=False)
amended.amended_from = doc.name
amended.naming_series = LATE_FEE_NAMING_SERIES
# Same debt, so the original dates stand. Re-dating to today would
# reset the invoice to "Current" on the statement's aging buckets, which
# read from due_date, and hide how long the balance has been owed.
amended.set_posting_time = 1
amended.posting_date = doc.posting_date
amended.posting_time = doc.posting_time
amended.due_date = doc.due_date
amended.set(BILLED_UPTO_FIELD, billed_upto)
amended.append("items", charge)
amended.insert(ignore_permissions=True)
amended.submit()
if allocations:
amended.reload()
_relink_payments(amended, allocations)
finally:
frappe.flags.mute_messages = muted
return amended.name
def _new_fee_invoice(customer, company, settings, charge, billed_upto):
"""Raise a fresh late-fee Sales Invoice; return its name."""
si = frappe.new_doc("Sales Invoice")
si.naming_series = LATE_FEE_NAMING_SERIES
si.customer = customer
si.company = company
si.posting_date = nowdate()
si.due_date = nowdate()
si.set(BILLED_UPTO_FIELD, billed_upto)
si.append("items", charge)
# Late fees are not taxed. A single zero "Actual" tax line keeps the taxes
# table non-empty, which stops ERPNext from auto-applying the company or
# item tax templates; being zero it posts nothing to the ledger.
si.taxes_and_charges = ""
si.append(
"taxes",
{
"charge_type": "Actual",
"account_head": settings.income_account,
"description": _("Late fees are not taxed"),
"tax_amount": 0,
"rate": 0,
},
)
si.insert(ignore_permissions=True)
si.submit()
return si.name
def _post_late_fee_invoice(customer, company, overdue_invoices, period):
"""Bill late-payment interest for one customer/company (once per month).
Tops up the customer's open fee invoice where there is one, otherwise raises
a new one. Returns the fee invoice name, or None if nothing was billed.
"""
if not overdue_invoices:
return None
@@ -348,64 +606,53 @@ def _post_late_fee_invoice(customer, company, overdue_invoices, period):
)
fee_invoices = _get_fee_invoices(customer, company, fee_item)
last_billed = _last_billed_upto(fee_invoices)
open_invoice = _open_fee_invoice(fee_invoices)
# Idempotency: at most one fee invoice per (customer, company, month).
# Idempotency: at most one charge per (customer, company, month).
month_start = getdate(period + "-01")
for fi in fee_invoices:
if getdate(fi.posting_date) >= month_start:
return fi.name
if last_billed and last_billed >= month_start:
return open_invoice.name if open_invoice else None
# Interest on overdue balances, excluding prior fee invoices (no fee-on-fee).
prior_fee_names = {fi.name for fi in fee_invoices}
daily_interest = flt(settings.rate_of_interest) / 100.0 / 365.0
interest = sum(
flt(inv["outstanding_amount"]) * daily_interest * inv["days_overdue"]
for inv in overdue_invoices
if inv["name"] not in prior_fee_names
)
fee = round(interest + flt(settings.dunning_fee), 2)
if fee <= 0:
today = getdate(nowdate())
interest = _accrued_interest(overdue_invoices, settings.rate_of_interest, last_billed)
# The flat dunning fee is a one-off for falling into collections, charged
# when the fee invoice is raised — not again every time it is topped up.
amount = round(interest if open_invoice else interest + flt(settings.dunning_fee), 2)
if amount <= 0:
return None
cost_center = settings.cost_center or frappe.get_cached_value(
"Company", company, "cost_center"
)
charge = {
"item_code": fee_item,
"qty": 1,
"rate": amount,
"income_account": settings.income_account,
"cost_center": settings.cost_center
or frappe.get_cached_value("Company", company, "cost_center"),
"description": _("Late payment fee for statement period {0}").format(period),
}
si = frappe.new_doc("Sales Invoice")
si.naming_series = LATE_FEE_NAMING_SERIES
si.customer = customer
si.company = company
si.posting_date = nowdate()
si.due_date = nowdate()
si.append(
"items",
{
"item_code": fee_item,
"qty": 1,
"rate": fee,
"income_account": settings.income_account,
"cost_center": cost_center,
"description": _("Late payment fee for statement period {0}").format(period),
},
)
# Late fees are not taxed. A single zero "Actual" tax line keeps the taxes
# table non-empty, which stops ERPNext from auto-applying the company or
# item tax templates; being zero it posts nothing to the ledger.
si.taxes_and_charges = ""
si.append(
"taxes",
{
"charge_type": "Actual",
"account_head": settings.income_account,
"description": _("Late fees are not taxed"),
"tax_amount": 0,
"rate": 0,
},
)
si.insert(ignore_permissions=True)
si.submit()
if open_invoice:
blockers = _amend_blockers(open_invoice)
if not blockers:
name = _amend_fee_invoice(open_invoice, charge, today)
frappe.db.commit()
return name
_note_amend_skipped(customer, open_invoice.name, blockers)
name = _new_fee_invoice(customer, company, settings, charge, today)
frappe.db.commit()
return si.name
return name
def _note_amend_skipped(customer, fee_invoice, reasons):
"""Record why an open fee invoice was left alone and a new one raised."""
frappe.get_doc("Customer", customer).add_comment(
"Info",
_("Late fee {0} could not be amended ({1}); the charge was billed on a new invoice.").format(
fee_invoice, ", ".join(reasons)
),
)
def _late_fee_invoice_names(customer):
@@ -436,7 +683,7 @@ def _record_statement_activity(customer, data, fee_invoice_names, skip_late_fee)
if skip_late_fee:
fee_note = _("late fee skipped")
elif fee_invoice_names:
fee_note = _("late fee invoice {0}").format(", ".join(fee_invoice_names))
fee_note = _("late fee charged on {0}").format(", ".join(fee_invoice_names))
else:
fee_note = _("no late fee")
frappe.get_doc("Customer", customer).add_comment(
@@ -448,9 +695,10 @@ def _record_statement_activity(customer, data, fee_invoice_names, skip_late_fee)
def generate_statements(customers, skip_late_fee=0):
"""Render printable statements (one page per customer) for the selection.
Side effect (unless `skip_late_fee`): a late-payment fee is billed as a
Sales Invoice (once per customer per month) for each customer with overdue
invoices. Each generation is recorded on the customer's timeline.
Side effect (unless `skip_late_fee`): a late-payment fee is billed (once per
customer per month) for each customer with overdue invoices — added to their
open fee invoice if they have one, otherwise raised as a new Sales Invoice.
Each generation is recorded on the customer's timeline.
`customers` may arrive as a JSON-encoded list from the client.
"""