Credit Notes

Credit notes reduce what a contact owes. A credit note is a SEPARATE document, not a negative invoice (ADR-013): its own lines are stored non-negative and the document's effect is subtractive. The separate-document shape is what HMRC requires of a valid credit note (VATREC13040, VAT Regs 1995 reg 15C): its own sequential number in a series distinct from the invoice series, a reference to the original invoice, the reason for the decrease, and the rate and sterling amount of VAT credited.

Lifecycle

The stored status vocabulary is draft, issued, and voided. A draft is editable; issuing posts the document's own double-entry journal (the exact negation of an invoice issue: for a sales note, revenue and VAT on Sales are debited and Trade Debtors credited, in the note's own period, the reg 38 tax point) and moves the VAT return; voided is the terminal error-correction state, the mirror of an invoice void.

allocated is NOT a status. Allocation is an ACT, not a state: an issued note carrying live allocations is the derived allocated condition, still issued underneath. Voiding requires the live allocations to be zero first (ADR-013 addendum), the faithful mirror of the invoice void requiring amount_paid = 0, so de-allocation is a separate prior act and not a cascade folded into void.

Allocation and the credited flip

An issued credit note is applied to an open invoice by allocation. When an allocation drives the invoice outstanding (total - amount_paid - live allocations) to exactly zero, the invoice flips to credited, the terminal status reserved for this purpose on the invoice side. A partial allocation leaves the invoice open (sent or partial) so it can take further allocation or payment.

Allocation is conserved at the database (AX-CN-003): the live (non-reversed) allocations of a note may never exceed its own total, and the live allocations against an invoice may never exceed that invoice's outstanding. Concurrent allocations against one invoice are serialised by a fixed lock order (the note then the invoice), so two cannot both pass and over-apply. The conservation guard is the authority; the route precondition is its courtesy. A de-allocation marks an allocation reversed rather than deleting it, so the live set excludes it and the note can then be voided.

Amounts

The allocation amount is an integer in PENCE: £50.00 is sent as 5000, the same wire convention as an invoice payment. The invoice outstanding returned after an allocation is also in pence, carried as a STRING so a balance beyond the JavaScript safe-integer range is preserved exactly (the service computes it in BigInt).

Numbering

Credit-note numbers follow the pattern CN-{sequence} (e.g. CN-0001), assigned automatically on creation and sequential per organisation, in a series distinct from invoices.

The read endpoints (a single credit note and the paginated list) are documented below. The single-note object carries the header totals in integer pence, the lines (quantity as a full-scale decimal string, unitPrice in integer micro-pounds and vatRate in integer basis points per ADR-002 section 5, net, vat and gross in integer pence from the stored conserved columns), the settlement block (the live allocated and remaining totals and the allocation entries, live and reversed, each flagged isLive), and the invoices the note credits. availableTransitions is not yet served: it joins additively with a later increment. The lifecycle is now served end to end: create, issue, allocate, de-allocate and void.