Get Dispute | Truemed

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

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.

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.

Authentication

x-truemed-api-keystring

Sales channel API key for merchant server-to-server authentication

Path parameters

business_idstringRequired

The Truemed dispute ID (UUID).

Response

Successful response

amountinteger

The original disputed amount in cents, independent of resolution.

created_atdatetime

When the dispute was created.

currencystring

ISO currency code of the disputed amount.

dispute_idstring

Stable Truemed dispute ID (UUID). Use this as the dispute’s identifier.

paymentobject

Summary of the payment the dispute was filed against.

processorenum

Payment processor the dispute originated from.

processor_dispute_idstring

Raw payment-processor dispute ID (e.g. Stripe du_…), for reconciliation.

reasonenum

Canonical reason the dispute was filed.

stateenum

Canonical dispute state.

counterslist of objectsDefaults to []

Evidence counters for this dispute (the full chain across phases).

due_bydatetime or null

Evidence submission deadline, if the dispute is challengeable.

evidence_requirementsobject

Recommended evidence for this dispute’s reason, grouped by weight (compelling / supporting / other), plus Truemed’s merchant narrative on how to contest.

metadatamap from strings to anyDefaults to {}

Arbitrary merchant-set metadata.

network_reason_codestring or null

Raw card-network reason code behind the dispute (e.g. Visa 10.4), if provided.

outcomeenum or null

Terminal outcome; null until the dispute resolves.

phaseenum or null

Which round of the dispute (inquiry, dispute, pre-arbitration, arbitration).

prior_dispute_idstring or null

Truemed dispute ID (UUID) of the prior round in a pre-arbitration/re-filing chain, if any.

resolved_atdatetime or null

When the dispute reached a terminal state.

Errors

400

Bad Request Error

404

Not Found Error

405

Method Not Allowed Error

500

Internal Server Error

501

Not Implemented Error

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.

$	curl https://dev-api.truemed.com/api/v1/disputes/business_id \
>	-H "x-truemed-api-key: <apiKey>"