> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitaji360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Debit Notes (Purchase Returns)

> A debit note records a return to a vendor — you're sending goods back (or claiming a credit) and reducing what you owe them.

A **debit note** records a return *to a vendor* — you're sending goods back (or claiming a credit) and reducing what you owe them. It's the purchase-side mirror of a credit note. A debit note is always created **from an existing bill**: it clones the bill's lines with negated quantities, so the amounts are the reverse of the original purchase.

You'll find debit note detail pages at: `/accounting/debit-notes/:id`

Debit notes are listed alongside credit notes on the **Credit/Debit Notes** page (`/accounting/credit-notes`), and you create one from the source bill itself. There is no separate "new debit note" menu item — you start from a bill.

> 📷 *Screenshot: A debit note detail page showing the source bill link, negated lines, residue and allocations — to be added.*

***

## When to use a debit note

* You returned damaged or incorrect goods to a supplier.
* A supplier granted you a discount or price correction after you'd already booked the bill.
* You need to formally reduce an outstanding payable and either apply the credit to other bills or collect a cash refund.

Because a debit note offsets a real purchase, you can only raise one against a bill that has actually been posted (see source requirements below).

***

## The debit note lifecycle

A debit note follows the same workflow states as a bill, but the meaning is reversed (its total is **negative**, and "paying it down" means consuming the credit):

1. **Create draft** — clone the source bill into a Draft debit note.
2. **Issue** — post the return to the ledger and move it to **Approved**. The credit (residue) now exists.
3. **Allocate** — apply the credit against one or more open bills for the same vendor.
4. **Refund residue** — collect any leftover credit as cash back from the vendor.
5. **Unapply** — reverse a single allocation if you made a mistake.

| Status            | Meaning for a debit note                                         |
| ----------------- | ---------------------------------------------------------------- |
| **Draft**         | Created, not yet posted.                                         |
| **Approved**      | Issued and posted; full credit available to allocate or refund.  |
| **PartiallyPaid** | Part of the credit has been applied/refunded; a residue remains. |
| **Paid**          | The whole credit has been consumed (allocated and/or refunded).  |

***

## Step 1 — Create the debit note from a bill

A debit note can only be cloned from a **regular bill** (not from another debit note) that is **not deleted** and is in one of these states: **Approved**, **PartiallyPaid**, **Paid** or **Overdue**.

1. Open the source bill (`/accounting/bills/:id`).
2. Choose **Create debit note** from the bill's quick actions. (Available once the bill is submitted/posted and you have `accounting-bills:create`.)
3. Select a **reason** (required):
   * **Return** — goods returned
   * **Discount** — price reduction granted
   * **Correction** — fixing an error
   * **Damaged goods**
   * **Other**
4. Choose the scope:
   * **Full return** (default) — every source line is returned in full.
   * **Partial return** — specify, per line, the **quantity** you're returning. You can only return up to what was originally billed, minus anything already returned on earlier debit notes.
5. Save. A Draft debit note is created with a generated number in the form `DN-YYYY-MM-######` (e.g. `DN-2026-04-000001`).

What carries across from the source bill: vendor, expense/inventory accounts, tax rate and tax codes, cost center, stock item/warehouse/UOM, and the return reason (appended to the notes). Quantities and amounts are **negated**.

### Validations applied at creation

The system enforces several rules so a return can never exceed or predate the original purchase:

* **Quantity cap** — you cannot return more than was billed (counting prior partial returns). A "fully returned" bill is greyed out in the picker.
* **Rate** — the original unit price is always carried forward; you can't invent a different return price.
* **Vendor** — the source vendor must still exist and not be deleted.
* **Date** — the debit note's date cannot be earlier than the source bill's date.
* **Same book** — the debit note stays in the same accounting book (and therefore the same Accounts Payable control account) as the source bill.

The picker that lists eligible source bills is also exposed at `GET /accounting/bills/returnable`, which flags each bill with `fullyReturned` so the UI can disable bills with nothing left to return.

***

## Step 2 — Issue the debit note

From a Draft debit note, choose **Issue** (requires `accounting-bills:post`). This posts the return to the general ledger and moves the note to **Approved**. The note must be a debit note and in **Draft** to be issued.

**Behind the scenes** — issuing posts a balanced entry for the absolute value of the return:

* **Debit Accounts Payable** for the return total (reducing what you owe the vendor), tagged against the debit note itself so it carries its own AP residue.
* **Credit each source line's expense / inventory account** — putting the cost back, mirroring what the original bill debited.

***

## Step 3 — Allocate the credit to open bills

Once Approved, apply the debit note's credit against other open bills for the **same vendor**. Choose **Allocate** (requires `accounting-bills:update`) and enter one or more target bills with the amount to apply to each.

Rules enforced:

* The total you allocate can't exceed the debit note's remaining **residue**.
* Each target must be a **regular bill** belonging to the **same vendor**, in **Approved / PartiallyPaid / Overdue** state.
* You can't allocate more to a target than that bill's outstanding balance.

Allocation uses **replace-all** semantics: each time you allocate, you submit the complete set of allocations you want, and the system recomputes from scratch (reversing any prior allocations first). After allocating, the debit note becomes **PartiallyPaid** (residue remains) or **Paid** (fully consumed), and each target bill's balance is reduced accordingly.

**Behind the scenes** — allocation posts a single netting entry:

* **Credit Accounts Payable** (against the debit note) for the amount applied, reducing the note's residue.
* **Debit Accounts Payable** (against each target bill) for the amount applied, reducing that bill's outstanding balance.

***

## Step 4 — Refund the residue (vendor pays you back)

If you'd rather take leftover credit as cash than apply it to other bills, choose **Refund residue** (requires `accounting-bills:update`). The debit note must be **Approved** or **PartiallyPaid** with a residue remaining.

Enter:

* **Bank/cash account** receiving the refund (required).
* **Payment method** (e.g. BANK, CASH, MOBILE\_MONEY).
* **Reference number** *(optional)* — cheque #, mobile-money code, etc.
* **Received date** *(optional, defaults to now)*.

**Behind the scenes** — the refund posts:

* **Debit your bank/cash account** for the residue (money coming in).
* **Credit Accounts Payable** (against the debit note) for the residue, clearing it.

The debit note moves to **Paid**.

***

## Unapplying an allocation

Made a mistake? Choose to **unapply** a single allocation row (requires `accounting-bills:void`). The system removes that allocation, restores the target bill's outstanding balance, posts an offsetting reversal entry, and recomputes the debit note's status. If it was the last allocation, the note returns to **Approved** with its full residue available again.

***

## Voiding a debit note

A debit note can be voided through the standard bill **Void** action, but only if it's "clean":

* It **cannot** be voided while any active **allocations** point at it — unapply each one first.
* It **cannot** be voided if a **vendor refund payment** has cleared its residue — reverse that payment first.

This protects the integrity of any bills the credit has already touched.

***

## Multi-business note

Like bills, debit notes live inside a single **accounting book** and never cross businesses. A debit note must share the source bill's book, so it always uses the same Accounts Payable control account. Switch to the correct business before raising a return.

***

## Permissions reference

Debit note actions reuse the `accounting-bills` permission module:

| Action                            | Permission slug           |
| --------------------------------- | ------------------------- |
| Create a debit note (from a bill) | `accounting-bills:create` |
| Issue (post)                      | `accounting-bills:post`   |
| Allocate / refund residue         | `accounting-bills:update` |
| Unapply an allocation / void      | `accounting-bills:void`   |
| View                              | `accounting-bills:read`   |

***

## Related

* [Purchase Bills (Accounts Payable)](/accounting/user/transactions/purchase-bills) — the source documents debit notes are raised against
* [Expenses & Expense Claims](/accounting/user/transactions/expenses)
* [Petty Cash](/accounting/user/transactions/petty-cash)