# List disputes > The disputes.list operation: GET /api/v1/disputes in the REST API and the disputes_list tool in the MCP server. 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`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter or pagination value is invalid. | Fix the fields listed in `details.issues` and send the request again. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).