Create a credit note

POSThttps://app.speybooks.com/api/v1/credit-notes/

Creates a credit note. With status: "draft" (the default) the note and its lines are recorded and nothing posts to the ledger. With status: "issued" the note is created and issued in one act: the issue journal posts in the same transaction, moving the VAT return, and every line must carry an account (an unmapped line is refused 400 before the document number is drawn, so a failed create-as-issued consumes no number).

Line quantity and unitPrice are exact decimal strings (quantity strictly positive, unitPrice zero-legal); vatRate is an integer percentage. Per-line net and VAT are computed server-side with HMRC per-line rounding. contactId and line accountId are prefixed ids. reason records the HMRC decrease reason.

Creating is user-actor only: an API key is refused 403. The response carries the new id, the allocated document number, and the resulting status.

status "issued" is the second issue entry point: it posts the issue journal inline (AX-CN-001), so a create-as-issued and a draft-then-issue reach the same posted state. Idempotent under an Idempotency-Key (AX-CON-002). The credit note is a separate document from the invoice it corrects (ADR-013).

Body parameters

contactIdstringrequired
The contact the note credits (e.g. cont_42)
creditNoteTypestringrequired
salespurchase
issueDatestringrequired
date
linesarray<object>required
min items: 1
Show child parameters
descriptionstringrequired
quantitystringrequired
pattern: ^(?!0+(\.0+)?$)\d+(\.\d+)?$
unitPricestringrequired
pattern: ^\d+(\.\d+)?$
vatRateintegerrequired
min: 0 · max: 100
accountIdstringoptional
The revenue/expense account for the line (e.g. acc_4000)
notesstringoptional
max length: 2000
reasonstringoptional
The HMRC decrease reason (VATREC13040); captured in metadata
max length: 2000
statusstringoptionalDefault: draft
draftissued
termsstringoptional
max length: 2000

Response

201Default Response
Show response fields
creditNoteIdstring
creditNoteNumberstring
statusstring

Error codes

400Default Response
403The caller is an API key; creating requires a user.