---
title: >-
  ShopifyQL returns fields deprecated and replaced with sales reversals fields -
  Shopify developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/posts/shopifyql-returns-fields-deprecated-and-replaced-with-sales-reversals-fields
  md: >-
    https://shopify.dev/changelog/posts/shopifyql-returns-fields-deprecated-and-replaced-with-sales-reversals-fields.md
metadata:
  effectiveApiVersion: 2026-04
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: Deprecation announcement
    handle: deprecation-announcement
  indicatesActionRequired: true
  createdAt: '2026-03-03T13:57:12-05:00'
  postedAt: '2026-03-13T20:30:00-04:00'
  updatedAt: '2026-09-28T09:53:02-04:00'
  effectiveAt: '2026-03-05T12:00:00-05:00'
---

March 14, 2026

# ShopifyQL returns fields deprecated and replaced with sales reversals fields

DateMarch 14, 2026

Version[2026-04](https://shopify.dev/changelog?api_version=2026-04)

Flags[Deprecation announcement](https://shopify.dev/changelog?filter=deprecation-announcement)[Action required](https://shopify.dev/changelog?action_required=true)

SurfacesAPI

Affected APIs[Admin GraphQL API](https://shopify.dev/changelog?api_type=admin-graphql)

In GraphQL Admin API version `2026-04`, several Returns fields in analytics, which can be queried through [ShopifyQL](https://shopify.dev/docs/api/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_sales_reversal` |
| `order_or_return` | `order_or_sales_reversal` |

[Learn more about the updated fields.](https://help.shopify.com/en/manual/reports-and-analytics/shopify-reports/report-types/default-reports/sales-report), and about [ShopifyQL](https://shopify.dev/docs/api/shopifyql).