Reverse a credit-note allocation

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

Reverses one live allocation of a credit note (de-allocation), the inverse of allocation. Name the allocation by its own id (cna_*), returned as allocationId when it was created.

The allocation is marked reversed, not deleted, under an all-or-nothing completeness rule that records who reversed it and why; the reason is required and cannot be blank. A live allocation drops out of conservation the moment it is reversed, which is what lets the credit note then be voided.

When the invoice was credited, reversing un-flips it to its payment-derived status: partial if a payment remains on the invoice, otherwise sent. The number of credit allocations still live does not change that label; it changes only the outstanding balance. When the invoice was not credited (the allocation was a partial one that never closed it), the status is left as it is and only the outstanding moves.

De-allocation is user-actor only: an API key cannot reverse and is refused 403. A missing or wrong-note allocation is 404, an allocation already reversed is 409, and a blank reason is 400.

In the response, invoiceStatus is the status after the reversal and invoiceOutstanding is the invoice's remaining balance after it, in pence, carried as a STRING.

Two idempotencies apply: the request layer under an Idempotency-Key, and the domain layer where a second reverse of the same allocation returns 409. The credited -> sent | partial edges this relies on were made legal by migration 116 (AX-INV-001).

Path parameters

alloc_idstringrequired
The allocation to reverse (e.g. cna_12)
idstringrequired
The credit note (e.g. cn_5)

Body parameters

reasonstringrequired
Why the allocation is being reversed; recorded on the reversal
min length: 1

Response

200Default Response
Show response fields
allocationIdstring
creditNoteIdstring
invoiceIdstring
invoiceOutstandingstring
invoiceStatusstring

Error codes

400Default Response
403The caller is an API key; de-allocation requires a user.
404Credit note or allocation not found.
409The allocation is already reversed.