Allocate a credit note to an invoice

POSThttps://app.speybooks.com/api/v1/credit-notes/{id}/allocations

Allocates an issued credit note against an open invoice. The amount is an integer in PENCE: £100.00 is sent as 10000.

Allocatable only when the note is issued and the invoice is open (sent or partial). Allocating from a draft or voided note is rejected, with guidance to issue the note first; allocating against a terminal invoice is rejected; a missing note or invoice is reported as not found.

When the allocation drives the invoice outstanding to zero the invoice flips to credited (terminal); a partial allocation leaves it sent or partial. Over-allocation is rejected: the live allocations of the note can never exceed its total, nor an invoice its outstanding, enforced at the database (AX-CN-003), and concurrent allocations against one invoice are serialised so two cannot both pass.

In the response, amountAllocated is the amount applied by this request (pence), invoiceStatus is the invoice status after it, and invoiceOutstanding is the invoice's remaining balance after it, in pence, carried as a STRING so a balance beyond the safe-integer range is not rounded.

The response carries this allocation's own id (allocationId, cna_*); reverse it with POST /credit-notes/:id/allocations/:alloc_id/reverse, which marks the allocation reversed rather than deleting it, so the credit note can then be voided. Conservation sums only live, non-reversed allocations. Idempotent under an Idempotency-Key.

Path parameters

idstringrequired

Body parameters

amountintegerrequired
Amount to allocate, in pence
min: 1
invoiceIdstringrequired
The invoice to allocate against (e.g. inv_42)

Response

200Default Response
Show response fields
allocationIdstring
amountAllocatedinteger
creditNoteIdstring
invoiceIdstring
invoiceOutstandingstring
invoiceStatusstring

Error codes

400Default Response
404Credit note or invoice not found.