Table of Contents
- Key Highlights
- Introduction
- What changed and why: returns → sales_reversals
- Deprecation timeline and API versioning: what to expect
- The new returns schema: separating physical returns from order adjustments
- Mapping table: old fields and their new equivalents
- Practical migration guide: updating ShopifyQL queries
- Testing and verification: validating updated reports
- Impact on common reports and dashboards
- Edge cases: cancellations, order edits, partial returns, unverified returns
- Performance and query optimization when switching fields
- Developer and merchant best practices for migration
- Troubleshooting common issues
- Real-world examples: how merchants benefit from the change
- Resources and where to get help
- FAQ
Key Highlights
- Shopify’s GraphQL Admin API 2026-04 renames multiple analytics fields from returns-oriented names (e.g., returns, quantity_returned) to sales_reversals equivalents (e.g., sales_reversals, reversed_quantity) to reflect all order adjustments — refunds, cancellations, and edits — not only physical returns.
- Deprecated fields are removed in version 2026-07; they remain accessible via older API versions until 2027-04. Merchants and developers must update ShopifyQL queries and reporting logic now to avoid breaks.
- A new returns schema provides line-item-level physical return reporting: returned_quantity, return_line_item_reason, and is_unverified_return_line_item, enabling clear separation between physical returns and other order adjustments.
Introduction
Shopify’s 2026-04 GraphQL Admin API release revises how analytics represent order adjustments. What previously appeared under "returns" now uses names that emphasize these values are sales reversals — a collective category that includes refunds, returns, order edits, and cancellations. The change clarifies semantics in reporting and pairs with new line-item return reason fields that explicitly capture physical returns and their verification status.
This update affects any custom dashboards, BI pipelines, or ShopifyQL reports that relied on the older returns field names. The following examination explains what changed, why Shopify made the shift, how to migrate queries and dashboards, and how to validate analytics after the update. Practical migration steps, sample ShopifyQL queries, and troubleshooting guidance will help development and analytics teams maintain accurate KPIs during the transition.
What changed and why: returns → sales_reversals
The 2026-04 Admin API replaces multiple fields that used "returns" in their names with new "sales_reversals" equivalents. The functional definitions of these values have not been altered; Shopify renamed the fields to reduce confusion between broad order adjustments and the subset that are physical returns.
Why the rename? Merchants and analysts often need to separate adjustments that reverse sales (refunds, cancellations, manual edits) from physical returns where a product is sent back. Using "returns" for both concepts led to misinterpretation in reporting. The new names make it explicit that these fields capture sales reversals — systemic adjustments that decrease recognized sales — while physical return data is surfaced separately through the updated returns schema.
Core replaced fields include:
- 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
This is a rename and re-label; the calculations remain consistent with previous definitions. The updated field names provide clearer intent and align analytics with the new line-item return reporting.
Deprecation timeline and API versioning: what to expect
Shopify’s API version lifecycle determines when deprecated fields stop working. For these renamed fields, the timeline is:
- 2026-04: New field names introduced (sales_reversals and others). Deprecated fields are marked but still present in that release.
- 2026-07: Deprecated fields removed from the 2026-07 API version. Any clients pinned to that or later versions will no longer find the old field names.
- Until 2027-04: Deprecated fields remain accessible through older API versions. If a store or app continues to call an older Admin API version, the legacy field names will function until that cutoff.
Operational implications:
- If your app or reporting stack specifies a static API version earlier than 2026-07, old field names will continue to work until 2027-04, giving a temporary runway.
- Apps and integrations set to auto-upgrade to the latest API version or explicitly using 2026-07 or later will encounter missing fields unless queries are updated.
Action window and recommended schedule:
- Immediate: Inventory where your ShopifyQL reports and GraphQL queries reference deprecated field names. Prioritize reports that are surfaced to finance, operations, and marketplaces.
- Short term (weeks): Update queries and dashboards to use sales_reversals and reversed_quantity. Update test suites to assert on the new field names.
- By 2026-07: Deploy updates to any services using API version 2026-07 or later.
- By 2027-04: Finish rollouts for clients that remain on older API versions, as Shopify will remove deprecated field support entirely.
The new returns schema: separating physical returns from order adjustments
Alongside renames, Shopify introduced explicit line-item fields to record physical returns and their reasons. These help analysts answer questions such as how many items were physically sent back, why they were returned, and whether the return was verified.
New line-item fields include:
- returned_quantity — physical quantity returned at the line-item level.
- return_line_item_reason — categorical reason for the physical return (e.g., damaged, incorrect item, buyer remorse).
- is_unverified_return_line_item — flag denoting if the returned item is unverified (useful where return verification processes exist).
Why this matters:
- Earlier, "returns" conflated several types of changes. Now, analytics teams can directly attribute inventory and reverse logistics to physical return quantities.
- Business rules that adjust inventory, issue restocking fees, or reconcile with third-party logistics can read returned_quantity; financial reversals continue to route to sales_reversals.
Real-world scenario: A merchant receives a refund for an order that was canceled before fulfillment. Previously, an analyst viewing a returns metric might treat that as a physical return and reconcile inventory incorrectly. With sales_reversals and returned_quantity separated, the cancellation will show up as a sales reversal, while returned_quantity remains zero — eliminating inventory misstatements.
Mapping table: old fields and their new equivalents
Use this mapping when updating queries and dashboards. The semantics match existing definitions — only the names changed.
| 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 |
Apply this mapping systematically across ShopifyQL queries, BI extracts, and any stored procedures that reference old field names.
Practical migration guide: updating ShopifyQL queries
This section provides concrete examples showing how to change ShopifyQL queries from the old field names to the new ones, and how to leverage the new returns schema for line-item-level analysis.
Basic aggregate: total reversals by day
Before (deprecated field usage)
SELECT
date,
SUM(returns) AS total_returns,
SUM(quantity_returned) AS quantity_returned
FROM orders
GROUP BY date
ORDER BY date ASC
After (use sales_reversals and reversed_quantity)
SELECT
date,
SUM(sales_reversals) AS total_sales_reversals,
SUM(reversed_quantity) AS reversed_quantity
FROM orders
GROUP BY date
ORDER BY date ASC
Querying physical returned quantities and reasons by SKU (returns schema)
SELECT
line_item.sku AS sku,
SUM(line_item.returned_quantity) AS total_returned_quantity,
line_item.return_line_item_reason AS return_reason
FROM orders
WHERE line_item.returned_quantity > 0
GROUP BY sku, return_reason
ORDER BY total_returned_quantity DESC
LIMIT 50
Identifying unverified returns
SELECT
line_item.sku,
SUM(line_item.returned_quantity) AS qty_returned,
SUM(CASE WHEN line_item.is_unverified_return_line_item THEN line_item.returned_quantity ELSE 0 END) AS unverified_qty
FROM orders
WHERE line_item.returned_quantity > 0
GROUP BY sku
ORDER BY qty_returned DESC
Reconciliation example: sales less reversals equals net sales
SELECT
date,
SUM(gross_sales) AS gross_sales,
SUM(sales_reversals) AS sales_reversals,
SUM(gross_sales) - SUM(sales_reversals) AS net_sales
FROM orders
GROUP BY date
Notes on schema paths:
- In ShopifyQL, line-item fields are typically accessed through a nested path such as line_item.returned_quantity. Verify your analytics platform supports nested attribute aggregation; some BI tools require flattening the schema before aggregation.
Testing before/after:
- Run both versions of a query in parallel (old fields against an older API version if available, new fields against 2026-04 or later) and compare totals over a representative period (e.g., 90 days).
- Confirm that the sum of sales_reversals matches the previous returns metric for gross, net, and total representations where appropriate.
Testing and verification: validating updated reports
Updating queries is not enough. Reconciliation tests and regression checks prevent reporting regressions that could affect finance, operations, and executive dashboards.
Suggested testing checklist:
- Baseline comparison: Run existing reports against the legacy fields (if still available via an older API version) and the updated reports simultaneously for a 30–90 day window. Confirm numerical parity where fields are semantically equivalent.
- Line-item verification: For a sample set of orders involving returns, refunds, cancellations, and edits, verify that returned_quantity is only populated for physical returns while sales_reversals reflects any transaction-level adjustments.
- Inventory reconciliation: Check that inventory reductions and restocking actions correlate with line_item.returned_quantity values rather than sales_reversals, unless reconciled per business rules.
- Financial close tests: Confirm month-end metrics (gross sales, net sales, taxes, shipping, discounts) reconcile when substituting renamed fields. A mismatch often points to residual logic referencing deprecated names.
- Edge-case simulation: Create orders with partial refunds, partial returns, and order edits. Observe how each scenario maps to sales_reversals and returned_quantity.
- Dashboard smoke tests: Verify charts, filters, and slicers that referenced old field names do not show empty values or errors. Ensure calculated fields referencing old names are updated.
Automating tests:
- Add unit tests in your ETL pipeline to assert the presence of new fields and their non-nullability where applicable.
- Add integration tests that perform a sample API call, then assert that sums of new fields match expected calculations for seeded test orders.
Impact on common reports and dashboards
Most out-of-the-box Shopify reports will align as Shopify updates its own dashboards. The primary impact lands on custom analytics and external BI systems.
Sales and revenue dashboards:
- Net sales metrics should subtract sales_reversals rather than returns if the dashboard previously double-counted physical returns and other adjustments.
- Tax and shipping reversals are now explicitly tax_reversals and shipping_reversals; update tax and shipping adjustment lines to pull from those fields.
Return rate calculations:
- Two return rates are now important to distinguish:
- Reversal rate: reversed_quantity / quantity_sold — reflects all adjustments reducing sales.
- Physical return rate: returned_quantity / quantity_shipped — reflects items physically sent back.
- For clarity, label these metrics in dashboards accordingly: "Sales Reversal Rate" vs "Physical Return Rate."
Inventory and logistics:
- Use line_item.returned_quantity to drive restocking workflows, return authorizations, and RMA counts.
- Use is_unverified_return_line_item to trigger manual inspection workflows if returns need verification before restocking.
Finance and accounting:
- Reconciliation between ledgers and sales data should use sales_reversals for adjusting revenue entries.
- Physical returns that entail inventory changes might require cost of goods sold (COGS) journal entries; use returned_quantity for inventory valuation adjustments.
Marketplace and channel reporting:
- If you export Shopify analytics to marketplaces or marketplaces pull data, confirm field-name mappings in their ingestion scripts.
- Multi-channel sellers should ensure unified definitions across channels: what one system labels a "return" may be a sales reversal in Shopify.
Edge cases: cancellations, order edits, partial returns, unverified returns
Understanding how each scenario maps to sales_reversals and returned_quantity prevents misinterpretation.
Cancellations before fulfillment:
- No physical item was shipped. Shopify records an order adjustment that reduces sales; this maps to sales_reversals. returned_quantity is zero.
- Inventory never increased, so restocking logic should not trigger.
Partial refunds without return:
- Merchant issues a refund for a discount or customer service gesture without item return. This is a sales reversal. Inventory remains unchanged.
Partial returns with refund:
- Customer ships back some items. returned_quantity populates for returned line items. The refund amount and tax/shipping adjustments are captured under sales_reversals and detail lines like discount_reversals.
Order edits (price or quantity adjustments):
- If an order is edited after fulfillment and results in adjustments, these appear as sales_reversals if they reduce recognized sales. returned_quantity may be zero if no item returned.
Unverified returns:
- When a return is recorded in Shopify but not yet verified by the merchant or warehouse, is_unverified_return_line_item = true. Use this flag to delay restocking and accounting until verification completes.
Chargebacks:
- Chargebacks initiated by payment providers reverse revenue; these are sales_reversals. They frequently have downstream impacts such as fees and dispute processing, separate from physical returns.
Third-party fulfillment (3PL) anomalies:
- If a 3PL marks goods as returned in their system, but the merchant’s Shopify returned_quantity does not reflect it (or vice versa), reconcile using line-item return reasons and timestamps.
Performance and query optimization when switching fields
Large catalogs and order volumes can make analytic queries expensive. Updating fields presents an opportunity to optimize queries.
Indexing and materialization:
- If your analytics stack supports materialized views or pre-aggregations, incorporate sales_reversals and returned_quantity into those pre-aggregations to reduce query time for dashboards.
- Daily aggregates on date, SKU, and fulfillment status provide efficient lookups for most reporting needs.
Filter pushdown:
- Filter early on line_item.returned_quantity > 0 to limit row expansion when joining orders with line items.
- Aggregate at the line-item level before joining to order-level tables to prevent unnecessary cartesian growth.
Batching and pagination:
- For ETL that pulls historical data, request ranges by date and use pagination to avoid timeouts. Use incremental loads that capture only modified orders (updated_at) rather than full extracts.
Simplifying nested data:
- Consider flattening nested order-line structures in your data warehouse into a normalized line-item table. This avoids repeated nested aggregations in dashboards.
Cost considerations:
- Frequent, broad queries against the Admin API can be rate-limited. Migrate heavy historical analytics to your data warehouse and schedule regular delta syncs.
Developer and merchant best practices for migration
A structured migration reduces downtime and prevents reporting errors.
Migration checklist
- Audit: Inventory all queries, dashboards, stored procedures, ETL pipelines, and scripts referencing deprecated field names.
- Mapping: Apply the mapping table to generate a change list for query updates.
- Update: Change queries to use new field names. Where necessary, introduce returned_quantity line-item logic for physical returns.
- Parallel testing: Run updated and legacy queries in parallel for a meaningful test window. Compare results and investigate discrepancies.
- Automate tests: Add regression checks to CI for analytics pipelines; assert on sums, rejections, and presence of new fields.
- Rollout: Deploy updated code to production services before 2026-07 if they will be upgraded to API versions that remove deprecated fields.
- Monitor: After deployment, monitor dashboards for anomalies and set alerting on unexpected deltas in key metrics.
- Documentation: Update internal docs and data dictionaries to reflect new field names and definitions.
- Train stakeholders: Notify teams (finance, operations, customer service) about the semantic differences and new metrics (sales_reversals vs physical returns).
- Cleanup: Remove any legacy fallback code once deprecated fields are no longer accessible.
Communication strategy
- Notify internal stakeholders 4–6 weeks before cutover. Provide examples of how metrics will appear after migration.
- For customer-facing apps, communicate breaking changes in release notes and provide an upgrade guide with code samples.
- Where possible, maintain backward compatibility in public apps by reading both field names and prioritizing the new ones while warning downstream users in logs.
Sample commit-level change
- Update queries in one repository commit per report category (finance, inventory, customer service) to simplify rollbacks.
- Provide a migration script or linter rule that flags deprecated field names in code reviews.
Troubleshooting common issues
If updated queries produce unexpected results, follow a structured troubleshooting approach.
Symptom: Dashboard shows zeros or errors after code change
- Cause: Updated query references new fields, but deployed API version is older and still uses legacy field names or vice versa.
- Remedy: Verify the Admin API version to which the app or integration is pinned. If API version is 2026-07 or later, ensure only new field names are used. If pinned to older version, consider temporary dual-read logic during the migration window.
Symptom: Totals disagree between legacy and new queries
- Cause: The legacy returns metric mixed sales reversals and some line-item counts; new metrics separate them.
- Remedy: Break down sample orders and ensure sums of sales_reversals align with legacy returns. Investigate whether legacy totals included line-item counts that are now in returned_quantity.
Symptom: Inventory inconsistencies after migration
- Cause: Inventory automation updated based on returns metric that previously conflated adjustments and physical returns.
- Remedy: Rewire inventory workflows to use returned_quantity for restocking. Reconcile any incorrect restocking events by comparing warehouse records.
Symptom: Unexpected taxes or shipping reconciliation differences
- Cause: New fields tax_reversals and shipping_reversals must be used to compute net tax/shipping amounts; older dashboards might still subtract discounts_returned type fields.
- Remedy: Update tax and shipping calculations to reference their respective reversal fields.
Debugging tips:
- Pull detailed order-level records for sample transactions that cause discrepancies. Inspect the timeline of events: order created → fulfilled → return/refund → edit.
- Validate with the Shopify Admin UI: inspect the order’s history to understand whether the change was a refund, cancellation, or physical return.
- Use the returns schema fields to determine if returned_quantity was non-zero; line-item reasons and verification flags often explain unexpected states.
Real-world examples: how merchants benefit from the change
Example 1 — Apparel retailer with high return volumes A direct-to-consumer clothing brand experienced confusion between canceled orders and returned items. After switching to sales_reversals for revenue adjustments and using returned_quantity for restocking, their finance team reconciled monthly revenue faster and reduced inventory misstatements. Returns that were only refunds no longer triggered reverse logistics.
Example 2 — Electronics seller using third-party refurbishment A merchant with a refurbishment partner needed to track physical returns separately for quality inspection. Using return_line_item_reason and is_unverified_return_line_item, the seller directed unverified returns to an inspection queue and verified returns directly to the refurb pipeline, improving throughput and reducing time to resale.
Example 3 — Marketplace integrator and aggregated reporting A SaaS analytics provider that aggregates multi-store data updated its ingestion pipeline to use sales_reversals for adjustments and returned_quantity for warehouse correlation. Post-migration, their "return rate" KPI split into reversal and physical return rates, giving clients clearer signals for customer behavior versus process failures.
Resources and where to get help
- Shopify developer documentation for ShopifyQL and the Admin API provides the canonical schema references and examples.
- If your app is on Shopify’s App Store, consult app review and migration guides for API changes.
- For complex migrations, engage data engineering or BI consultants experienced with Shopify data models and ETL pipelines.
FAQ
Q: Will the old "returns" fields still work after 2026-07? A: Deprecated fields are removed in version 2026-07. They will remain accessible for clients using older API versions until 2027-04, but any app or integration using 2026-07 or later must use the new field names.
Q: Do sales_reversals include physical returns? A: Yes. sales_reversals is a broad category capturing all order adjustments that reverse sales, including refunds, cancellations, order edits, and physical returns. Physical return quantities are recorded separately at the line-item level as returned_quantity.
Q: How should I calculate a true physical return rate? A: Use line_item.returned_quantity aggregated against quantity_shipped or quantity_fulfilled, depending on your business rule. Label the metric "Physical Return Rate" and avoid mixing it with sales_reversal-based rates.
Q: What is reversed_quantity vs returned_quantity? A: reversed_quantity is the renamed aggregate field formerly known as quantity_returned and represents quantity reversed as part of sales adjustments. returned_quantity is a line-item field that explicitly records the physical quantity returned for that line item.
Q: How do I update legacy reports quickly across many dashboards? A: Automate the update: search your codebase for deprecated field names and apply the mapping table programmatically. Run parallel queries for a verification window and deploy changes in defined stages (finance, operations, customer-facing dashboards).
Q: Should I change inventory automation now? A: Yes. Inventory automation should rely on returned_quantity for restocking logic, because sales_reversals may include non-physical adjustments that should not affect inventory counts.
Q: What if my third-party analytics tool doesn’t support nested line-item fields? A: Flatten the nested data during ETL into a line-item table in your warehouse, then aggregate returned_quantity per SKU or order as needed. Alternatively, use the platform’s flattening/unnesting functionality when available.
Q: How can I tell if a return is verified? A: The field is_unverified_return_line_item flags unverified returns. Use it to drive inspection workflows and to exclude unverified returns from immediate restocking or resale calculations.
Q: Do I need to change webhooks or GraphQL queries beyond ShopifyQL? A: Yes. Any direct GraphQL queries or analytics calls that reference deprecated field names should be updated. Review webhooks and any processing logic that inspects order modification payloads.
Q: Where can I see examples and further documentation? A: Consult Shopify’s official docs for ShopifyQL and the Admin API. The release notes for version 2026-04 detail these field changes, and the help center explains standard reports and their updated fields.
If you need assistance mapping a large set of queries or producing a migration plan tailored to your data architecture, provide details on your current pipelines (tools, API versions, ETL cadence), and a prioritized list of dashboards.
