Query `disputes(first: 10)` or `dispute(id: $disputeId)` — these return `ShopifyPaymentsDispute` objects with fields including `id`, `amount`, `currencyCode`, `reasonMessage`, `status`, `evidenceDueBy`, `evidenceSentOn`, and `finalizedOn`
Inspect `dispute.reason` (a `ShopifyPaymentsDisputeReason` enum such as `FRAUDULENT`, `UNRECOGNIZED`, or `PRODUCT_NOT_RECEIVED`) to determine the type of evidence to gather
Retrieve the dispute's `evidence` field — a `ShopifyPaymentsDisputeEvidence` object — to see any previously submitted evidence and the available evidence fields (e.g., `customerPurchaseIp`, `shippingDocumentation`, `cancellationRebuttal`)
Upload supporting documents (shipping labels, invoices, communication screenshots) using `stagedUploadsCreate` and obtain their file GIDs
Call `disputeEvidenceUpdate(id: $disputeId, disputeEvidence: { shippingDocumentation: $fileGid, customerPurchaseIp: "203.0.113.5", accessActivityLog: "Customer accessed account on...", submitEvidence: true })` to submit evidence — set `submitEvidence: true` to finalize submission before `evidenceDueBy`
After submission, query the dispute again and confirm `evidence.submittedByMerchantOn` is set, indicating Shopify has received and forwarded the evidence to the card network
Known gotchas
The `disputes` query and `disputeEvidenceUpdate` mutation require the `shopify_payments_payouts` or `shopify_payments` access scope — standard order/payment scopes do not grant access to dispute data
Setting `submitEvidence: false` in disputeEvidenceUpdate saves a draft without submitting — only calls with `submitEvidence: true` send the evidence to the card network; missing the `evidenceDueBy` deadline forfeits the dispute automatically
The REST Admin API dispute endpoints are legacy as of October 2024 and new apps must use the GraphQL Admin API; the GraphQL `dispute` query and `disputeEvidenceUpdate` mutation are the current supported path
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp