Skip to main content
POST
Raise a dispute against a statement

Description

Raise dispute Raises a dispute against the active Statement for (tenantUserId, periodStart..periodEnd). Requires the statement to be finalized or closed. Unlike the other lifecycle mutations, this is self-or-admin rather than admin-only: a member may dispute their own statement, admins may dispute any. Authorization:
  • Required role: user or higher

Code Examples

Authorizations

Authorization
string
header
required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Path Parameters

tenantUserId
string<uuid>
required
periodStart
string<date-time>
required
periodEnd
string<date-time>
required

Body

application/json
category
string
required
contestedAmount
number
required

Must be a non-negative number.

description
string
required

Minimum 20 characters.

Minimum string length: 20
referenceLine
string | null

Response

Dispute raised.

Every statements response wraps the payload in { status, message, data }. data carries the per-endpoint payload PLUS the per-tenant feature flag.

status
enum<string>
Available options:
success,
error
message
string
data
object

Response payload shared by the ITEM 2 lifecycle mutations (finalize, payments, adjustments, hold, resume, void, disputes): the updated Statement row, shaped via the same shapeForClient mapper as StatementRosterRow, plus ok: true. The underlying Sequelize row carries additional endpoint-specific detail (e.g. statusHistory) not exhaustively modeled here — treat this as the roster-row core.