A debit note is the mirror of a credit note: where a CN reduces what a party owes, a DN increases it — or, on the purchase side, reduces what we owe a supplier (returned goods, disputed charges, damaged shipments).

When to use a debit note

Scenario	Direction	Reason
Supplier shipped damaged goods we're returning	`supplier`	`goods_returned`
Disputing a line on a supplier's bill	`supplier`	`price_dispute`
Supplier under-delivered vs. the PO	`supplier`	`under_delivery`
We caught that we under-billed a customer	`customer`	`under_billed`
Late-payment fee assessment	`customer`	`late_payment_fee`
Correcting a posted credit note that shouldn't have been issued	either	`credit_note_correction`

Lifecycle

  draft → [post] → posted → [void (with reason)] → voided
    │
    └── [delete] → gone   (drafts only; no GL impact)

Unlike credit notes, debit notes can be voided — they're not terminal. The void creates a reversing JE that mirrors the DN's original entry with swapped debits and credits.

List debit notes

GET/v1/debit-notes

Returns debit notes for a business, newest first.

Query parameters

Field	Type	Required	Notes
`businessId`	string	yes
`limit`	integer	no	Default 50, max 100.
`status`	string	no	`draft`, `posted`, `voided`.
`direction`	string	no	`customer` or `supplier`.
`customerId`	string	no
`supplierId`	string	no

Get a single debit note

GET/v1/debit-notes/{id}

Fetches one debit note.

Create a debit note

POST/v1/debit-notes

Creates a draft (or posts with post=true).

Body — supplier-side (the common case)

Field	Type	Required	Notes
`direction`	string	yes	`supplier`
`supplierId`	string	yes
`supplierName`	string	yes
`supplierEmail`	string	no
`referencedBillIds`	string[]	no	Bills this DN claims against.
`reason`	string	yes	`goods_returned`, `price_dispute`, `damaged_shipment`, `under_delivery`, `credit_note_correction`, `other`.
`reasonNote`	string	required for `other`
`debitNoteDate`	ISO 8601	no	Defaults to today.
`lineItems`	array	yes	Each needs `description`, `quantity`, `unitPrice` / `unitPriceKobo`, and `category` — the expense COA code (`"5010"`) or keyword (`"office-supplies"`). The reversal credits this account.
`vatRate`	number	no	Default 7.5.
`whtRate`	number	no	Non-zero WHT reverses proportionally between 2022 Provision and 2027 Payable based on the referenced bill's payment state.
`notes`	string	no
`post`	boolean	no

Body — customer-side

Same schema with customer* fields instead of supplier*. Use referencedInvoiceIds for the invoice this DN supplements. Line items don't require category (revenue routes to 4010 by default).

Body — CN correction (either direction)

When reason='credit_note_correction', referencedCreditNoteIds is required. The server loads the referenced CN's journal entry and creates a mirror-swap reversal, undoing exactly what the CN did regardless of which accounts it touched.

Response — 201

{
  "success": true,
  "data": {
    "id": "dn_abc",
    "number": "DN-2026-00001",
    "status": "draft",
    "direction": "supplier",
    "totalKobo": 102500,
    "total": 1025,
    "createdAt": "2026-04-23T10:46:16.359Z"
  }
}

Note the total math: DN total = subtotal + VAT − WHT (matches bill convention — net payable reduction on the supplier side).

Update a draft

PUT/v1/debit-notes/{id}

Edits a draft. Posted debit notes reject edits — void them and reissue instead.

Post a draft

POST/v1/debit-notes/{id}/post

Flips status draft → posted; GL posting runs asynchronously.

For a supplier-side DN against an unpaid bill, the GL trigger posts:

DR  2010 Trade Creditors     = subtotal + VAT − WHT     (reduce AP)
DR  2022 WHT Provision       = WHT                       (reverse the provision)
    CR  5xxx/6xxx Expense          = subtotal                  (credit by category)
    CR  1040 Input VAT             = VAT                      (reverse the input VAT)

WHT splits between 2022 Provision and 2027 Payable when the bill has been partially paid, capped at whtTransferredKobo so a DN can never un-remit more than was actually remitted to FIRS.

Void a posted debit note

POST/v1/debit-notes/{id}/void

Cancels a posted debit note and creates a reversing journal entry.

Body

Field	Type	Required	Notes
`reason`	string	yes	Min 1 char; shown in the audit trail.

Delete a draft

DELETE/v1/debit-notes/{id}

Deletes a draft. Posted DNs are voided instead.

Errors

Code	When
`VALIDATION_ERROR`	Missing fields; supplier-side line without `category`; `credit_note_correction` without `referencedCreditNoteIds`; `reason='other'` without `reasonNote`.
`BAD_REQUEST`	Void on a draft / already-voided DN; update on a non-draft.
`NOT_FOUND`	Debit note id doesn't exist.
`FORBIDDEN`	API key's user doesn't own `businessId`.

Related endpoints

Credit Notes — the sales-side mirror and the chain's starting point
Bills & Payments — the originating document for supplier-side DNs
Journal Entries — inspect the reversal JE

Debit Notes