Handle a commercial dispute
Open a case on the invoices, orders, or lines actually disputed, qualify the disagreement, organize the decision, then materialize commercial or financial corrections separately before closing the dispute.
Business objective
The dispute preserves the disputed scope and commercial conclusion. Its associated process orchestrates evidence collection, analysis, human review, and corrective effects. Process status never replaces case resolution.
An Ormuz dispute is a provider-neutral commercial case. It may begin before any financial movement, cover several documents, or lead to a return, credit note, or refund. A PSP chargeback remains a distinct financial signal to integrate into the process when your use case requires it.
Prerequisites
| Element | Role |
|---|---|
| Buyer company | The dispute belongs to one buyer and every subject must be consistent with that scope. |
| Disputed subjects | Invoice, order, or line contextualized by an invoice and/or order; each subject carries its reason. |
Launcher dispute | Associates the case with a process definition accepting platform.dispute under the input dispute. |
| Resolution policy | Defines who can decide, what evidence is required, and which effects are allowed according to the decision. |
Open the dispute
The public entry point is POST /v1/disputes. Creation persists the case as status=open, resolution_status=pending then starts its owning process. When several processes are possible, explicitly supply process_definition_id ; otherwise the merchant's dispute launcher is used.
POST /v1/disputes
{
"merchant_id": "mer_0123456789abcdef0123456789abcdef",
"buyer_id": "cmp_0123456789abcdef0123456789abcdef",
"reference": "DSP-2026-0042",
"source_reference": "CASE-18472",
"subjects": [
{
"type": "invoice",
"invoice_id": "inv_0123456789abcdef0123456789abcdef",
"amount": 12000,
"reason": "incorrect_amount"
}
],
"amount_disputed": 12000
}For a line, retain the context of theinvoice ororder that explains where it sits. Do not broaden the case to documents not genuinely disputed: dispute scope also feeds invoice and receivable projections.
Resolution journey
The case carries the disagreement. A customer-favorable decision may require one or more explicit corrective effects before closure; a rejection or withdrawal may go directly to finalization.
While the case is open, the process may adjust its scope with update_dispute. Once resolved or canceled, the case is closed and its history must no longer be rewritten.
Qualify, analyze, and decide
Start by precisely qualifying the subjects, reason, and disputed amount. update_dispute allows adjustment when new evidence changes case scope. The disputed amount is expressed in minor currency units; all monetary subjects in one case remain in a consistent currency.
A Decision can formalize a deterministic policy. An Agent can analyze documents, classify the reason, or produce a recommendation when its activity and tools are designed for it. An Agent recommendation never automatically becomes the dispute conclusion: the final decision must remain materialized by the process and the controls required by your policy.
When human review is required, use an appropriate user action or approval request, then turn its response into an explicit decision. The case must not be finalized merely because a notification was sent or an operator opened the screen.
Materialize resolution effects
A resolution accepted or partially_accepted may require one or more separate effects: credit note against an invoice, payment refund, creation of a Return, replacement order, or supporting document. finalize_dispute creates none of these objects.
Create corrective objects through their canonical nodes or APIs, then add them to related_objects with update_dispute before closure when linking them helps explain the case. For example, a credit note may carry the accounting correction while a refund intent separately handles returning funds.
Accepting a dispute proves neither that a credit note was issued nor that a refund was executed. Each effect retains its own lifecycle and guarantees.
Finalize or cancel the case
finalize_dispute closes the case with accepted, partially_accepted, rejected or withdrawn. If
amount_accepted when provided, it cannot exceed amount_disputed. Use resolution_detail to preserve a readable explanation of the decision when useful for operations or business audit.
cancel_dispute corresponds to administrative abandonment without a normal commercial resolution — a case opened in error, a duplicate identified by operations, or a case that became irrelevant. Do not use it to hide a rejection or acceptance that was already decided.
While a dispute open covers an invoice, that invoice exposes its disputed state and the receivable projection distinguishes disputed amounts from undisputed amounts. When no open dispute covers the invoice anymore, that projection is cleared.
Events and tracking
| Event | Usage |
|---|---|
dispute.created | The case is opened and its owning process starts. |
invoice.disputed | An invoice becomes covered by at least one open dispute. |
dispute.resolved | The case is closed with an explicit commercial resolution. |
dispute.cancelled | The case is abandoned without normal commercial resolution. |
invoice.dispute_cleared | An invoice is no longer covered by any open dispute. |
Use dispute.created, dispute.resolved, and dispute.cancelled to synchronize the case lifecycle. Invoice events describe the invoice's “disputed” projection and may help suspend or resume collection journeys.
Implementation checklist
- Configure a launcher
disputewith an inputplatform.dispute. - Open the case only on documents or lines that are genuinely disputed.
- Keep currency consistent and the disputed amount explicit when the case is monetary.
- Update scope while the case is open rather than creating artificially fragmented cases.
- Distinguish analysis, recommendation, human review, and final decision.
- Explicitly create any required credit notes, refunds, Returns, or other corrective effects.
- Attach important effects to
related_objectsbefore finalization when business audit needs to link them to the case. - Finalize with a coherent resolution and accepted amount, or cancel only cases that were genuinely abandoned.