> 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 Disputes

GET https://dev-api.truemed.com/api/v1/disputes

List the card disputes — chargebacks and the pre-dispute inquiries that precede them — raised against payments you've taken through Truemed. Use it to drive a disputes queue in your own dashboard, surface disputes whose evidence deadline is approaching, or reconcile against your records by processor dispute ID. Results are scoped to the sales channel your API key authenticates as: you only ever see disputes on your own payments.

Disputes are returned newest first and paginated with `page` / `page_size` (default 30 per page, max 100). The response `pagination` object reports `current_page`, `page_size`, `total_count`, and `last_page`.

## Request Notes

All filters are optional and combine with AND:

- `state`, `phase`, `reason` — exact match on the canonical enums. See the Get Dispute endpoint for the full state model.
- `amount_gte` / `amount_lte` — disputed amount in **cents**, inclusive on both bounds.
- `created_gte` / `created_lte` — dispute creation time, **inclusive** on both bounds. Pass ISO 8601 datetimes, e.g. `2026-01-01T00:00:00Z`.
- `due_before` — only disputes whose evidence deadline (`due_by`) falls **strictly before** this datetime. Disputes with no deadline — inquiries and already-resolved disputes both have a null `due_by` — are excluded by this filter. Use it together with `state=needs_response` to build a "deadline approaching" view.

## Response Notes

Each item is the same `Dispute` object returned by Get Dispute. Use the stable `dispute_id` (a Truemed UUID) for the detail, accept, and metadata endpoints; use `processor_dispute_id` (e.g. Stripe `du_…`) to reconcile against the processor. State, amounts, and deadlines are read-only — they advance only through processor events, never through this API.

Reference: https://developers.truemed.com/api-reference/disputes/list-dispute

## Authentication

- `x-truemed-api-key` header (required) — Sales channel API key for merchant server-to-server authentication

## Servers

- `https://dev-api.truemed.com` (Development server, default)
- `https://api.truemed.com` (Production server)

## Request

### Query parameters

- `page` (integer, optional) — Optional field indicating which page to access. Defaults to 1.
- `page_size` (integer, optional) — Optional field indicating the number of records per page. Defaults to 30.
- `state` (string, optional) — Filter by canonical state.
- `phase` (string, optional) — Filter by phase.
- `reason` (string, optional) — Filter by reason.
- `amount_gte` (integer, optional) — Only disputes with amount >= this (cents).
- `amount_lte` (integer, optional) — Only disputes with amount \<= this (cents).
- `created_gte` (datetime, optional) — Only disputes created on/after this date.
- `created_lte` (datetime, optional) — Only disputes created on/before this date.
- `due_before` (datetime, optional) — Only disputes whose evidence deadline is before this date.

## Response

### 200

Successful response

- `disputes` (list of DisputeResource, required) — The page of disputes for the authenticated sales channel.
- `pagination` (PaginationBody, optional, nullable) — A pagination object with information about the current page, page size, total count, and last page.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (enum, required)
  - Allowed values: `TotalAmountInvalid`, `ValidationError`
- `message` (string, required)

### 404 Not Found Error

Not Found

- `error` (enum, required)
  - Allowed values: `NotFound`
- `message` (string, required)

### 405 Method Not Allowed Error

Method Not Allowed

- `error` (enum, required)
  - Allowed values: `MethodNotAllowed`
- `message` (string, required)

### 500 Internal Server Error

Internal Server Error

- `error` (enum, required)
  - Allowed values: `ServerError`
- `message` (string, required)

### 501 Not Implemented Error

Not Implemented

- `error` (enum, required)
  - Allowed values: `NotImplemented`
- `message` (string, required)

## Types

### DisputeResource

- `amount` (integer, required) — The original disputed amount in cents, independent of resolution.
- `created_at` (datetime, required) — When the dispute was created.
- `currency` (string, required) — ISO currency code of the disputed amount.
- `dispute_id` (string, required) — Stable Truemed dispute ID (UUID). Use this as the dispute's identifier.
- `processor` (enum, required) — Payment processor the dispute originated from.
  - Allowed values: `STRIPE`, `FAKE`, `EXTERNAL`
- `processor_dispute_id` (string, required) — Raw payment-processor dispute ID (e.g. Stripe `du_…`), for reconciliation.
- `reason` (enum, required) — Canonical reason the dispute was filed.
  - Allowed values: `credit_not_processed`, `duplicate`, `fraudulent`, `general`, `noncompliant`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, `unrecognized`
- `state` (enum, required) — Canonical dispute state.
  - Allowed values: `inquiry`, `needs_response`, `under_review`, `won`, `lost`, `accepted`, `expired`, `closed`
- `counters` (list of CounterResource, optional, default: []) — Evidence counters for this dispute (the full chain across phases).
- `due_by` (datetime, optional, nullable) — Evidence submission deadline, if the dispute is challengeable.
- `metadata` (map from string to any, optional, default: {}) — Arbitrary merchant-set metadata.
- `network_reason_code` (string, optional, nullable) — Raw card-network reason code behind the dispute (e.g. Visa `10.4`), if provided.
- `outcome` (enum, optional, nullable) — Terminal outcome; null until the dispute resolves.
  - Allowed values: `won`, `lost`, `accepted`, `expired`, `closed`
- `payment_session_id` (string, optional, nullable) — The Truemed payment session this dispute belongs to. Null for disputes on non-payment-session charges.
- `phase` (enum, optional, nullable) — Which round of the dispute (inquiry, dispute, pre-arbitration, arbitration).
  - Allowed values: `inquiry`, `dispute`, `pre_arbitration`, `arbitration`
- `prior_dispute_id` (string, optional, nullable) — Truemed dispute ID (UUID) of the prior round in a pre-arbitration/re-filing chain, if any.
- `resolved_at` (datetime, optional, nullable) — When the dispute reached a terminal state.

### PaginationBody

- `count` (integer, required) — The total number of items associated with the provided API key.
- `current_page` (integer, required) — The page requested. If none was provided, this will default to 1.
- `last_page` (integer, required) — The last page. You can iterate through pages by providing integers up to last_page in the page parameter.
- `page_size` (integer, required) — The number of items per page applied to this response.

### CounterResource

- `counter_id` (string, required) — Stable Truemed counter ID (UUID).
- `created_at` (datetime, required) — When this counter was created.
- `phase` (enum, required) — Dispute phase this counter responds to.
  - Allowed values: `inquiry`, `dispute`, `pre_arbitration`, `arbitration`
- `revision` (integer, required) — Optimistic-lock revision; echo it back on the next draft save to detect conflicts.
- `state` (enum, required) — Counter lifecycle state.
  - Allowed values: `draft`, `submitted`, `withdrawn`, `superseded`
- `updated_at` (datetime, required) — When this counter was last updated.
- `evidence_items` (list of EvidenceItem, optional, default: []) — The categorized evidence captured on this counter.
- `submitted_at` (datetime, optional, nullable) — When this counter was submitted to the processor.
- `submitted_by` (string, optional, nullable) — Email of the dashboard user who submitted this counter; null for drafts or API-key submissions.

### EvidenceItem

- `category` (enum, required) — Canonical evidence category; the adapter maps it to the processor's evidence fields.
  - Allowed values: `product_description`, `customer_communication`, `customer_name`, `customer_email`, `customer_purchase_ip`, `customer_signature`, `billing_address`, `receipt`, `shipping_documentation`, `shipping_tracking_number`, `service_documentation`, `service_date`, `access_activity_log`, `refund_policy`, `refund_policy_disclosure`, `refund_refusal_explanation`, `cancellation_policy`, `cancellation_policy_disclosure`, `cancellation_rebuttal`, `duplicate_charge_documentation`, `duplicate_charge_explanation`, `uncategorized`
- `file_ids` (list of string, optional, default: []) — File IDs (from the Files API) attached for this category; must be owned by you.
- `text` (string, optional, nullable) — Free-text evidence for this category.

## Examples

**Response**

```json
{
  "disputes": [
    {
      "amount": 8999,
      "created_at": "2026-01-20T14:32:00Z",
      "currency": "usd",
      "dispute_id": "d1f8c2a4-9b3e-4c17-8a2d-5e6f7a8b9c0d",
      "processor": "STRIPE",
      "processor_dispute_id": "du_1Q9XyZ2eZvKYlo2CDeFgHiJk",
      "reason": "product_not_received",
      "state": "needs_response",
      "counters": [],
      "due_by": "2026-02-03T23:59:59Z",
      "metadata": {
        "internal_case_id": "OPS-4821"
      },
      "network_reason_code": "13.1",
      "outcome": null,
      "phase": "dispute",
      "prior_dispute_id": null,
      "resolved_at": null
    },
    {
      "amount": 12500,
      "created_at": "2026-01-18T11:02:44Z",
      "currency": "usd",
      "dispute_id": "a2e9d1b3-7c4f-4a80-b6e1-2f3a4b5c6d7e",
      "processor": "STRIPE",
      "processor_dispute_id": "du_1Q8WvU1dYuJXkn1BCdEfGhIj",
      "reason": "fraudulent",
      "state": "under_review",
      "counters": [],
      "due_by": null,
      "metadata": {},
      "network_reason_code": "10.4",
      "outcome": null,
      "phase": "dispute",
      "prior_dispute_id": null,
      "resolved_at": null
    }
  ],
  "pagination": {
    "count": 2,
    "current_page": 1,
    "last_page": 1,
    "page_size": 25
  }
}
```

**SDK Code**

```python Example
import requests

url = "https://dev-api.truemed.com/api/v1/disputes"

headers = {"x-truemed-api-key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Example
const url = 'https://dev-api.truemed.com/api/v1/disputes';
const options = {method: 'GET', headers: {'x-truemed-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```