Overweight Refund

Accept or reject overweight refund tickets from the Overweights screen, with audit (compensations), client notification, and optional editable refund amount.

Overview

When an admin accepts an overweight refund from the Overweights screen, the system must:

1. Audit — Create the corresponding record in the refunds audit module (table compensations, and compensations_history if applicable). The flow reuses the same patterns as the refunds module so the audit trail is consistent.

2. Notify — Send the automatic client communication (e.g. WhatsApp template) using the same notification path as the refunds flow.

3. Editable amount — Allow editing the refund amount before applying. The amount is optional in the confirmation modal; when provided it is validated and used for balance, surcharge, and compensation.

Key Concepts

Concept	Description
Overweight ticket	A support ticket for an overweight charge that can be accepted (refund) or rejected.
Compensation	Audit record in compensations for an accepted refund; links ticket, surcharge, amount, and approver.
Approved amount	Optional refund amount the admin can set in the accept modal; must be > 0 and ≤ original surcharge amount.

Data Flow

Accept path (with compensation and notification)

Database

Tables

Table	Purpose
compensations	Audit record for each accepted refund; stores ticket_id, surcharge_id, approved_amount, approver, status. New rows inserted when accepting from the Overweights screen. No new columns or migration.
compensations_history	History entries when the refunds module writes them for compensation creation/update; same behavior for this path when applicable.

Key Relationships

Compensation rows link to company_tickets (ticket_id) and surcharges (surcharge_id for the refund surcharge). Same shape as other accepted refunds in the refunds module.

Key Decisions

Decision	Reasoning	Alternatives Considered
Reuse existing methods	Single audit trail and consistent behavior; avoid duplicating compensation and notification logic.	Implementing separate compensation/notification paths for overweights.
Compensation shape aligned with refunds	Refunds module already defines the contract; overweight acceptance is another entry point to the same audit.	Custom compensation schema only for overweights.
Backend as source of truth for amount	approved_amount is validated server-side (0 < amount ≤ surcharge.amount); frontend validation is optional.	Relying only on frontend validation.

Dependencies

• Internal: refunds.util (compensation insert), ticketsV2 (notifyTicketChangesByWhatsapp), overweight.util (applyCounterSurcharge), frontend Overweights table and API.
• External: WhatsApp (or existing template channel) for client notification; same path as refunds module.

Related Documentation

• User Guide — Step-by-step instructions for accepting or rejecting overweight refunds.
• API — Endpoint reference for PUT /overweights/ticket/:id.
• UI — Overweights screen, accept modal, and user flows.