ShopifyQL returns fields deprecated and replaced with sales reversals fields

In GraphQL Admin API version 2026-04, several Returns fields in analytics, which can be queried through ShopifyQL, have been deprecated and replaced with renamed versions (e.g., sales_reversals, reversed_quantity) to better reflect that they capture all order adjustments, including refunds, returns, order edits, and cancellations. The definitions remain unchanged.

Deprecation timeline

Deprecated fields will be removed in version 2026-07, but will still be accessible via older API versions until 2027-04.

Why we did this

The new field names clarify the difference between broad order adjustments (sales reversals) and physical returns. With the launch of return reason reporting, you can now see physical quantities returned and their reasons at the line item level, separate from overall order adjustments. Access these details in the returns schema using returned_quantity, return_line_item_reason, and is_unverified_return_line_item.

What you need to do

Update your ShopifyQL queries to use the new sales_reversals and reversed_quantity fields (see mapping table below)

Deprecated field	New replacement field
`returns`	`sales_reversals`
`net_returns`	`net_sales_reversals`
`gross_returns`	`gross_sales_reversals`
`total_returns`	`total_sales_reversals`
`discounts_returned`	`discount_reversals`
`shipping_returned`	`shipping_reversals`
`taxes_returned`	`tax_reversals`
`quantity_returned`	`reversed_quantity`
`returned_quantity_rate`	`reversed_quantity_rate`
`is_return_related`	`is_reversal`
`order_or_return`	`order_or_sales_reversal`

Learn more about the updated fields., and about ShopifyQL.

Was this section helpful?