Disputes

Response Payloads

A fully-populated look at what the Disputes API returns, so you can model your integration against the complete shape. Two payloads are covered: the detail response (GET /api/v1/disputes/{dispute_id}, the richest shape — also the body of every dispute.* webhook) and the list response (GET /api/v1/disputes, the lean per-row shape).

The values below are illustrative — IDs, tracking numbers, and timestamps are made up to show the shape. The Disputes API is in draft (sandbox only); build against https://dev-api.truemed.com and see Base URLs.

Retrieve a dispute — full detail response

$curl -s "https://dev-api.truemed.com/api/v1/disputes/d1f8c2a4-9b3e-4c17-8a2d-5e6f7a8b9c0d" \
>  -H "Authorization: Bearer $TRUEMED_API_KEY"
1{
2  "dispute_id": "d1f8c2a4-9b3e-4c17-8a2d-5e6f7a8b9c0d",
3  "processor_dispute_id": "du_1Q9XyZ2eZvKYlo2CDeFgHiJk",
4  "prior_dispute_id": null,
5  "processor": "STRIPE",
6  "state": "needs_response",
7  "phase": "dispute",
8  "outcome": null,
9  "reason": "product_not_received",
10  "network_reason_code": "13.1",
11  "amount": 8999,
12  "currency": "usd",
13  "due_by": "2026-02-03T23:59:59Z",
14  "created_at": "2026-01-20T14:32:00Z",
15  "resolved_at": null,
16  "counters": [
17    {
18      "counter_id": "c7b1e2d3-4a5f-4b6c-9d8e-0f1a2b3c4d5e",
19      "state": "draft",
20      "phase": "dispute",
21      "revision": 3,
22      "evidence_items": [
23        {
24          "category": "shipping_tracking_number",
25          "text": "1Z999AA10123456784",
26          "file_ids": []
27        },
28        {
29          "category": "shipping_documentation",
30          "text": null,
31          "file_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
32        }
33      ],
34      "submitted_at": null,
35      "submitted_by": null,
36      "created_at": "2026-01-21T09:15:00Z",
37      "updated_at": "2026-01-21T09:47:12Z"
38    }
39  ],
40  "metadata": {
41    "internal_case_id": "OPS-4821",
42    "assigned_to": "ops-disputes-team"
43  },
44  "evidence_requirements": {
45    "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 dates. Supplement with your communications confirming the shipment.",
46    "compelling": [
47      {
48        "category": "shipping_tracking_number",
49        "label": "Shipping tracking number",
50        "description": "Carrier tracking number showing the order was delivered to the cardholder's address.",
51        "text": true,
52        "file": false
53      },
54      {
55        "category": "service_documentation",
56        "label": "Service documentation",
57        "description": "Records showing the service was rendered, for service-based orders.",
58        "text": true,
59        "file": true
60      },
61      {
62        "category": "service_date",
63        "label": "Service date",
64        "description": "The date the service was provided.",
65        "text": true,
66        "file": false
67      }
68    ],
69    "supporting": [
70      {
71        "category": "shipping_documentation",
72        "label": "Shipping documentation",
73        "description": "Proof of shipment such as a carrier label or packing slip.",
74        "text": false,
75        "file": true
76      },
77      {
78        "category": "customer_communication",
79        "label": "Customer communication",
80        "description": "Emails or messages with the cardholder about the order or its delivery.",
81        "text": true,
82        "file": true
83      }
84    ],
85    "other": [
86      {
87        "category": "receipt",
88        "label": "Receipt",
89        "description": "The order receipt or invoice.",
90        "text": false,
91        "file": true
92      },
93      {
94        "category": "customer_signature",
95        "label": "Customer signature",
96        "description": "A signed order form or delivery receipt.",
97        "text": false,
98        "file": true
99      },
100      {
101        "category": "uncategorized",
102        "label": "Additional evidence",
103        "description": "Any other supporting evidence not covered by a specific category.",
104        "text": true,
105        "file": true
106      }
107    ]
108  },
109  "payment": {
110    "order_id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
111  }
112}

Field guide

  • Identity & routing — dispute_id is the Truemed UUID you use everywhere; processor_dispute_id is the raw Stripe du_… for reconciliation; prior_dispute_id links the previous round in a pre-arbitration/re-filing chain (null if this is the first round).
  • State model — state is one of the eight canonical states, phase is the orthogonal round (inquiry/dispute/pre_arbitration/arbitration), and outcome stays null until the dispute resolves. See Overview for the full state table.
  • Money & deadline — amount is the original disputed amount in cents (never changes with the outcome), currency is the ISO code, and due_by is your evidence deadline (null once the dispute is no longer challengeable).
  • counters — your evidence responses across phases, oldest first; each carries its state, phase, revision (echo it back on the next save for optimistic locking), evidence_items, and submission metadata. See Respond with Evidence.
  • evidence_requirements — the recommended evidence for this dispute’s reason, resolved by Truemed:
    • merchant_explanation — a Markdown narrative on how to contest this reason (may be empty).
    • compelling / supporting / other — categories grouped by weight, in display order. Lead with compelling, then add supporting; other lists the remaining categories the processor accepts so nothing is unreachable in your form.
    • Each entry carries its canonical category, display label, helper description, and whether it accepts free text and/or a file.
  • payment — a summary of the disputed charge, including its order_id when the dispute maps to a Truemed order (null otherwise).

evidence_requirements and payment are served only on this single-dispute shape and the dispute.* webhook — the list rows below omit them. For the full per-reason evidence matrix across every reason, use GET /api/v1/disputes/evidence-guidance.

List disputes — full list response

$curl -s "https://dev-api.truemed.com/api/v1/disputes?state=needs_response&page_size=25" \
>  -H "Authorization: Bearer $TRUEMED_API_KEY"
1{
2  "disputes": [
3    {
4      "dispute_id": "d1f8c2a4-9b3e-4c17-8a2d-5e6f7a8b9c0d",
5      "processor_dispute_id": "du_1Q9XyZ2eZvKYlo2CDeFgHiJk",
6      "prior_dispute_id": null,
7      "processor": "STRIPE",
8      "state": "needs_response",
9      "phase": "dispute",
10      "outcome": null,
11      "reason": "product_not_received",
12      "network_reason_code": "13.1",
13      "amount": 8999,
14      "currency": "usd",
15      "due_by": "2026-02-03T23:59:59Z",
16      "created_at": "2026-01-20T14:32:00Z",
17      "resolved_at": null,
18      "counters": [],
19      "metadata": {
20        "internal_case_id": "OPS-4821"
21      }
22    },
23    {
24      "dispute_id": "a2e9d1b3-7c4f-4a80-b6e1-2f3a4b5c6d7e",
25      "processor_dispute_id": "du_1Q8WvU1dYuJXkn1BCdEfGhIj",
26      "prior_dispute_id": null,
27      "processor": "STRIPE",
28      "state": "under_review",
29      "phase": "dispute",
30      "outcome": null,
31      "reason": "fraudulent",
32      "network_reason_code": "10.4",
33      "amount": 12500,
34      "currency": "usd",
35      "due_by": null,
36      "created_at": "2026-01-18T11:02:44Z",
37      "resolved_at": null,
38      "counters": [],
39      "metadata": {}
40    }
41  ],
42  "pagination": {
43    "current_page": 1,
44    "page_size": 25,
45    "count": 2,
46    "last_page": 1
47  }
48}

Each list row is the lean dispute shape: the same canonical fields as the detail response but without evidence_requirements or payment (fetch the dispute by dispute_id, or read the dispute.* webhook, when you need those). counters and metadata are present on both shapes. The pagination object reports the current page, page size (max 30), total count, and the last_page number.