ShopifyQL parseWarnings: What It Returns and What to Add

Starting with API version 2026-10, a ShopifyQL query that succeeds can also return non-fatal warnings. Shopify’s parseWarnings changelog adds a parseWarnings field to ShopifyqlQueryResponse, the object that the GraphQL Admin API query shopifyqlQuery returns. It carries problems such as a field scheduled for deprecation, while the query still returns its rows. If your app reads store reports through ShopifyQL, adopting it is one field in your selection set and a few lines in your handler.

What ShopifyQL parseWarnings returns

Shopify describes the field in one sentence worth quoting in full: “The field is always present: it returns a list of warning messages when a successful query has non-fatal issues, and an empty list when there are none.” That gives you a simple reading rule. An empty list means Shopify reported no non-fatal issues for that query; a non-empty list means it found one or more, such as a field scheduled for deprecation, that could affect the query in a future API version.

Warnings never stop a query from running. They exist so you can act before a later version changes the query’s behaviour. Watching them helps saved reports keep working across version upgrades.

How is parseWarnings different from parseErrors?

The two fields answer different questions. parseErrors explains why a query failed to run, and according to the shopifyqlQuery reference, when a query has a syntax error the response carries those messages instead of table data. parseWarnings only comes back on queries that did run, next to the tableData result set.

What to add to your ShopifyQL queries

Add parseWarnings to every shopifyqlQuery selection set, next to parseErrors, and read it after a successful query the same way you already read parseErrors. This is the example from the changelog. Keep your own query string and copy only the fields:

query {
  shopifyqlQuery(query: "FROM sales SHOW total_sales SINCE -7d") {
    tableData { columns { name } rows }
    parseWarnings
    parseErrors
  }
}

In that example, parseWarnings holds any non-fatal warnings for the query, or an empty list when there are none.

On the handling side the order matters: stop on errors, record warnings, then use the rows. Here is a sketch of that order in JavaScript. It is our example, not Shopify’s, and result is the shopifyqlQuery object from the parsed response:

function handleShopifyqlResult(result, queryText, log) {
  if (result.parseErrors?.length) {
    throw new Error("ShopifyQL query failed: " + queryText + " " + JSON.stringify(result.parseErrors));
  }
  for (const warning of result.parseWarnings ?? []) {
    log.warn({ query: queryText, warning });
  }
  return result.tableData;
}

Log the query text with each warning, because the documentation does not say whether a warning message identifies the query that produced it.

Rolling it out across your reports

1. Set your app’s Admin API version to 2026-10, the version that introduces the field (see Shopify’s API versioning documentation).
2. Add parseWarnings next to parseErrors in every shopifyqlQuery selection.
3. Log each warning with the query that produced it, and never fail a job on warnings alone.
4. Before each API version upgrade, group the logged warnings by query and fix what each one reports.

If you already make Admin API calls in production, put this in the same client code that handles throttling and retries. Our guide to GraphQL Admin API rate limits in production covers throttling and retry handling in that client code. For logging failures in other Shopify integrations, see our write-up of Shopify webhook retry failures.

Access the query needs

The changelog does not change who can call the query. According to the shopifyqlQuery reference, it needs the read_reports access scope and Level 2 access to protected customer data, which covers name, address, phone and email fields. The changelog does not mention any change to those requirements, so nothing in it suggests an app that already runs ShopifyQL queries needs a new approval to read warnings.

What the source leaves undocumented

The changelog says the field is always present, and also that warnings are only returned on queries that ran successfully. It does not say what parseWarnings holds when parseErrors is not empty, so treat it as empty or missing in that branch, as the sketch above does with ?? []. It also does not describe the wording or structure of a warning message, or whether the list has a fixed order. Store each warning as it arrives, and avoid alerting on its exact text until the ShopifyqlQueryResponse reference documents it.

Where to start this week

Add parseWarnings to the saved report query your team relies on most, run it once, and fix whatever a warning reports. Then repeat for the remaining queries before your next API version upgrade, so a deprecation does not catch a report out in a later version. If you would rather hand the reporting integration to a team that maintains Admin API clients day to day, see our Shopify development services.