Disputes

Multi-subject commercial dispute case driven by a process.

Business object

Vue d’ensemble

Dispute endpoints open, list, retrieve, and update the scope of a commercial case. Final resolution is performed explicitly in the associated process.

See also the business-model page dispute for semantics, relationships, and functional lifecycle.

Contrat JSON

Objet `dispute`

Responses use the prefixed identifier dis_ and the field object to make the type explicit.

buyer_idstring

Buyer company shared by all subjects.

subjectsarray

Invoices, orders, or contextualized line items actually disputed.

currencystring | null

Single currency derived from monetary subjects.

amount_disputednumber | null

Optional aggregated disputed amount.

statusenum

`open`, `resolved`, or `cancelled`.

resolution_statusenum

`pending`, `accepted`, `partially_accepted`, `rejected`, or `withdrawn`.

related_objectsarray

Significant business objects linked to handling or resolution.

process_instance_idstring | null

Current process instance owning the case.

REST

Endpoints

Method	Endpoint	Usage
POST	`/v1/disputes`	Open a case and start its process.
GET	`/v1/disputes`	List cases with filters for merchant, buyer, invoice, status, or resolution status.
GET	`/v1/disputes/{id}`	Retrieve a case.
POST	`/v1/disputes/{id}`	Update a case while it is still open.
GET	`/v1/invoices/{id}/disputes`	List cases covering an invoice.

Events

Associated events

These events can be consumed through platform webhooks when the account is configured to receive them.

dispute.createddispute.resolveddispute.cancelledinvoice.disputedinvoice.dispute_cleared

Behavior

Points d’attention

A `line_item` must always be contextualized by `invoice_id` and/or `order_id`.
All monetary subjects in the same case use the same currency.
A terminal process status does not automatically close the dispute: the business resolution remains explicit.