Dispute Success Fee

Contest a success fee — the outcome was reversed, restated, duplicated, or falls outside the agreement.

POST/api/v1/billing/dispatch

Request

curl -X POST "<BASE_URL>/api/v1/billing/dispatch" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-CQRS-Action: DISPUTE_SUCCESS_FEE" \
  -H "Content-Type: application/json" \
  -d '{
    "current_status": "DISPUTED",
    "reason": "CUSTOMER_DISPUTE",
    "success_fee_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }'

Authorization

Minimum role: FinanceThe caller must hold this role or a higher one.
Action: DISPUTE_SUCCESS_FEE

Headers

AuthorizationstringRequired
Access token of the signed-in user, as a Bearer token. It identifies the user, their role and the workspace.
X-CQRS-ActionstringRequired
Names the command to run. Must be DISPUTE_SUCCESS_FEE for this endpoint.
Content-TypestringRequired
Always application/json.
X-Idempotency-KeystringOptional
A key you choose that is unique to this attempt. A command repeated with the same key is not applied a second time.
X-Correlation-IdstringOptional
Your own identifier for the request. Returned in the x-correlation-id response header; generated when you leave it out.

Request body

current_statusenumRequired
No description yet.
Allowed values
- DISPUTED
- BILLED
- PENDING_VERIFICATION
- QUALIFIED
- NOT_QUALIFIED
- CLAWED_BACK
- VOID
PENDING_VERIFICATION
Outcome recorded; inside the verification window. Nothing is billable yet — a fee invoiced the instant a deal flips to won is a credit note waiting to happen.
QUALIFIED
Verified and above the qualifying floor. Billable.
NOT_QUALIFIED
Verified but below the floor, or otherwise outside the contract. Terminal, and distinct from Void: the outcome was real, the fee simply was not earned.
CLAWED_BACK
Billed, then recovered in whole or part after the outcome was reversed.
VOID
Withdrawn before billing — duplicate record, or a dispute upheld.
reasonenumRequired
Why a success fee is being contested. Recorded because a pattern of one reason is a process defect, not a series of one-offs.
Allowed values
- CUSTOMER_DISPUTE
- OUTCOME_REVERSED
- VALUE_RESTATED
- DUPLICATE_OUTCOME
- NOT_ATTRIBUTABLE
OUTCOME_REVERSED
The underlying deal was reversed or cancelled.
VALUE_RESTATED
The outcome stands but its value was restated downward.
DUPLICATE_OUTCOME
The same outcome was recorded twice.
NOT_ATTRIBUTABLE
The outcome did not meet the contract's qualifying conditions.
success_fee_iduuidRequired
No description yet.
expected_versioninteger or nullOptional
CORE invariant: mutations carry the version they read. Absent preserves legacy callers.
notestring or nullOptional
No description yet.

Response

Status 202. The command was applied. The body reports the outcome and, where the command changes a record, that record's new state.

successbooleanRequired
true when the command was applied.
error_messagestringRequired
Empty when the command was applied.
projected_stateobjectOptional
The record as it stands after the command.
event_payloadobjectOptional
The event the command recorded.
insightsarray of objectOptional
Advisory notes about the result. Each has a code, a message and an impact number.

Errors

Every error carries an HTTP status. Where it also carries a code, branch on the code, not on the message.

400X-CQRS-Action is missing or names a command this route does not accept. Send DISPUTE_SUCCESS_FEE.
400DOMAIN_ROUTINGThe body is not a valid command. Check the required fields and their types.
401The access token is missing, expired or not valid.
401L1_AUTHThe caller's role is below finance or the caller has no access to this record.
403L1_POLICYA business rule refused the command. The message names the rule.
409L1_VERSIONexpected_version is not the record's current version. Read the record again, then retry.
409L1_IDEMPOTENCYA command with this idempotency key was already applied.
409CONFLICTThe command would duplicate a record that must be unique.
500L3_COMMITThe command was valid but could not be saved.