CreditNote/index • CreditNote/add • CreditNote/preview • CreditNote/settings Credit Notes, RMA Sales Returns & Customer Refunds Command Center & Studio
Master legally compliant revenue reversals (CN-), physical RMA goods return inspections (RMA-), warehouse stock restocking vs. quarantine, restocking fees, and the 3-way settlement router (Invoice Offset, Customer Credit Wallet, or Direct Cash/EFT Refund).
13.1 Plain-English Accounting: Why You Never Delete a Finalized Tax Invoice
A common question from beginners is: "If a customer returns a product or we overcharged them on an invoice, why can't we just delete or edit the original Tax Invoice?"
Under tax law (such as the SARS Value-Added Tax Act) and international audit standards, once a Tax Invoice (`INV-`) has been issued to a client, its sequential document number and VAT liability are locked into the audit trail. Deleting it would leave a gap in your invoice sequence and corrupt historical VAT201 periods. Instead, you issue an official Tax Credit Note (`CN-`)—which acts as a "negative invoice" that legally reverses all or part of the original sale.
When a Credit Note for R 1,150.00 (R 1,000.00 Excl. VAT + R 150.00 VAT) is marked Applied:
| GL Account | Debit (DR) | Credit (CR) |
|---|---|---|
| 4000 - Sales Returns / Revenue | R 1,000.00 | — |
| 2200 - Output VAT Control (SARS) | R 150.00 | — |
| 1100 - Accounts Receivable / Wallet / Bank | — | R 1,150.00 |
Plain English: Your taxable revenue decreases by R 1,000.00, you reclaim R 150.00 of Output VAT from SARS, and the customer's debt is reduced by R 1,150.00.
What happens to the physical item returned by the customer?
- Condition =
Good / Restock: The item is unopened and resellable. Keystone X increments your warehouse stock quantity (`+Qty`), restores your Inventory Asset account, and reverses Cost of Goods Sold (COGS). - Condition =
Damaged / QuarantineorDefective / Warranty: The item is broken and cannot be sold to another customer! Keystone X credits the customer financially without polluting your sellable warehouse stock count.
13.2 The 3-Way Financial Settlement Router & Physical Restock Engine
Every Credit Note in Keystone X lets you choose exactly how the credit value should be settled via the settlement_type router:
Offset Linked Tax Invoice (+ Excess to Wallet)
Automatically knocks the credit amount off the unpaid balance of the linked Tax Invoice (`INV-`). What if the customer already paid that invoice in full? Keystone X smartly routes any excess credit straight into the client's Credit Wallet so zero value is ever lost!
Credit Client Account Wallet (Future Invoices)
Deposits 100% of the net credit value directly into the customer's Credit Wallet (`customers.credit_balance`). Ideal for standalone SLA rebates, volume discounts, or returns on already-paid invoices where the client buys from you regularly.
Direct Cash / EFT Refund Disbursement
Used when a customer cancels an order after paying and wants money transferred back to their bank account. Records the exact Disbursing Bank Account, Refund Date, Refund Method (`EFT Refund`, `Card Reversal`, `Cash Refund`), and Bank Proof Reference.
13.3 Credit Notes & RMA Command Center (CreditNote/index) & Its 3 Modes
Navigate to Sales & Receivables → Credit Notes (`CreditNote/index`) to open the Credit Notes & RMA Returns Command Center.
📸 [SCREENSHOT PLACEHOLDER: credit-notes-command-center.png]
How to Capture: Open /CreditNote/index. Capture the 5 top KPI cards, the 3-Mode View Switcher (Ledger | Pipeline Board | RMA & Stock Hub), the filter ribbon, and the Credit Notes & RMA Ledger table.
The 5 Executive KPI Cards
- Total Credited Value: Cumulative rand value of all Credit Notes issued, plus a blue pill showing total Output VAT Reclaimed (`VAT: R X,XXX.XX`).
- Applied & Settled: Total rand value and count of credits directly offset against open Tax Invoices (`AR Offset`).
- Wallets & Refunds: Combined value routed to Customer Credit Wallets (`Wallet: R X,XXX.XX`) and disbursed as Cash/EFT Refunds (`Refunds: N`).
- Pending Pipeline: Value and count of Credit Notes sitting in `Draft`, `Pending Approval`, or `RMA / Goods Inspection` awaiting final sign-off.
- RMA & Stock Restock: Total physical units returned and restocked into your warehouse across all RMA authorizations (`RMA-`).
The 3 Workspace Modes on CreditNote/index
| Workspace Mode | Features, Columns & Operational Actions |
|---|---|
| Mode 1: Ledger ( ?view=list) |
Master register displaying:
|
| Mode 2: Pipeline Board ( ?view=board) |
Interactive drag-and-drop Kanban board organized by your approval and RMA inspection stages (`Draft` → `Pending Approval` → `RMA / Goods Inspection` → `Sent` → `Applied` → `Refunded`). Dragging a card into `Applied` automatically fires `CreditNote/updateStatusAjax` and triggers your configured financial settlement and stock restock rules! |
| Mode 3: RMA & Stock Hub ( ?view=rma) |
A specialized split-screen workspace for Warehouse Receiving & Returns Managers:
|
13.4 Issuing a Credit Note or RMA Authorization (CreditNote/add)
Clicking + Issue Credit Note / RMA opens the Smart Credit Note, RMA Return & Revenue Adjustment Builder Studio (`CreditNote/add`).
📸 [SCREENSHOT PLACEHOLDER: credit-note-rma-builder.png]
How to Capture: Open /CreditNote/add, select a Customer and a Linked Tax Invoice so the original billed line items auto-populate into Section 3 with checkboxes and Return Condition dropdowns, and capture both columns of the studio.
| Builder Section & Field | Field Name | Automated Behavior & Accounting Impact |
|---|---|---|
| 1. Standardized Reason Blueprint | reason_code |
Selecting a pre-built Reason Blueprint (e.g., Defective Warranty Return, Stock Return — Unopened, Pricing Overcharge Adjustment, or SLA Downtime Goodwill Credit) immediately auto-fills the Credit Note Classification (`credit_note_type`), Commercial Justification (`reason`), Settlement Routing (`settlement_type`), and Automatically Restock Returned Items (`restock_items`) switch! |
| RMA Authorization # | rma_number |
Auto-proposes the next sequential RMA tracking code (e.g., `RMA-01001`) so the customer can label their returned carton for your warehouse receiving bay. |
| 2. Customer & Linked Tax Invoice | customer_idinvoice_id |
Selecting a Customer fetches their saved addresses (`CreditNote/getAddressesJSON`) and all their Tax Invoices (`CreditNote/getInvoicesJSON`). Selecting a Linked Tax Invoice automatically pulls every original line item from that invoice (`CreditNote/getInvoiceItemsJSON`) into the credit grid below with original quantities, unit prices, discounts, and VAT codes! (Or leave on — Standalone Credit — for an unlinked rebate). |
| Linked Project & Job Card | project_idjobcard_id |
Optionally attributes the credit adjustment back to a specific Project Workspace or Field Service Job Card. |
| 3. Credit Line Items & Return Condition | items[i][selected]items[i][return_condition]items[i][credit_qty] |
For each line loaded from the invoice (or added via + Add Catalog Item / + Add Custom Credit Line):
|
| Less: Restocking / Admin Fee | restocking_fee |
Optional handling/restocking deduction subtracted from the gross credit (`Net Total Credit = Subtotal + VAT − Restocking Fee`), commonly used when customers return unwanted special-order goods. |
| 4. Audit Notes & RMA Inspection Evidence | notes, terms, attachments[] |
Upload photos of damaged packaging, signed warehouse inspection slips, or supplier RMA authorizations directly to the Credit Note. |
13.5 The Executive Credit Note & RMA Cockpit (CreditNote/preview/{id})
Clicking any Credit Note number opens its 360° Cockpit (`CreditNote/preview/{id}`).
- Interactive Lifecycle Stage Stepper: Click any stage button across the top bar to move the Credit Note through `Draft` → `Pending Approval` → `RMA / Goods Inspection` → `Applied`.
- Apply & Settle Credit Modal (
#applyCreditModal): Appears on unsettled Credit Notes. Lets you choose between offsetting a target Tax Invoice (with automatic excess spillover to the client's Credit Wallet) or crediting 100% to the Client Account Wallet (`CreditNote/apply/{id}`). - Record Refund Modal (
#refundCreditModal): Records an outbound EFT, Card Reversal, or Cash refund disbursement from a selected company bank account (`CreditNote/refund/{id}`). - Restock Warehouse Button: Appears whenever `restock_items = 1` and the goods haven't been synced to inventory yet. Clicking it (`CreditNote/restock/{id}`) increments warehouse stock for all `Good / Restock` lines and stamps the exact `restocked_at` timestamp on the audit trail.
13.6 Credit Note & RMA Customization Studio (CreditNote/settings)
Administrators can click Customize (`CreditNote/settings`) to configure all Credit Note and RMA governance across 4 Studio Tabs:
- 1. Numbering & Automation (`#tab-general`): Configure the Credit Note Prefix (`CN-`), RMA Authorization Prefix (`RMA-`), Default Initial Stage, Default Settlement Routing, Approval Threshold Amount (e.g., any Credit Note above R 10,000 automatically routes to `Pending Approval` for manager sign-off), Default Restocking Fee %, and 3 automation switches (Auto-Restock Warehouse Items, Auto-Offset Linked Invoice, and Auto-Email Customer on Apply).
- 2. Lifecycle Pipeline Stages (`#tab-stages`): Add, color-code, or reorder custom workflow stages (`#stageModal`) and see which stages trigger financial settlement.
- 3. Return & Credit Reason Blueprints (`#tab-reasons`): Create standardized return reason templates (`#reasonModal`) with pre-bound classification, default settlement routing, `Auto-Restock` rules, and `Requires RMA#` enforcement.
- 4. Official PDF & Terms (`#tab-pdf`): Customize the Default Credit Note Terms & Conditions and toggle 3 PDF layout blocks: Display RMA Return Condition Column, Display Financial Settlement Summary Box, and Display Authorized Signatory & Customer Return Acknowledgment Block.