Technical integrations
Query Shopify Payments Disputes With GraphQL: A Monitoring-Only Example
A monitoring-only Shopify Payments query should retrieve operational case information and leave response actions outside the integration. Start with the dispute identifier, status, type, amount, currency, reason and evidence deadline. Preserve missing values and API errors instead of turning them into reassuring defaults.
The illustrative example below targets Admin GraphQL API version 2026-07, the stable documentation version reviewed on 6 September 2026. It has not been executed against a live Shopify store. Validate it with your authorized app, granted permissions and chosen version before production use.
Choose the smallest useful read
Shopify documents the disputes query and the ShopifyPaymentsDispute fields. The query requires the appropriate dispute read access; it should not request evidence-writing authority for a monitoring purpose.
query MonitorDisputes($first: Int!) {
disputes(first: $first) {
nodes {
id
status
type
amount { amount currencyCode }
reasonDetails { reason networkReasonCode }
evidenceDueBy
initiatedAt
}
pageInfo { hasNextPage endCursor }
}
}
Use a small explicit variable such as {"first": 25} for the first authorized check. This example reads one page and reports whether more data exists; it is not a complete historical import. A production traversal needs the cursor handling described in the dedicated pagination guide.
The reason is nested under reasonDetails, rather than a guessed top-level field. The reason-details reference defines the standardized reason and optional network code. Preserve both when the network code is useful to your operators.
Send the request through the authorized installation
Send the GraphQL document and variables to the store's versioned Admin API endpoint, using the access token belonging to that installation. Keep the token in the server-side credential store. Do not put it in browser code, source control or a case export.
Resolve the shop identity from your authenticated installation record. Do not accept an arbitrary shop host from an untrusted request and attach a stored token to it. A monitoring endpoint should know which merchant relationship it is serving before it makes the API call.
Record the requested API version and the version returned in Shopify's response headers. This helps identify compatibility problems if the service responds under a different supported version.
Log a request identifier, operation name and safe error classification. Avoid logging complete response bodies by default. Operational dispute monitoring does not require copying all available customer context into infrastructure logs.
Interpret the response without losing meaning
A successful HTTP response does not guarantee a successful GraphQL operation. Inspect the GraphQL errors collection and the expected data path before treating the result as current.
Use a conservative first implementation: if the operation contains errors affecting the requested monitoring fields, preserve the last successful record and mark the refresh as failed. More advanced partial-data handling can be added only when it distinguishes precisely which fields remain reliable.
| Response condition | Display or storage decision |
|---|---|
| Valid case and deadline | Store the source timestamp and display it with a zone |
| Deadline is null | Show that no deadline value was supplied |
| Empty valid connection | Record a successful read with no cases on this page |
| Access or schema error | Mark synchronization unavailable; do not show zero cases |
| More pages exist | Label the current result incomplete until traversal finishes |
Keep money as a decimal value paired with currency. Do not combine different currencies into one amount or use floating-point arithmetic for financial comparisons without an appropriate decimal strategy.
Build a useful local case record
Use the installation identity and Shopify dispute ID as the stable operational key. Store status, type, reason, amount, currency and deadline separately, along with the time of the last successful observation.
The observation time is your integration's metadata. It is not a Shopify case-change timestamp, and it should not be presented as one. That distinction becomes important when investigating stale data.
A hypothetical record might contain a $125 dispute with a supplied deadline and a known reason. If the next request fails, the application should retain the $125 case and show its previous observation time. Deleting it or resetting the deadline because the refresh failed would misrepresent the source.
Do not add a response-complete flag merely because the record was read. Monitoring and merchant action are separate events.
Verify the read before relying on it
Compare a few authorized cases with Shopify Admin. Include an open case, a finalized case if available and a case without a supplied deadline. Check identity, amount, currency, reason and status rather than only the total number of rows.
Exercise a denied permission and a malformed query in a suitable development environment. The meaningful result is a visible access or compatibility failure, with prior valid data preserved and no false “all clear” state.
Finally, confirm that no mutation or unnecessary evidence field is part of the operation. A good monitoring read is small enough to understand, honest about missing information and traceable to the authorized merchant source. That gives the team a dependable starting point for a focused dispute interface.
Explore the dispute status and deadline information shown in Lower Chargeback.
Related reading in this collection:
- Shopify Dispute Monitoring Permissions: Request Only the Scopes You Need
- Paginate Shopify Payments Disputes Without Skipping Cases