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

# Get Dispute

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

Retrieve a single dispute by its Truemed `dispute_id`, with everything you need to decide how to respond: its canonical state and phase, the reason code, the disputed amount and currency, the evidence deadline, and the recommended evidence for the dispute's reason. Only disputes on your own sales channel's payments are accessible — any other ID returns 404.

## Response Notes

`state` is processor-agnostic. Every dispute, whatever the processor, maps to one of eight canonical states:

| State | Meaning |
|-------|---------|
| `inquiry` | A pre-dispute warning or retrieval request. Not yet a chargeback; no funds withdrawn. |
| `needs_response` | An open chargeback awaiting your evidence by `due_by`. The only state you can `accept`. |
| `under_review` | Evidence submitted; the processor or card network is deciding. |
| `won` | Resolved in your favor; funds retained. |
| `lost` | Resolved against you; funds withdrawn. |
| `accepted` | You conceded the dispute (see Accept Dispute). |
| `expired` | The evidence deadline passed with no response. |
| `closed` | An inquiry that resolved without becoming a chargeback — a favorable no-contest outcome, tracked separately from `won`. |

- `phase` (`inquiry`, `dispute`, `pre_arbitration`, `arbitration`) is **orthogonal** to `state`: it tells you which round of the lifecycle you're in, not whether the dispute is open or resolved.
- `outcome` is null until the dispute reaches a terminal state (`won`, `lost`, `accepted`, `expired`, `closed`).
- `amount` is the **original disputed amount in cents** and does not change with the outcome; `currency` is the ISO code.
- `due_by` is set only while the dispute is challengeable — it's null for inquiries and for resolved disputes.
- `evidence_requirements` is the recommended evidence for this dispute's `reason`, resolved by Truemed: a `merchant_explanation` narrative (Markdown) plus categories grouped by weight into `compelling`, `supporting`, and `other`, each entry carrying its canonical `category`, display `label`, helper `description`, and whether it takes free text and/or a file.
- `counters` is the full chain of evidence submissions (counters) for this dispute across phases.
- State, amounts, and deadlines are read-only and advance only through processor events. The only writable fields are exposed through Accept Dispute and Update Dispute Metadata.

Reference: https://developers.truemed.com/api-reference/disputes/retrieve-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

### Path parameters

- `business_id` (string, required) — The Truemed dispute ID (UUID).

## Response

### 200

Successful response

- `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.
- `payment` (PaymentSummaryResource, required) — Summary of the payment the dispute was filed against.
- `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.
- `evidence_requirements` (DisputeEvidenceRequirements, optional) — Recommended evidence for this dispute's reason, grouped by weight (compelling / supporting / other), plus Truemed's merchant narrative on how to contest.
- `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.

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

### PaymentSummaryResource

- `order_id` (string, optional, nullable) — ID (UUID) of the Truemed payment session or order the disputed payment belongs to. For a payment session it matches `payment_session_id`. Null when the payment has no linked record.

### 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.

### DisputeEvidenceRequirements

- `compelling` (list of DisputeEvidenceCategorySpec, optional, default: []) — Evidence most likely to overturn the dispute, in display order.
- `merchant_explanation` (string, optional, default: ) — Truemed's reason-specific narrative (Markdown) on how to contest this dispute. Empty when the reason has no configured guidance.
- `other` (list of DisputeEvidenceCategorySpec, optional, default: []) — Every remaining category the processor accepts, so nothing is unreachable in the form.
- `supporting` (list of DisputeEvidenceCategorySpec, optional, default: []) — Additional recommended evidence (supporting and context tiers), in display order.

### 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.

### DisputeEvidenceCategorySpec

- `category` (enum, required) — Canonical evidence category.
  - 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`
- `description` (string, required) — Merchant-facing helper text explaining what to provide; empty when the category has none.
- `file` (boolean, required) — Whether the category accepts a file upload.
- `label` (string, required) — Merchant-facing display label for the category.
- `text` (boolean, required) — Whether the category accepts free text.

## Examples

**Response**

```json
{
  "amount": 8999,
  "created_at": "2026-01-20T14:32:00Z",
  "currency": "usd",
  "dispute_id": "d1f8c2a4-9b3e-4c17-8a2d-5e6f7a8b9c0d",
  "payment": {
    "order_id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
  },
  "processor": "STRIPE",
  "processor_dispute_id": "du_1Q9XyZ2eZvKYlo2CDeFgHiJk",
  "reason": "product_not_received",
  "state": "needs_response",
  "counters": [
    {
      "counter_id": "c7b1e2d3-4a5f-4b6c-9d8e-0f1a2b3c4d5e",
      "created_at": "2026-01-21T09:15:00Z",
      "phase": "dispute",
      "revision": 3,
      "state": "draft",
      "updated_at": "2026-01-21T09:47:12Z",
      "evidence_items": [
        {
          "category": "shipping_tracking_number",
          "file_ids": [],
          "text": "1Z999AA10123456784"
        },
        {
          "category": "shipping_documentation",
          "file_ids": [
            "f47ac10b-58cc-4372-a567-0e02b2c3d479"
          ],
          "text": null
        }
      ],
      "submitted_at": null,
      "submitted_by": null
    }
  ],
  "due_by": "2026-02-03T23:59:59Z",
  "evidence_requirements": {
    "compelling": [
      {
        "category": "shipping_tracking_number",
        "description": "Carrier tracking number showing the order was delivered to the cardholder's address.",
        "file": false,
        "label": "Shipping tracking number",
        "text": true
      },
      {
        "category": "service_documentation",
        "description": "Records showing the service was rendered, for service-based orders.",
        "file": true,
        "label": "Service documentation",
        "text": true
      },
      {
        "category": "service_date",
        "description": "The date the service was provided.",
        "file": false,
        "label": "Service date",
        "text": true
      }
    ],
    "merchant_explanation": "The cardholder says the order never arrived. Lead with carrier tracking that shows delivery to the cardholder's address and any signed proof of delivery; for service orders, provide service records and the service date. Supplement with your communications confirming the shipment.",
    "other": [
      {
        "category": "receipt",
        "description": "The order receipt or invoice.",
        "file": true,
        "label": "Receipt",
        "text": false
      },
      {
        "category": "customer_signature",
        "description": "A signed order form or delivery receipt.",
        "file": true,
        "label": "Customer signature",
        "text": false
      }
    ],
    "supporting": [
      {
        "category": "shipping_documentation",
        "description": "Proof of shipment such as a carrier label or packing slip.",
        "file": true,
        "label": "Shipping documentation",
        "text": false
      },
      {
        "category": "customer_communication",
        "description": "Emails or messages with the cardholder about the order or its delivery.",
        "file": true,
        "label": "Customer communication",
        "text": true
      }
    ]
  },
  "metadata": {
    "assigned_to": "ops-disputes-team",
    "internal_case_id": "OPS-4821"
  },
  "network_reason_code": "13.1",
  "outcome": null,
  "phase": "dispute",
  "prior_dispute_id": null,
  "resolved_at": null
}
```

**SDK Code**

```python Example
import requests

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

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/business_id';
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);
}
```