Table of Contents

#97 — A full refund never reverses the invoice's own PAID / Status fields (Resolved)

← Back to Manara Bugs · View issue #97 in MantisBT


Reported by: Khaled Tarabay on 2026-07-27T14:34:31+01:00
Assigned to: Claude
Resolved by: Claude on 2026-07-27T15:50:34+01:00
Severity: major
Priority: high
Reproducibility: always
Category: General

Description: Refunds & Credits is a one-way ledger recording a refund never writes back to the invoice it refunds. A $70.00 invoice paid in full, then a full $70.00 refund recorded against it — the invoice still showed PAID $70.00, Status Paid, unchanged. There is also no “Refunded” state anywhere in the invoice status list. Confirmed still true on regression retest, verified via full-page text search rather than a short slice Status remained “Paid.” A “Refunded” status (and ideally “Partially Refunded”) needs to be added to the invoice status list, and recording a refund must update the invoice accordingly: a full refund should set Status = Refunded with Balance Due recalculated to reflect the refund, and a partial refund should set Status = Partially Refunded (or an equivalent flag) with an updated net-paid figure. Any downstream view that reads “PAID” or “Status” dashboards, reports, Reconciliation must reflect the refund, not just the raw payment history.

Steps to Reproduce: Create, issue, and fully pay any invoice (e.g. $70.00). Record a Refund for the full $70.00 against that invoice. Reload the invoice PAID, Balance Due, and Status are all unchanged this is the bug; Status should now reflect the refund.

Resolution: FIXED (migration 064 — two new invoice_statuses rows: 'refunded', 'partially_refunded'). Prod must run /run-migrations.php for 064.

Where: database/migrations/064_invoice_refund_statuses.sql, app/classes/Billing/Invoice.php (new applyRefundStatus()), app/controllers/CreditNoteController.php (store() now wraps in a transaction and calls it for kind=refund), app/controllers/BillingController.php (validate() extends the existing paid/partially_paid “system-owned, can't hand-set” guard to the two new statuses), app/views/billing/show.php (pill styling).

What: recording a refund now sets the invoice's own Status — full refund (refunded total >= amount paid) → “Refunded”; a partial refund → “Partially Refunded”. total_amount / amount_paid / balance_due are deliberately left untouched (they're trigger-derived strictly from invoice_items + payments — a refund is a separate ledger, not a payment reversal, so those columns correctly keep showing the real historical Paid figure), but the STATUS is not trigger-owned, so it's safe — and now correct — to set it directly. The new statuses are guarded the same way paid/partially_paid already are: not hand-pickable on the invoice edit form (rejected server-side if someone tries).

Verified live against the local database, reproducing the ticket's own steps: created a $70 invoice, issued it, paid it in full (status → Paid) — recorded a full $70 refund against it — reloaded the invoice: Status is now “Refunded” (pill correctly recolored), Paid still correctly shows $70.00 (the real historical figure) with a “fully refunded” banner explaining the discrepancy. Also tested a PARTIAL refund on a separate $100 invoice (refunded $30 of $100 paid) — Status correctly became “Partially Refunded”. Confirmed a direct attempt to hand-set an invoice's status to “Refunded” via the edit form is rejected (“Paid / partially-paid / refunded statuses are set automatically…”). Full test suite: 29/29 passing (859 assertions, unchanged — no new routes). Test invoices/refunds removed afterward.

Activity / Notes

Where: database/migrations/064_invoice_refund_statuses.sql, app/classes/Billing/Invoice.php (new applyRefundStatus()), app/controllers/CreditNoteController.php (store() now wraps in a transaction and calls it for kind=refund), app/controllers/BillingController.php (validate() extends the existing paid/partially_paid “system-owned, can't hand-set” guard to the two new statuses), app/views/billing/show.php (pill styling).

What: recording a refund now sets the invoice's own Status — full refund (refunded total >= amount paid) → “Refunded”; a partial refund → “Partially Refunded”. total_amount / amount_paid / balance_due are deliberately left untouched (they're trigger-derived strictly from invoice_items + payments — a refund is a separate ledger, not a payment reversal, so those columns correctly keep showing the real historical Paid figure), but the STATUS is not trigger-owned, so it's safe — and now correct — to set it directly. The new statuses are guarded the same way paid/partially_paid already are: not hand-pickable on the invoice edit form (rejected server-side if someone tries).

Verified live against the local database, reproducing the ticket's own steps: created a $70 invoice, issued it, paid it in full (status → Paid) — recorded a full $70 refund against it — reloaded the invoice: Status is now “Refunded” (pill correctly recolored), Paid still correctly shows $70.00 (the real historical figure) with a “fully refunded” banner explaining the discrepancy. Also tested a PARTIAL refund on a separate $100 invoice (refunded $30 of $100 paid) — Status correctly became “Partially Refunded”. Confirmed a direct attempt to hand-set an invoice's status to “Refunded” via the edit form is rejected (“Paid / partially-paid / refunded statuses are set automatically…”). Full test suite: 29/29 passing (859 assertions, unchanged — no new routes). Test invoices/refunds removed afterward.

Full History

Date User Field Change
2026-07-27T14:34:31+01:00 Khaled Tarabay issue-new New Issue
2026-07-27T15:50:27+01:00 Claude Assigned To ⇒ Claudine
2026-07-27T15:50:30+01:00 Claude tag-added Tag Attached: done-by-claude
2026-07-27T15:50:32+01:00 Claude note-added Note Added: 0000056
2026-07-27T15:50:34+01:00 Claude Status new ⇒ resolved

Synced automatically from MantisBT issue #97.