Executive summary
- What: The shopifyqlQuery query in the GraphQL Admin API returns a new parseWarnings field on ShopifyqlQueryResponse, starting with version 2026-10.
- Why: Warnings expose non-fatal problems, including fields scheduled for deprecation, on queries that ran successfully, giving teams advance notice before a future version breaks them.
- Who: Anyone running ShopifyQL behind custom dashboards, scheduled exports, or embedded reporting in an app.
What changed
shopifyqlQuery now returns parseWarnings alongside your results. The field is always present: it holds a list of warning messages when a successful query has non-fatal issues, and an empty list when there are none. That consistency matters, because it means you can read the field unconditionally rather than guarding for its absence.
The distinction from parseErrors is worth being precise about. parseErrors explain why a query failed to run and arrive instead of table data. parseWarnings arrive together with tableData on queries that ran fine. A warning never blocks execution and never changes your results. It tells you that something in the query is heading for trouble. Reading the field requires the read_reports scope, and queries touching customer fields still fall under Shopify's protected customer data requirements.
Why it matters
Reporting breakage has an awkward shape in enterprise environments. A ShopifyQL query referencing a field that is quietly on its way out keeps returning correct numbers right up until the version where it does not, at which point a dashboard goes blank or a scheduled export fails. The failure almost never happens at a convenient time, because version upgrades tend to be scheduled around other work and reporting is validated last.
parseWarnings converts that from a surprise into a backlog item. If your reporting layer logs warnings, you accumulate a list of queries needing attention weeks or months before any of them break, and you can fix them during normal maintenance rather than during an incident. The cost of adoption is one field in your selection set and a few lines of logging, which is an unusually good trade.
The practical move is to treat warnings as monitoring output, not as something a human reads once. Teams already instrumenting their Shopify analytics workflows will find this slots into existing logging with little effort.
Role-specific impact
- Marketers: Fewer dashboards breaking without warning during a platform upgrade, which means campaign and revenue reporting stays available through version changes.
- Developers: Add parseWarnings to your selection set and check it after a successful query exactly as you already check parseErrors. Log warnings with the originating query text so the source is identifiable later.
- Store admins: Advance notice that a saved report or export is on borrowed time, instead of a blank panel discovered during a review.
Use-case example
Real-world scenario
A multi-brand retailer on Shopify Plus runs about 60 scheduled reports built on ShopifyQL, feeding a warehouse that powers weekly merchandising reviews and a monthly board pack. During a previous API version upgrade, four queries referencing a retired field began failing, and nobody noticed until the board pack was assembled three weeks later with two revenue panels missing. Reconstructing the figures took roughly 11 hours across two analysts. After adopting parseWarnings, the reporting service now logs every warning with its query identifier to the same channel used for job failures. The first week surfaced nine queries carrying deprecation warnings, all of which were repaired during ordinary sprint work with no reporting outage.
Implementation checklist
- Move the service that issues shopifyqlQuery calls to API version 2026-10.
- Add parseWarnings to the selection set everywhere you currently select parseErrors.
- Confirm the calling app holds read_reports, and review protected customer data requirements if your queries touch customer fields.
- Log each warning together with the query identifier or query text, so you can trace a warning back to the report that produced it.
- Route warnings to the same place you already send job failures, at a lower severity, so they are visible without paging anyone.
- Treat an empty list as the healthy state and avoid writing null checks the field does not need.
- Review accumulated warnings on a regular cadence and schedule fixes before your next version upgrade.
FAQ
Q: Do warnings mean our query results are wrong?
A: No. Warnings are returned only on queries that ran successfully, and the table data is unaffected. They flag issues that could matter in a future API version.
Q: Is this a breaking change?
A: No. The field is additive. Existing queries continue to work unchanged, and you adopt parseWarnings when you want the early notice.
Resources
shopifyqlQuery query reference
Need guidance? Talk to Makro.