Balance endpoints — correction, waiver, header sync, retention
How correction, undoing a correction, waiver, header recalculation and retention release work, with their tables and permission keys.
The balance endpoints change an invoice's open balance from the items or with a separate log row. Header totals are always calculated from the items, and the outstanding balance moves by the difference.
Endpoints
| Endpoint | Behaviour | Right |
|---|---|---|
correction | With an empty amount closes the whole open balance in both currencies, with an amount it applies it signed; with several documents each goes to zero. addCorrection() writes a correction row and an item row, then the header is recalculated. Only documents with a header, not settled (state !== 'settled') and in scope. | core modify + correction; several items bulkcorrection |
correctiondelete | deleteCorrection(correction_id): deletes the row and its item, recalculates the header. | core modify + correctiondelete |
waive | Only interest and recovery fee documents (getWaivableDoc). The amount is the one entered (if at most open + 0.5) or the whole open balance; with several documents always the whole. A future date becomes today. settlement::addWaiver() + applyWaiverToBalance(); the response gives done/skipped counts. | core modify + waive; several items canBulk(waive) |
headersync | Per invoice syncHeaderFromItemsReport() (Dlbtinvoice::syncHeaderFromItems); the response counts changed and skipped invoices. | core modify + headersync; several items bulkheadersync |
retention, retentionsave, retentionsearch | Shows the recorded retentions (getRetentions), releases them row by row (releaseRetention, per error error_retention_*), searches your own outgoing invoices to the same partner for offset (searchSettleInvoices). Recording happens when the invoice is saved (saveRetentions). | retention + retentionInScope |
Error keys
error_correction_select, error_correction_amount, error_correction_not_ready, error_correction_doc, error_waive_select, error_waive_doc, error_waive_not_ready (missing migration).
Data model
Table names carry the installation's own prefix in the database.
| Table | Role |
|---|---|
invoice_correction | correction log |
settlement_waiver | waiver log (through the finance/settlement model) |
invoice_retention | retention rows |
invoice, invoice_item | header and items, balance |
Known limitations
The bulkwaive key is not in the seeds, so the plain waive right decides for several items too. The keys correction, correctiondelete, headersync, retention and waive exist only in the legacy permission table and are not classified in the feature master.