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

title, tags

title	tags
Dispute API	api dispute reference

Dispute API

Last updated: 2026-05-30 — resolver role added, role guards applied to assign/status/resolve (commits b9e0f6a, 1d881c5)

[!note] Current implementation The Dispute module has two distinct router families. Keep this page aligned with both backend/src/routes/disputeRoutes.ts and backend/src/services/dispute/disputeRoutes.ts.

Endpoints live under two prefixes:

• /api/disputes/* — backend/src/routes/disputeRoutes.ts delegates to DisputeController (backend/src/controllers/disputeController.ts) for CRUD/triage. All routes apply authenticateToken globally.
• /api/disputes/pr/* — backend/src/services/dispute/disputeRoutes.ts provides lightweight release-hold endpoints (raise, resolve, status) used by escrow release gating. Previously mounted at /api/disputes, causing route shadowing (ISSUE-003). Remounted at /api/disputes/pr in commit 1d881c5 — all release-hold calls must use this new prefix.

[!success] Route shadowing resolved (ISSUE-003) The release-hold router was remounted from /api/disputes to /api/disputes/pr. Both routers now have independent paths and neither shadows the other.

[!note] Resolver role A new resolver role was added (commit fce8a19). Resolvers can view and resolve disputes but have no other platform privileges. They are granted the same access as admin on all dispute-triage operations listed below.

[!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/pr/:purchaseRequestId/raise

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

Path note: Previously served at /api/disputes/:purchaseRequestId/raise. Moved to /api/disputes/pr/:purchaseRequestId/raise in commit 1d881c5 (ISSUE-003 fix).

GET /api/disputes/pr/:purchaseRequestId/status

Description: Returns release-hold flags for a purchase request, including whether release is currently blocked. No corresponding frontend UI 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 or resolver — authorizeRoles('admin', 'resolver') is applied) 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 or resolver moderator to the dispute. Sets assignedAdminId and transitions status to in_progress. Auth required: Bearer JWT (admin or resolver)

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 or resolver)

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 or resolver)

⚠️ 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.
• ISSUE-004 fix (commit 1d881c5): DisputeService.resolveDispute now calls releaseHoldResolve() on the linked purchaseRequestId, clearing the escrow hold so payment release is unblocked automatically after resolution.

POST /api/disputes/pr/: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)

Path note: Previously unreachable due to route shadowing. Moved to /api/disputes/pr/:purchaseRequestId/resolve (commit 1d881c5, ISSUE-003 fix). This endpoint is now reachable.

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