nick-doc/03 - API Reference/Dispute API.md

---
title: Dispute API
tags: [api, dispute, reference]
---

# Dispute API

> **Last updated:** 2026-05-29 — aligned with code (see [Doc vs Code Audit Report](../09%20-%20Audits/Doc%20vs%20Code%20Audit%20Report%20-%202026-05-29.md))

> [!note] Current implementation
> The Dispute module now has a Mongoose model, controller routes, dashboard routes, and release-hold helper routes mounted under `/api/disputes`. Keep this page aligned with both `backend/src/routes/disputeRoutes.ts` and `backend/src/services/dispute/disputeRoutes.ts`.

Endpoints live under `/api/disputes/*`. `backend/src/routes/disputeRoutes.ts` delegates to `DisputeController` (`backend/src/controllers/disputeController.ts`) for CRUD/triage. `backend/src/services/dispute/disputeRoutes.ts` provides lightweight release-hold endpoints (`raise`, `resolve`, `status`) used by escrow release gating. The routers apply `authenticateToken` globally — every endpoint requires `Bearer JWT`.

> [!warning] Route shadowing — both dispute routers are mounted at `/api/disputes`
> The dashboard router is mounted **first** in `app.ts`. Its `POST /:id/resolve` intercepts requests before the admin-guarded release-hold router's resolve handler. Confirm which handler will run before wiring automation to either resolve endpoint.

> [!danger] Security issues — see individual endpoint notes below
> Several endpoints that are documented as admin-only have **no role guard** in the current codebase. Any authenticated user can call them. These are noted per-endpoint.

> [!note] Real-time events
> All socket events from `DisputeService` are currently **TODO stubs**. No real-time events fire from dispute mutations. Notifications are delivered via `POST /api/notifications` → `new-notification` socket event only.

Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[Payment]] context and is the input to the mediation workflow that can lead to refund, replacement, compensation, warning/ban, or no-action. Release/refund execution should go through the ledger-gated [[Payment API]] and [[Payout Flow]].

## Create

### POST /api/disputes

**Description:** Open a dispute against a purchase request.
**Auth required:** Bearer JWT (buyer or seller participant in the request)
**Request body:**
```ts
{
  purchaseRequestId: string;
  reason: "product_quality" | "delivery_delay" | "wrong_item" | "payment_issue" | "seller_behavior" | "other";
  description: string;
  evidence?: string[];          // URLs from [[File API]]
  paymentId?: string;
}
```

> **Note:** Valid `reason` values are `product_quality | delivery_delay | wrong_item | payment_issue | seller_behavior | other`. The value `fraud` does not exist.

**Response 201:** `{ success: true, data: { dispute } }`
**Errors:** `400` validation, `403` not a participant of the request, `409` dispute already open for this request.
**Side effects:**
- Notifies the counter-party via `POST /api/notifications` (`new-notification` socket event).
- Pauses any in-flight payout (sets a hold flag on the related [[Payment]]).

### POST /api/disputes/:purchaseRequestId/raise

**Description:** Lightweight release-hold endpoint that marks a purchase request and related payments as disputed. Exists in the backend but has no corresponding frontend action.
**Auth required:** Bearer JWT (buyer who owns the request or admin)
**Request body:** `{ reason?: string }`
**Response 200:** `{ success, message, data }`

### GET /api/disputes/:purchaseRequestId/status

**Description:** Returns release-hold flags for a purchase request, including whether release is currently blocked. Exists in the backend but has no corresponding frontend action.
**Auth required:** Bearer JWT (buyer, preferred seller, or admin)

## Read

### GET /api/disputes

**Description:** List disputes the caller can see (their own as buyer/seller, all for admins).
**Auth required:** Bearer JWT
**Query params:**
- `status` (`open` | `in_progress` | `resolved_buyer` | `resolved_seller` | `closed`)

  > **Note:** The status value `under_review` does not exist. Use `in_progress`.

- `purchaseRequestId`
- `page`, `limit`, `sortBy`, `sortOrder`

**Response 200:** `{ success, data: { disputes, pagination } }`

### GET /api/disputes/statistics

**Description:** Aggregated counts (open, by reason, average resolution time) for admin dashboards.
**Auth required:** Bearer JWT (any authenticated user — backend applies `authenticateToken` only, no role restriction)
**Response 200:** `{ success, data: { open, byReason, avgResolutionHours, ... } }`

### GET /api/disputes/:id

**Description:** Full dispute including evidence list, messages, assigned admin, decision (if any).
**Auth required:** Bearer JWT (participant or admin)
**Errors:** `403` not allowed, `404` not found.

## Admin operations

### POST /api/disputes/:id/assign

**Description:** Assign an admin moderator to the dispute. Sets `assignedAdminId` and transitions status to `in_progress`.
**Auth required:** Bearer JWT

> ⚠️ **SECURITY — NO ROLE GUARD:** Despite being documented as admin-only, there is no role guard on this endpoint. Any authenticated user can self-assign as mediator on any dispute.

**Request body:** `{ adminId: string }`
**Side effects:** Notifies all participants.

### PATCH /api/disputes/:id/status

**Description:** Generic status update (e.g. close without resolution).
**Auth required:** Bearer JWT

> ⚠️ **SECURITY — NO ROLE GUARD:** There is no role guard on this endpoint. Any authenticated user can change dispute status despite documentation claiming admin-only access.

**Request body:** `{ status: string; note?: string }`

### POST /api/disputes/:id/resolve

**Description:** Final adjudication. Records the decision and triggers the appropriate escrow action.
**Auth required:** Bearer JWT

> ⚠️ **SECURITY — NO ROLE GUARD:** This is the dashboard router's resolve handler (mounted first). There is no role guard. Any authenticated user can resolve a dispute, including issuing `action=ban_seller`.

> ⚠️ **ROUTE SHADOWING:** Because the dashboard router is mounted before the admin-guarded release-hold router, this handler intercepts all `POST /api/disputes/:id/resolve` requests. The admin-guarded release-hold resolve endpoint is unreachable at this path.

**Request body:**
```ts
{
  action: "refund" | "replacement" | "compensation" | "warning_seller" | "ban_seller" | "no_action";
  amount?: string;       // optional, e.g. for partial refund or compensation amount
  notes?: string;
}
```
**Response 200:** `{ success, data: { dispute, paymentAction } }`
**Side effects:**
- `action === "refund"` → create/approve the corresponding refund instruction through the ledger-gated payment release/refund flow.
- `action === "no_action"` or seller-favorable outcome → clear hold only after release checks pass.
- Notifies both participants and updates [[PurchaseRequest]] status to `disputed_resolved`.

### POST /api/disputes/:purchaseRequestId/resolve

**Description:** Lightweight release-hold endpoint that clears the disputed hold flags on a purchase request and related payments.
**Auth required:** Bearer JWT (admin)

> ⚠️ **ROUTE SHADOWING:** This endpoint is on the release-hold router which is mounted **after** the dashboard router. The dashboard router's `POST /:id/resolve` matches first, making this handler unreachable in practice. See the route shadowing warning at the top of this page.

**Response 200:** `{ success, message, data }`

## Evidence and messages

### POST /api/disputes/:id/evidence

**Description:** Attach additional evidence (image / document URLs from the [[File API]]) to the dispute. Either party can call.
**Auth required:** Bearer JWT (participant or admin)
**Request body:**
```ts
{
  url: string;
  description?: string;
  type?: "image" | "document" | "video";
}
```
**Response 200:** `{ success, data: { dispute } }` with the evidence appended.

### Messages

Direct messages between disputants and the admin moderator are handled via a dedicated [[Chat]] created automatically when the dispute is opened (`type: "dispute"`). Use the [[Chat API]] endpoints (`POST /api/chat/:id/messages`, `GET /api/chat/:id/messages`) once you have the `chatId` from the dispute payload.

## Real-time

> ⚠️ All socket events from `DisputeService` are currently **TODO stubs** — no real-time events fire from dispute mutations. Dispute notifications are delivered only via `POST /api/notifications`, which in turn emits `new-notification` to the relevant `user-<userId>` room. See [[Socket Events]] for payload shape.

## Related

- [[Dispute]]
- [[Dispute Resolution Flow]]
- [[Payment API]]
- [[Chat API]]