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

title, tags

title	tags
Dispute API	api dispute reference

Dispute API

Last updated: 2026-05-29 — aligned with code (see Doc vs Code Audit Report)

[!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:

{
  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 (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 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:

{
  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:

{
  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