Client Chargeback & Billing

Client Chargeback & Billing

When equipment damage is caused by a client, NexusRMS lets you bill the responsible party directly from the repair record. The chargeback system links repair costs to a client, generates a dedicated invoice, and maintains a full audit trail between the repair and the financial record.

How chargebacks work

Every repair record includes a set of fields that control client billing:

• billable_to_client — A boolean flag that marks the repair as billable. When enabled, the Client Charging panel becomes active on the repair form.
• client_id — The client who will be charged. This is selected via an autocomplete field that searches your client database.
• charged_amount — The amount to invoice the client. This can differ from the repair's total_cost — you may choose to charge more (to cover administrative overhead) or less (as a goodwill gesture).
• chargeback_invoice_id — Once an invoice is generated, its ID is stored here, linking the repair to the invoice for audit purposes.

Chargeback reasons

When marking a repair as billable, select a reason that describes why the client is being charged. The five chargeback reasons are:

1. client_damage — The client physically damaged the equipment during the rental period.
2. misuse — The equipment was used outside its intended purpose or operating parameters.
3. lost_equipment — The equipment was lost or not returned by the client.
4. late_return_damage — Damage that occurred because the equipment was retained beyond the agreed return date.
5. other — Any other billable circumstance not covered above. Add details in the repair notes.

Chargeback workflow

Follow these steps to charge a client for repair costs:

1. Mark as billable — Toggle the billable_to_client switch on the repair form. This activates the Client Charging tab.
2. Assign the client — Use the client autocomplete to select the responsible party. If the repair is linked to a project, the project's client is suggested automatically.
3. Set the charged amount — Enter the amount to invoice. The estimated cost from the repair is shown as a hint to guide your decision.
4. Select a chargeback reason — Choose from the five reasons listed above.
5. Generate the invoice — When the repair reaches completed status, NexusRMS automatically generates a chargeback invoice. You can also trigger this manually via POST /repairs/{id}/chargeback using the RepairAssignmentController.

Invoice generation

The RepairService.generateChargebackInvoice(repair) method handles invoice creation. It performs the following:

• Validates that billable_to_client is true and a client_id is set.
• Checks that no chargeback invoice already exists for this repair (prevents duplicates).
• Uses charged_amount if set; otherwise falls back to total_cost.
• Creates an invoice via the InvoiceService with a 30-day payment term.
• Adds a single line item of type repair, linking the invoice item back to the repair record.
• Stores the generated invoice ID in chargeback_invoice_id on the repair.

Billable defaults by repair type

The RepairType enum includes an isBillableByDefault() method that pre-sets the billable toggle based on the type of repair:

Repair Type	Billable by Default
Corrective	Yes
Preventive	No
Inspection	No
Upgrade	No
Recall	No
Warranty	No

This default can always be overridden manually on each repair.

Cost summary and the detail page

When a repair is marked as billable, the repair detail page displays an informational alert reading "Billable to client" along with the charged amount (e.g. "Charged: £X"). This gives all users immediate visibility that the repair has a financial obligation attached.

Remember that charged_amount and total_cost are independent values. The total cost is calculated from labor_cost + parts_cost + external_cost, while the charged amount is whatever you decide to invoice the client. Review both figures before generating the invoice to ensure accuracy.

Audit trail

The chargeback invoice includes internal notes referencing the repair number (e.g. "Auto-generated from repair #REP-2026-0042"). From the invoice, you can navigate back to the repair record, and from the repair record you can navigate to the linked invoice via chargeback_invoice_id. This bidirectional link ensures full traceability for financial audits.