Disputes
Overview
The Disputes module lets rate pavers file disputes against bills, properties, or payments, track dispute status through to resolution, and communicate with agents/admins via a conversation thread.
Navigate to: Sidebar → Disputes or /disputes
Dispute List
| Element | Description |
|---|---|
| Search bar | Search by dispute ID, title, or category |
| Filter tabs | All, and category-specific tabs (e.g. Properties, Billing, Payments) |
| + Add Dispute button | Opens the Create Dispute form |
| Empty state | Gavel icon, "No disputes found," with a prompt to create a dispute |
Dispute Card
| Field | Description |
|---|---|
| Dispute ID | e.g. #DSP-2026-100000002 |
| Status badge | Pending, In Review, Resolved, Closed |
| Title | e.g. "Incorrect Bill Amount" |
| Category | e.g. "Billing Dispute" |
| Filed by | Ratepayer name |
| Related Type | e.g. "Payment", "Property", "Bill" |
| Date filed | Timestamp of dispute creation |
Tapping a dispute card opens Dispute Details.
!!! tip "Things to check" - Filter tabs correctly narrow the list to disputes of that category - Empty state only shows when there are genuinely zero disputes matching the current filter - Tapping a dispute card opens the correct dispute details - Status badge colors are consistent (Pending = yellow, In Review = blue, Resolved = green) - List is sorted by most recent dispute first
Create Dispute
Navigate to: /disputes/create
| Field | Required | Notes |
|---|---|---|
| Dispute Category | Yes | Dropdown (e.g. Billing, Property, Payment) |
| Dispute Title | Yes | Free text |
| Related Types | Yes | Dropdown, e.g. Others, Bill, Property |
| Priority | Yes | Dropdown, defaults to Medium |
| Description of Issue | Yes | Free text, detailed explanation of the dispute |
| Upload Supporting Documents | No | Attach via Gallery, Camera, or File — max 5 items |
| Preferred Contact Method | No | Dropdown (e.g. Email, Phone) |
| Contact detail | No | Shown when Preferred Contact Method is selected — email field or phone field |
Submit Dispute / Cancel at the bottom.
Document Upload
| Element | Description |
|---|---|
| Gallery | Select images from device gallery |
| Camera | Capture a new photo |
| File | Attach a document file |
| Max items | 5 supporting documents |
| Remove | Each attached file has a remove button |
!!! tip "Things to check"
- Dispute Category and Related Types options make sense together (e.g. Billing category restricts Related Types to billing-relevant options)
- Attaching more than 5 files is blocked with a clear message
- Preferred Contact Method correctly swaps the input below it depending on the method chosen
- Leaving all required fields blank and tapping Submit shows validation errors
- After submission, the new dispute appears immediately in the Dispute List with status Pending
- Cancel discards all entered data and returns to the dispute list
Dispute Details
| Field | Description |
|---|---|
| Dispute ID | Unique identifier |
| Title | Dispute title |
| Category | Dispute category |
| Status | Current status (Pending, In Review, Resolved, Closed) |
| Priority | Low, Medium, High |
| Request From | e.g. RatePayer |
| Related Type | Type of entity the dispute is related to |
| Dispute At | Timestamp when the dispute was filed |
| Reason | The description entered when filing |
| Attachments (N) | Files attached — shows "No attachments found" when none, with a refresh icon |
| Replies & Updates | Thread of responses — shows "No replies yet" until an agent/admin responds |
Conversation Thread
The Replies & Updates section displays a chronological conversation thread between the rate payer and agents/admins.
| Element | Description |
|---|---|
| Message bubble | Each message shows the sender, timestamp, and content |
| Reply input | Text input at the bottom for adding a follow-up message |
| Send button | Posts the reply to the thread |
!!! tip "Things to check"
- Status updates (e.g. Pending → In Review → Resolved) reflect promptly once an agent/admin acts on the dispute
- Sending a reply actually posts to Replies & Updates and is visible without leaving and re-opening the screen
- Attachments uploaded at filing time show up correctly, with working preview/download
- Reply input clears after successful submission
- Thread maintains correct chronological order
- Long threads scroll correctly without layout issues
- New messages from agents/admins appear in real time or after a refresh
!!! tip "Things to check" - Dispute lifecycle (create → review → resolve/close) works end to end - All dispute data persists correctly across sessions - Dispute list updates in real time when a new dispute is created or status changes - Conversation thread handles long messages and multiple replies without UI issues