Get a free Shopify store audit

Shopify's New Return Shipping Tax Fields, Explained

Starting October 23, Shopify taxes US return shipping fees. Here's the estimated-vs-finalized field pair your reconciliation logic needs.

Shopify's New Return Shipping Tax Fields, Explained — ASSOSIATIX Journal

As of API version 2026-10, Shopify's GraphQL Admin API exposes the tax it calculates on a return's shipping fee. The change isn't cosmetic: starting October 23, 2026, Shopify begins actually charging that tax — on orders shipped to US addresses, for stores using Shopify Tax or Tax Platform — treating return shipping like any other shipping charge. Existing shipping-tax settings carry over: if a state has shipping marked untaxed, return shipping in that state stays untaxed too. Any integration that reconciles refunds, syncs returns to an ERP, or reports on return costs now has a new number to account for, and it arrives through two distinct fields at two distinct points in a return's lifecycle.

The Estimate: taxAmountSet

taxAmountSet is a non-null MoneyBag field on CalculatedReturnShippingFee, available from the returnCalculate query, which requires the read_returns or read_marketplace_returns access scope. It's populated before a return is even created — returnCalculate previews the financial outcome of a return, including this fee, without creating anything. It returns zero when no tax applies to the fee. This is the number to show a customer or a support agent when a return is first being set up: an estimate, not a final figure.

The Final Number: finalizedTaxAmountSet

finalizedTaxAmountSet lives on ReturnShippingFee and is nullable — it returns null until the return is actually processed through the returnProcess mutation, which requires the write_returns or write_marketplace_returns access scope, and it returns zero if no tax applied. Shopify's own documentation is explicit that this value can differ from the estimate in taxAmountSet, because the tax provider can return a different amount at the time the return is processed rather than when it was first calculated.

Why Both Reads Matter

For reconciliation logic, treating these two fields as interchangeable — or reading only the estimate — will misstate a refund or a tax report whenever the provider's finalized number diverges from the preview. The correct pattern is to read taxAmountSet for a pre-return preview, then re-read finalizedTaxAmountSet once returnProcess completes, and use that second value as the source of truth for anything downstream: ERP sync, refund totals, tax filings. Shopify's own guidance to merchants carries the same caution integrators should take from it: anyone running a manual workaround today to calculate, collect, import, or reconcile tax on return shipping should review that logic before October 23 to avoid double-counting tax once Shopify starts doing it automatically.

Sources

Tell us what you're building.

Share a few details and we'll reply within 1–2 business days with questions, a scope and a quote.