Dispute ( dispute )

Role

The case is not limited to one invoice or PSP chargeback. It may cover one or more invoices, orders, or precisely contextualized lines. It preserves stable dispute business state independently from how the process handles it.

Structure

GET /v1/disputes/dis_4a7b

{
"id": "dis_4a7b",
"object": "dispute",
"merchant_id": "mer_1a2b",
"buyer_id": "cmp_9c3d",
"buyer_contact_id": "ctc_5e6f",
"reference": "DSP-2026-0042",
"subjects": [
  {
    "type": "invoice",
    "invoice_id": "inv_7a8b",
    "amount": 12000,
    "reason": "incorrect_amount"
  }
],
"currency": "eur",
"amount_disputed": 12000,
"amount_accepted": null,
"status": "open",
"resolution_status": "pending",
"related_objects": [],
"process_definition_id": "prd_1b2c",
"process_instance_id": "pci_3d4e",
"process_status": "waiting",
"url": "https://…",
"opened_at": "2026-08-24T14:00:00.000Z",
"closed_at": null
}

Subjects

subjects contains only the items actually disputed. Supported types are invoice, order and line_item. Each subject carries its own reason and may carry an amount.

[
{
  "type": "invoice",
  "invoice_id": "inv_7a8b",
  "amount": 12000,
  "reason": "incorrect_amount"
},
{
  "type": "line_item",
  "line_item_id": "li_2f3a",
  "invoice_id": "inv_7a8b",
  "order_id": "ord_6c7d",
  "quantity": 2,
  "amount": 4000,
  "reason": "product_unacceptable"
}
]

A line_item is never disputed without context: it must reference at least one invoice or order and may reference both when relationships are coherent. All monetary subjects in the same case use the same currency.

Lifecycle

status describes the case lifecycle. resolution_status separately describes the commercial conclusion.

Associated process

Creating a dispute selects a process compatible with a typed input platform.dispute. You may explicitly provide process_definition_id or use the system launcher dispute configured for the merchant.

Retries, replays, or corrective forks transfer case ownership to the new instance. Only the current instance can then modify or finalize the dispute through dedicated nodes.

Resolution

The process explicitly decides which actions to perform before finalizing the case: create a credit note, initiate a refund, cancel an order, create a Return, or another business action. The node Finalize dispute creates none of these objects automatically.

Important objects produced during handling may be referenced in related_objects with a business role, for example resolution_credit_note, resolution_refund, or resolution_return.

Impact on invoices

When a dispute open covers an invoice or a line contextualized by that invoice, the invoice exposes disputed = true. The projection remains true while at least one open case still covers the invoice.

The receivable separately exposes disputed and undisputed balances. Payment Commitment carries no notion of disputed or collectible amount.

API

POST /v1/disputes

{
"merchant_id": "mer_1a2b",
"buyer_id": "cmp_9c3d",
"reference": "DSP-2026-0042",
"subjects": [
  {
    "type": "invoice",
    "invoice_id": "inv_7a8b",
    "amount": 12000,
    "reason": "incorrect_amount"
  }
],
"amount_disputed": 12000
}

GET /v1/disputes
GET /v1/disputes/dis_4a7b
POST /v1/disputes/dis_4a7b
GET /v1/invoices/inv_7a8b/disputes

While the case is open, the update endpoint may change its scope, related objects, and references. The final conclusion belongs to the process through the nodes Finalize dispute and Cancel dispute.

Events