Credit Notes

A credit note is a formal financial document that reduces the amount a client owes. In NexusRMS, credit notes are linked to an original invoice and can be applied to reduce the balance on that invoice or on a different invoice for the same client. Every credit note maintains a full audit trail with status tracking, client acknowledgement, and voiding capabilities.

When to use credit notes

NexusRMS provides eight predefined reasons via the REASONS constant:

• return — Equipment Return: the client returned equipment early or unused items were sent back
• damaged — Damaged Equipment: equipment was damaged before or during delivery
• overpayment — Overpayment Refund: the client paid more than the invoice total
• discount — Additional Discount: a post-invoice discount agreed with the client
• error — Billing Error: the invoice contained incorrect quantities, prices, or items
• cancellation — Project Cancellation: the project was cancelled after invoicing
• goodwill — Goodwill Gesture: a voluntary credit to maintain the client relationship
• other — Other: any reason not covered by the above categories

Creating a credit note

Navigate to Financial > Credit Notes and click Create Credit Note, or open an invoice and select Create Credit Note from the actions menu to pre-link it. The form fields are:

• Invoice (required) — The original invoice being credited. The client is inherited automatically.
• Reason (required) — One of the eight predefined reasons listed above
• Currency — Automatically set to match the linked invoice's currency
• Notes — Client-visible notes explaining the credit
• Internal Notes — Staff-only notes for internal context
• Template — PDF template for the credit note document via the template_id field

The credit_note_number is auto-generated in the format CN-YYYY-#### (e.g., CN-2026-0001), incrementing from the last credit note created in the current year.

Credit note line items

Each credit note contains one or more CreditNoteItem records detailing what is being credited:

• invoice_item_id — Links to the specific InvoiceItem being credited for traceability
• item_type — The type of item (equipment, labour, delivery, service, custom)
• item_id — Reference to the equipment or other item being credited
• description — Description of the credited item
• quantity — Number of units being credited
• unit_price — Price per unit for the credit
• subtotal — Auto-calculated as quantity × unit_price on save
• total — Equal to the subtotal (credit notes do not apply per-line discounts)
• notes and sort_order — Additional notes and display order

When a line item is saved, the parent credit note's totals are automatically recalculated via calculateTotal(), updating subtotal, tax_amount, total, and amount_remaining.

Credit note summary

• Subtotal — Sum of all line item totals
• Tax Rate / Tax Amount — Tax percentage and calculated tax on the subtotal
• Total — Full credit amount: subtotal + tax
• Amount Applied — How much credit has been applied to invoices
• Amount Remaining — Unused credit balance: total − amount_applied

Credit note statuses

1. draft — Credit note is being prepared. Line items can be added, edited, or removed.
2. issued — Formally issued via issue(), which sets the issue_date. If the linked invoice has an outstanding balance, the credit is automatically applied.
3. applied — The full credit amount has been applied to invoices (amount_remaining reaches zero).
4. voided — Cancelled via void(reason, voidedBy), recording voided_at, void_reason, and voided_by.

Applying credit to invoices

The applyToInvoice(invoiceId, ?amount) method determines the apply amount as the smallest of: the specified amount (or full remaining balance), the credit note's amount_remaining, and the target invoice's amount_due. It then creates a Payment record on the target invoice with payment_method set to credit_note, status completed, and the credit note number as the reference. The credit note's amount_applied and amount_remaining are updated, and the status changes to applied once the remaining balance reaches zero.

On the detail page, click Apply to Invoice to open the dialog. Select the target invoice via autocomplete (showing all unpaid invoices for this client) and enter the amount. Credit notes are not limited to the original invoice — you can apply credit to any unpaid invoice for the same client.

Checking credit status

• isFullyApplied() — Returns true when amount_remaining is zero or less
• hasRemainingBalance() — Returns true when amount_remaining is greater than zero
• canBeApplied() — Returns true when the status is issued and there is a remaining balance

Voiding a credit note

Use the Void action on the detail page and provide a reason. The void(reason, voidedBy) method records voided_at, void_reason, voided_by, and sets the status to voided. Voiding does not reverse payments already applied to invoices — review and adjust affected invoices manually if needed.

Client acknowledgement

Credit notes can be shared with clients for formal acknowledgement via a public URL:

• getOrCreatePublicToken() — Generates a unique public_token if one does not exist
• getPublicUrl() — Returns the full URL for client viewing and acknowledgement
• canBeAcknowledged() — Returns true when the status is issued and not yet acknowledged
• acknowledge(name, email, ip) — Records acknowledged_by_name, acknowledged_by_email, acknowledged_at, and acknowledged_ip

Statistics cards

The Credit Notes list page displays four summary cards: Total Credit (combined total), Issued (count and total), Applied (count and total), and Voided (count and total).

Detail page actions

• Issue — Change status from draft to issued and auto-apply to the linked invoice
• Apply to Invoice — Apply remaining credit to a selected invoice
• Edit — Modify the credit note (draft status only)
• Download PDF — Generate and download the credit note as a PDF
• Duplicate — Create a copy as a new draft
• Print — Open the print dialog
• Send to Client — Email the PDF with the public acknowledgement link
• Void — Void the credit note with a reason

Tips

• Always link to the original invoice — Even if you plan to apply credit elsewhere, linking to the original provides a clear audit trail.
• Use the correct reason — Selecting the right reason makes reporting meaningful and helps identify patterns (e.g., frequent damage credits may indicate a packing issue).
• Send credit notes to clients — Clients appreciate formal documentation. Use Send to Client so they have a record for their own accounts.
• Check remaining balance before voiding — Voiding does not reverse applied payments. Ensure affected invoices are correct first.
• Use acknowledgement for compliance — Client acknowledgement creates a paper trail valuable for audits and dispute resolution.