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

# Dispute API

> [!warning] Not implemented
> The Dispute module is **documented but not yet implemented** in the backend. There is no `backend/src/services/dispute/` directory, no `backend/src/routes/disputeRoutes.ts`, and no `/api/disputes` mount in `app.ts`. The API specification below reflects the *intended* design only.

Endpoints are planned to live under `/api/disputes/*`. The router would be `backend/src/routes/disputeRoutes.ts` and delegate to `DisputeController` (`backend/src/controllers/disputeController.ts`). The router would apply `authenticateToken` globally — every endpoint requires `Bearer JWT`.

Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[Payment]] and is the input to the mediation workflow that ends in either a `resolved_buyer` or `resolved_seller` decision and triggers an escrow release or refund via the [[Payment API]].

## 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: "not_delivered" | "wrong_item" | "damaged" | "quality" | "other";
  description: string;
  evidence?: string[];          // URLs from [[File API]]
  paymentId?: string;
}
```
**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]]).

## 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` | `under_review` | `resolved_buyer` | `resolved_seller` | `closed`)
- `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 (admin)
**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 `under_review`.
**Auth required:** Bearer JWT (admin)
**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 (admin)
**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 (admin)
**Request body:**
```ts
{
  decision: "buyer" | "seller" | "split";
  refundAmount?: number;        // required when "split"
  releaseAmount?: number;       // required when "split"
  reasoning: string;
}
```
**Response 200:** `{ success, data: { dispute, paymentAction } }`
**Side effects:**
- `decision === "buyer"` → triggers `POST /api/payment/shkeeper/:id/refund` flow.
- `decision === "seller"` → triggers `POST /api/payment/shkeeper/:id/release` flow.
- `decision === "split"` → admin executes both partial release and partial refund manually.
- Notifies both participants and updates [[PurchaseRequest]] status to `disputed_resolved`.

## 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

Dispute mutations emit notifications via `POST /api/notifications` which delivers `new-notification` socket events to each participant's `user-<userId>` room. See [[Socket Events]] for payload shape.

## Related

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