Credit Notes

A credit note reduces what a customer owes (or, against a paid invoice, creates an open credit or disburses a refund). Unlike an invoice void, a credit note is a real document with its own number, date, reason, and VAT treatment — the customer receives it and your books reflect both the original sale and the correction as distinct events.

Once posted, credit notes are terminal: no edits, no voids. If a posted credit note turns out to have been wrong, the correction is a debit note with reason credit_note_correction, which re-raises the amount on the ledger. This keeps NRS e-invoice filings clean (one invoice → at most one credit note; corrections flow the opposite direction).

Lifecycle

  draft → [post] → posted → [apply allocations] → applied
    │                  │
    │                  └── can receive allocations (cross-invoice)
    │
    └── [delete] → gone         (drafts only; no GL impact)

Drafts are freely editable. Posted credit notes create a revenue + VAT reversal journal entry in the same batch as the COA balance update. When the originating invoice has an NRS IRN, the CN is auto-transmitted to NRS as invoice type 380 post-commit (fire-and-forget; NRS failures are surfaced via cn.nrs.status='rejected' without unwinding the ledger).

List credit notes

Query parameters

Get a single credit note

Response includes the full document (line items, totals, GL state, NRS transmission status) and an allocations array showing every invoice or bill this credit has been applied to.

Create a credit note

Body — customer-side (sales)

Body — supplier-side (purchases)

Same schema but replace customer* with supplier*. Referenced documents are invoices on the sales side, bills on the purchase side. Supplier-side credit notes are uncommon — most purchase corrections go through debit notes.

Response — 201

{
  "success": true,
  "data": {
    "id": "cn_abc",
    "number": "CN-2026-00001",
    "status": "draft",
    "direction": "customer",
    "totalKobo": 107500,
    "total": 1075,
    "createdAt": "2026-04-23T10:45:34.419Z"
  }
}

Update a draft

Accepts the same body fields as create (partial updates allowed). Returns the full sanitised credit note.

Post a draft

Empty body. Response 200 with status: 'posted' and a note string pointing at isPostedToGL + glEntryId as the async-settle signals.

The GL trigger creates one balanced journal entry with the reversal lines. For a customer-side CN on an unpaid invoice:

DR  4010 Service Revenue     = CN subtotal − discount
DR  2021 VAT Provision       = CN VAT
    CR  1021 Trade Debtors        = CN total

VAT splits proportionally between 2021 Provision and 2026 Payable based on how much of the referenced invoice has already been paid. Bad-debt CNs (reason='bad_debt') debit 6090 Bad Debt Expense instead of 4010 Revenue.

Apply to one or more invoices

Body

The sum of active allocations is capped at the credit note's totalKobo. When fully consumed, the CN status advances from posted to applied.

Response — 200

{
  "success": true,
  "data": {
    "id": "cn_abc",
    "allocationIds": ["alloc_1", "alloc_2"],
    "remainingKobo": 0,
    "remaining": 0
  }
}

Unapply an allocation

The allocation doc is preserved (not deleted) with isReversed: true so customer statements retain the full narrative.

Delete a draft

Errors

Related endpoints

• Debit Notes — purchase-side corrections and the credit_note_correction path
• Invoices — the originating document
• Receipts — cash settling
• Journal Entries — see the reversal JE created when a CN posts