Retrieve a Shopify Payments dispute and submit evidence to contest a chargeback using the Admin GraphQL API

In-depth guide

Steps

1. Query `disputes(first: 10)` or `dispute(id: $disputeId)` — these return `ShopifyPaymentsDispute` objects with fields including `id`, `amount`, `currencyCode`, `reasonMessage`, `status`, `evidenceDueBy`, `evidenceSentOn`, and `finalizedOn`
2. Inspect `dispute.reason` (a `ShopifyPaymentsDisputeReason` enum such as `FRAUDULENT`, `UNRECOGNIZED`, or `PRODUCT_NOT_RECEIVED`) to determine the type of evidence to gather
3. 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`)
4. Upload supporting documents (shipping labels, invoices, communication screenshots) using `stagedUploadsCreate` and obtain their file GIDs
5. 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`
6. After submission, query the dispute again and confirm `evidence.submittedByMerchantOn` is set, indicating Shopify has received and forwarded the evidence to the card network