# Get a dispute

> The disputes.get operation: GET /api/v1/disputes/{id} in the REST API and the disputes_get tool in the MCP server.

Returns one dispute of the brand: the disputed payment and customer, the processor's reference and reason, the
amount and the dispute fee, the deadline to respond (`evidenceDueBy`), its status (`needs_response`,
`under_review`, `won`, `lost`), the ledger postings (the chargeback, and its reversal when won), the wallets it
froze, the unused credits it took back from the wallet, the evidence pack once built and submitted, the team's
notes and assignee, and the timeline.

## At a glance

- **REST:** `GET /api/v1/disputes/{id}`
- **MCP tool:** `disputes_get`
- **Operation ID:** `disputes.get`
- **Scope:** Brand
- **Permission:** `disputes:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Authentication:** API key with the `disputes:read` scope
- **Since:** M8

## Request

### Path parameters

| Field | Type      | Description |
| ----- | --------- | ----------- |
| `id`  | `dp_…` ID |             |

### Query parameters

This operation takes no query parameters.

## Response

`200 OK` with a JSON object:

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

## Examples

### A new chargeback

```http
GET /api/v1/disputes/dp_01m4ttwd3veh9apbewxheq5xb1
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "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
}
```

## Errors

| Code                                                                                     | HTTP status | When                                            | What to do                                                                                           |
| ---------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404         | No dispute with this ID in this brand and mode. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
| [`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): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`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), [`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).