List disputes · Ownrecord docs

Lists the brand's disputes (chargebacks and inquiries reported by the payment processor) in the mode of the request, newest first. Filter by status (needs_response, under_review, won, lost; one or several), customerId or paymentId. Paginate with limit (1–100, default 10) and starting_after.

Each dispute has its amount and fee, the deadline to respond (evidenceDueBy), the ledger postings, the customer's wallets it froze and the credits it took back, and its evidence pack once built.

At a glance

REST: GET /api/v1/disputes
MCP tool: disputes_list
Operation ID: disputes.list
Scope: Brand
Permission: disputes:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Pagination: limit (at most 100) and starting_after
Authentication: API key with the disputes:read scope
Since: M8

Request

Query parameters

Field	Type	Required	Description
`status`	one of `needs_response`, `under_review`, `won`, `lost` or array of one of `needs_response`, `under_review`, `won`, `lost`	No
`customerId`	`cus_…` ID	No	Disputes of one customer (`cus_…`).
`paymentId`	`pay_…` ID	No	Disputes of one payment (`pay_…`).
`limit`	integer (1 to 100)	No
`starting_after`	`dp_…` ID	No	The `next_cursor` of the previous page.

Response

200 OK with a JSON object, a page of the list (newest first):

Field	Type	Description
`object`	`"list"`
`data`	array of object
`data[].id`	`dp_…` ID
`data[].object`	`"dispute"`
`data[].livemode`	boolean
`data[].entityId`	`ent_…` ID
`data[].brandId`	`brd_…` ID
`data[].paymentId`	`pay_…` ID
`data[].customerId`	`cus_…` ID
`data[].processor`	one of `stripe`, `mollie`, `fake`
`data[].processorConnectionId`	`pcon_…` ID
`data[].processorRef`	string
`data[].reason`	string or null
`data[].processorStatus`	string or null
`data[].status`	one of `needs_response`, `under_review`, `won`, `lost`
`data[].inquiry`	boolean
`data[].fundsWithdrawnAt`	date-time or null
`data[].amount`	money
`data[].fee`	money or null
`data[].evidenceDueBy`	date-time or null
`data[].openedAt`	date-time
`data[].closedAt`	date-time or null
`data[].ledgerTxnIds`	array of `txn_…` ID
`data[].walletFreeze`	object or null
`data[].walletReversal`	object or null
`data[].evidence`	object or null
`data[].notes`	string or null
`data[].assignee`	object or null
`data[].history`	array of object
`data[].history[].at`	date-time
`data[].history[].event`	one of 10 values, e.g. `opened`, `wallet_frozen`, `funds_withdrawn` (all in the OpenAPI document)
`data[].history[].by`	string
`data[].history[].note`	string or null
`data[].createdAt`	date-time
`data[].updatedAt`	date-time
`data[].version`	integer (at least 1)
`has_more`	boolean
`next_cursor`	`dp_…` ID or null

Examples

Disputes that need a response

HTTP

GET /api/v1/disputes?status=needs_response
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "list",
  "data": [
    {
      "id": "dp_01m4ttwd3veh9apbewxheq5xb1",
      "object": "dispute",
      "livemode": true,
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
      "paymentId": "pay_01m4ttwd3veh9apbewxheq5xb2",
      "customerId": "cus_01m4ttwd3veh9apbewxheq5xb3",
      "processor": "stripe",
      "processorConnectionId": "pcon_01m4ttwd3veh9apbewxheq5xb4",
      "processorRef": "dp_1QOwnrecordTest01",
      "reason": "fraudulent",
      "processorStatus": "needs_response",
      "status": "needs_response",
      "inquiry": false,
      "fundsWithdrawnAt": "2026-10-18T08:00:00.000Z",
      "amount": {
        "amount": "12500000",
        "currency": "EUR"
      },
      "fee": {
        "amount": "15000000",
        "currency": "EUR"
      },
      "evidenceDueBy": "2026-10-25T23:59:59.000Z",
      "openedAt": "2026-10-18T08:00:00.000Z",
      "closedAt": null,
      "ledgerTxnIds": ["txn_01m4ttwd3veh9apbewxheq5xb6"],
      "walletFreeze": {
        "walletIds": ["wal_01m4ttwd3veh9apbewxheq5xb5"],
        "frozenAt": "2026-10-18T08:00:00.000Z",
        "unfrozenAt": null
      },
      "walletReversal": {
        "walletId": "wal_01m4ttwd3veh9apbewxheq5xb5",
        "credits": {
          "amount": "10000000",
          "currency": "EUR"
        },
        "restored": null
      },
      "evidence": null,
      "notes": null,
      "assignee": null,
      "history": [
        {
          "at": "2026-10-18T08:00:00.000Z",
          "event": "opened",
          "by": "system",
          "note": null
        },
        {
          "at": "2026-10-18T08:00:00.000Z",
          "event": "wallet_frozen",
          "by": "system",
          "note": "1 wallet"
        },
        {
          "at": "2026-10-18T08:00:00.000Z",
          "event": "funds_withdrawn",
          "by": "system",
          "note": null
        }
      ],
      "createdAt": "2026-10-18T08:00:00.000Z",
      "updatedAt": "2026-10-18T08:00:00.000Z",
      "version": 2
    }
  ],
  "has_more": false,
  "next_cursor": null
}

One customer's disputes

HTTP

GET /api/v1/disputes?customerId=cus_01m4ttwd3veh9apbewxheq5xb3&limit=20
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "list",
  "data": [
    {
      "id": "dp_01m4ttwd3veh9apbewxheq5xb1",
      "object": "dispute",
      "livemode": true,
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
      "paymentId": "pay_01m4ttwd3veh9apbewxheq5xb2",
      "customerId": "cus_01m4ttwd3veh9apbewxheq5xb3",
      "processor": "stripe",
      "processorConnectionId": "pcon_01m4ttwd3veh9apbewxheq5xb4",
      "processorRef": "dp_1QOwnrecordTest01",
      "reason": "fraudulent",
      "processorStatus": "needs_response",
      "status": "needs_response",
      "inquiry": false,
      "fundsWithdrawnAt": "2026-10-18T08:00:00.000Z",
      "amount": {
        "amount": "12500000",
        "currency": "EUR"
      },
      "fee": {
        "amount": "15000000",
        "currency": "EUR"
      },
      "evidenceDueBy": "2026-10-25T23:59:59.000Z",
      "openedAt": "2026-10-18T08:00:00.000Z",
      "closedAt": null,
      "ledgerTxnIds": ["txn_01m4ttwd3veh9apbewxheq5xb6"],
      "walletFreeze": {
        "walletIds": ["wal_01m4ttwd3veh9apbewxheq5xb5"],
        "frozenAt": "2026-10-18T08:00:00.000Z",
        "unfrozenAt": null
      },
      "walletReversal": {
        "walletId": "wal_01m4ttwd3veh9apbewxheq5xb5",
        "credits": {
          "amount": "10000000",
          "currency": "EUR"
        },
        "restored": null
      },
      "evidence": null,
      "notes": null,
      "assignee": null,
      "history": [
        {
          "at": "2026-10-18T08:00:00.000Z",
          "event": "opened",
          "by": "system",
          "note": null
        },
        {
          "at": "2026-10-18T08:00:00.000Z",
          "event": "wallet_frozen",
          "by": "system",
          "note": "1 wallet"
        },
        {
          "at": "2026-10-18T08:00:00.000Z",
          "event": "funds_withdrawn",
          "by": "system",
          "note": null
        }
      ],
      "createdAt": "2026-10-18T08:00:00.000Z",
      "updatedAt": "2026-10-18T08:00:00.000Z",
      "version": 2
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A filter or pagination value is invalid.	Fix the fields listed in `details.issues` and send the request again.
`permission_denied`	403	You can't see disputes of this brand.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, scope_required, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

Disputes that need a response#

One customer's disputes#

Errors#