Disputes

List & Retrieve Disputes

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:

ParameterTypeDescription
stateenumCanonical state, e.g. needs_response.
phaseenumDispute phase, e.g. dispute.
reasonenumCanonical reason, e.g. product_not_received.
amount_gteint (cents)Only disputes with amount ≥ this.
amount_lteint (cents)Only disputes with amount ≤ this.
created_gtedatetimeCreated on/after this timestamp.
created_ltedatetimeCreated on/before this timestamp.
due_beforedatetimeEvidence 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.

$curl -s "https://dev-api.truemed.com/api/v1/disputes?state=needs_response&page_size=50" \
>  -H "Authorization: Bearer $TRUEMED_API_KEY"
1{
2  "disputes": [
3    {
4      "dispute_id": "b3f1c0a2-1d4e-4c8a-9f2b-7e6d5c4b3a21",
5      "processor_dispute_id": "du_1QabcdEXAMPLE",
6      "processor": "STRIPE",
7      "state": "needs_response",
8      "phase": "dispute",
9      "outcome": null,
10      "reason": "product_not_received",
11      "amount": 8999,
12      "currency": "usd",
13      "due_by": "2026-07-12T23:59:59Z",
14      "created_at": "2026-06-28T14:03:11Z",
15      "resolved_at": null,
16      "counters": [],
17      "metadata": {}
18    }
19  ]
20}

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

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

$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"}}'