> 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. # Response payloads > A fully-populated look at the detail and list shapes the Disputes API returns, so you can model your integration against the complete response. 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). > **Info** > > 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](/guides/setup/api/disputes/overview#base-urls). ## Retrieve a dispute — full detail response ```bash curl -s "https://dev-api.truemed.com/api/v1/disputes/d1f8c2a4-9b3e-4c17-8a2d-5e6f7a8b9c0d" \ -H "Authorization: Bearer $TRUEMED_API_KEY" ``` ```json { "dispute_id": "d1f8c2a4-9b3e-4c17-8a2d-5e6f7a8b9c0d", "processor_dispute_id": "du_1Q9XyZ2eZvKYlo2CDeFgHiJk", "prior_dispute_id": null, "processor": "STRIPE", "state": "needs_response", "phase": "dispute", "outcome": null, "reason": "product_not_received", "network_reason_code": "13.1", "amount": 8999, "currency": "usd", "due_by": "2026-02-03T23:59:59Z", "created_at": "2026-01-20T14:32:00Z", "resolved_at": null, "counters": [ { "counter_id": "c7b1e2d3-4a5f-4b6c-9d8e-0f1a2b3c4d5e", "state": "draft", "phase": "dispute", "revision": 3, "evidence_items": [ { "category": "shipping_tracking_number", "text": "1Z999AA10123456784", "file_ids": [] }, { "category": "shipping_documentation", "text": null, "file_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"] } ], "submitted_at": null, "submitted_by": null, "created_at": "2026-01-21T09:15:00Z", "updated_at": "2026-01-21T09:47:12Z" } ], "metadata": { "internal_case_id": "OPS-4821", "assigned_to": "ops-disputes-team" }, "evidence_requirements": { "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.", "compelling": [ { "category": "shipping_tracking_number", "label": "Shipping tracking number", "description": "Carrier tracking number showing the order was delivered to the cardholder's address.", "text": true, "file": false }, { "category": "service_documentation", "label": "Service documentation", "description": "Records showing the service was rendered, for service-based orders.", "text": true, "file": true }, { "category": "service_date", "label": "Service date", "description": "The date the service was provided.", "text": true, "file": false } ], "supporting": [ { "category": "shipping_documentation", "label": "Shipping documentation", "description": "Proof of shipment such as a carrier label or packing slip.", "text": false, "file": true }, { "category": "customer_communication", "label": "Customer communication", "description": "Emails or messages with the cardholder about the order or its delivery.", "text": true, "file": true } ], "other": [ { "category": "receipt", "label": "Receipt", "description": "The order receipt or invoice.", "text": false, "file": true }, { "category": "customer_signature", "label": "Customer signature", "description": "A signed order form or delivery receipt.", "text": false, "file": true }, { "category": "uncategorized", "label": "Additional evidence", "description": "Any other supporting evidence not covered by a specific category.", "text": true, "file": true } ] }, "payment": { "order_id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f" } } ``` ### 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](/guides/setup/api/disputes/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](/guides/setup/api/disputes/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). > **Info** > > `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 ```bash curl -s "https://dev-api.truemed.com/api/v1/disputes?state=needs_response&page_size=25" \ -H "Authorization: Bearer $TRUEMED_API_KEY" ``` ```json { "disputes": [ { "dispute_id": "d1f8c2a4-9b3e-4c17-8a2d-5e6f7a8b9c0d", "processor_dispute_id": "du_1Q9XyZ2eZvKYlo2CDeFgHiJk", "prior_dispute_id": null, "processor": "STRIPE", "state": "needs_response", "phase": "dispute", "outcome": null, "reason": "product_not_received", "network_reason_code": "13.1", "amount": 8999, "currency": "usd", "due_by": "2026-02-03T23:59:59Z", "created_at": "2026-01-20T14:32:00Z", "resolved_at": null, "counters": [], "metadata": { "internal_case_id": "OPS-4821" } }, { "dispute_id": "a2e9d1b3-7c4f-4a80-b6e1-2f3a4b5c6d7e", "processor_dispute_id": "du_1Q8WvU1dYuJXkn1BCdEfGhIj", "prior_dispute_id": null, "processor": "STRIPE", "state": "under_review", "phase": "dispute", "outcome": null, "reason": "fraudulent", "network_reason_code": "10.4", "amount": 12500, "currency": "usd", "due_by": null, "created_at": "2026-01-18T11:02:44Z", "resolved_at": null, "counters": [], "metadata": {} } ], "pagination": { "current_page": 1, "page_size": 25, "count": 2, "last_page": 1 } } ``` 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.