> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# List and retrieve disputes

> How to list, filter, and retrieve disputes, and update their metadata, scoped to your sales channel.

Both endpoints are scoped to your sales channel: you only ever see disputes on your own charges. Authenticate with your
API key, or with a session plus the `x-truemed-sales-channel-id` header.

## List disputes

`GET /api/v1/disputes` returns your disputes, newest first.

### Filters

All filters are optional query parameters and combine with AND:

| Parameter     | Type        | Description                                         |
| ------------- | ----------- | --------------------------------------------------- |
| `state`       | enum        | Canonical state, e.g. `needs_response`.             |
| `phase`       | enum        | Dispute phase, e.g. `dispute`.                      |
| `reason`      | enum        | Canonical reason, e.g. `product_not_received`.      |
| `amount_gte`  | int (cents) | Only disputes with `amount` ≥ this.                 |
| `amount_lte`  | int (cents) | Only disputes with `amount` ≤ this.                 |
| `created_gte` | datetime    | Created on/after this timestamp.                    |
| `created_lte` | datetime    | Created on/before this timestamp.                   |
| `due_before`  | datetime    | Evidence deadline (`due_by`) before this timestamp. |

### Pagination

Offset pagination via `page` (default `1`) and `page_size` (default `30`, max `100`). Requesting a `page_size` above 100
is rejected.

```bash
curl -s "https://dev-api.truemed.com/api/v1/disputes?state=needs_response&page_size=50" \
  -H "Authorization: Bearer $TRUEMED_API_KEY"
```

```json
{
  "disputes": [
    {
      "dispute_id": "b3f1c0a2-1d4e-4c8a-9f2b-7e6d5c4b3a21",
      "processor_dispute_id": "du_1QabcdEXAMPLE",
      "processor": "STRIPE",
      "state": "needs_response",
      "phase": "dispute",
      "outcome": null,
      "reason": "product_not_received",
      "amount": 8999,
      "currency": "usd",
      "due_by": "2026-07-12T23:59:59Z",
      "created_at": "2026-06-28T14:03:11Z",
      "resolved_at": null,
      "counters": [],
      "metadata": {}
    }
  ]
}
```

> **Info**
>
> To find a dispute for a specific order, filter by `created_gte`/`created_lte` around the order date and match on the
> returned fields, or store the `dispute_id` from the `dispute.created` webhook when it arrives.

## Retrieve a dispute

`GET /api/v1/disputes/{dispute_id}` returns one dispute by its Truemed UUID. A dispute that isn't on your sales channel
returns `404`.

The detail response includes every list field plus `evidence_requirements` and the `payment` summary:

* **`evidence_requirements`** — the recommended evidence for **this dispute's `reason`**, resolved by Truemed and
  grouped by weight:

  * `merchant_explanation` — a Markdown narrative on how to contest this reason (may be empty).
  * `compelling` — the evidence most likely to overturn the dispute, in display order.
  * `supporting` — additional recommended evidence.
  * `other` — every remaining category the processor accepts, so nothing is unreachable in your evidence form.

  Each category entry carries its `category`, display `label`, helper `description`, and whether it takes free `text`
  and/or a `file`. See [Respond with Evidence](/guides/setup/api/disputes/respond-with-evidence). It's served on the single-dispute
  shapes — this endpoint and the `dispute.*` webhook — not on list rows. (For the full per-reason matrix across every
  reason, use `GET /api/v1/disputes/evidence-guidance`.)
* **`payment`** — a summary of the charge the dispute was filed against, including its `order_id` when the dispute maps to
  a Truemed order.

See [Response Payloads](/guides/setup/api/disputes/payloads) for a fully-populated detail and list response.

`counters` — the full chain of your evidence responses across phases, oldest first (withdrawn drafts excluded; each
carries its `state`, `phase`, `revision`, `evidence_items`, and `submitted_at`) — is on both the list and detail shapes.
See [Respond with Evidence](/guides/setup/api/disputes/respond-with-evidence).

```bash
curl -s "https://dev-api.truemed.com/api/v1/disputes/b3f1c0a2-1d4e-4c8a-9f2b-7e6d5c4b3a21" \
  -H "Authorization: Bearer $TRUEMED_API_KEY"
```

## Update metadata

`POST /api/v1/disputes/{dispute_id}/metadata` replaces the dispute's `metadata` object — arbitrary key/values you set for
your own reference. **Only `metadata` is mutable**; state, amounts, and deadlines are read-only and change through ingest
and dispute actions, never directly.

```bash
curl -s -X POST "https://dev-api.truemed.com/api/v1/disputes/b3f1c0a2-1d4e-4c8a-9f2b-7e6d5c4b3a21/metadata" \
  -H "Authorization: Bearer $TRUEMED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"internal_case_id": "CASE-4821", "owner": "risk-team"}}'
```