Executive summary
- What changed: API version 2026-10 adds two tax fields for return shipping fees: CalculatedReturnShippingFee.taxAmountSet for the estimate during drafting, and ReturnShippingFee.finalizedTaxAmountSet for the tax actually charged at processing.
- Why it happened: From October 23, 2026, Shopify calculates tax on return shipping fees for orders shipped to US addresses on stores using Shopify Tax or Tax Platform. The API needed to expose both the estimate and the settled figure.
- Who should care: Finance and operations teams at US-shipping merchants, plus anyone maintaining an ERP, accounting, or returns integration that reads return totals.
What changed
The distinction between the two fields is the whole point. taxAmountSet sits on CalculatedReturnShippingFee, available through the returnCalculate query. It is an estimate, a MoneyBag in shop and presentment currencies, and resolves to zero when no tax applies. finalizedTaxAmountSet sits on ReturnShippingFee and stays null until the return is processed through returnProcess, where it locks in what the tax provider actually charged.
The two figures can differ, and Shopify is explicit that the provider may return a different amount at processing than at calculation. Use the estimate for anything a buyer sees while the return is created, and the finalized value for anything touching the ledger. Existing shipping tax configuration still applies, so if shipping is untaxed in a state, return shipping fees there remain untaxed.
Why it matters
Most merchants charging return shipping fees have been under-collecting tax on them, and many built a manual workaround: a spreadsheet adjustment, an imported journal entry, a periodic correction from finance. Those workarounds are now a liability. After October 23 Shopify collects the tax and pushes it into tax reports automatically, so any manual process left running will double-count.
The integration consequence is worth planning. Return totals flowing into an ERP will carry a tax component they did not before, and a connector that maps fields positionally or sums a hardcoded set will silently post the wrong figure. We see this repeatedly in ERP to Shopify integration work: the platform change is small, the mapping assumption it invalidates is not. Read finalizedTaxAmountSet explicitly rather than deriving tax from a difference between totals.
Role-specific impact
- Marketers: Minor, but real where return shipping cost appears in policy copy or a returns portal. If you quote a fee, confirm whether the figure shown to a US buyer should now be tax inclusive.
- Developers: Add both fields to return queries. Use taxAmountSet from returnCalculate for display during creation and finalizedTaxAmountSet from the processed return for posting. Handle null on the finalized field rather than coercing it to zero, since null means not yet processed, not no tax due.
- Store admins: Expect an estimated tax figure when creating a return and a recorded final amount after processing. Before October 23, stop any manual tax adjustment on return shipping fees so the automatic calculation is not applied twice.
Use-case example
Real-world scenario
A US apparel brand processing around 4,000 returns a month charges a 9 USD return shipping fee. At a blended rate near 7 percent, that is roughly 2,500 USD a month of tax previously uncollected and reconciled by hand each quarter. After October 23 it is collected automatically. If the ERP connector keeps summing its old field list, it posts return credits short by that amount, surfacing as a reconciliation variance that takes finance longer to diagnose than the integration change would have taken. Mapping finalizedTaxAmountSet before the date makes it a non-event.
Implementation checklist
- Confirm whether your store uses Shopify Tax or Tax Platform and ships to US addresses. If not, this is informational only.
- Inventory every manual process that reconciles tax on return shipping fees and retire it before October 23, 2026.
- Upgrade return-related queries to API version 2026-10.
- Add taxAmountSet to return calculation queries and surface it wherever an estimated refund or fee is displayed.
- Add finalizedTaxAmountSet to processed return reads and map it into your ERP or accounting integration as an explicit tax line.
- Test a return end to end in a development store, comparing the estimate against the finalized amount.
- Verify your state-level shipping tax settings still reflect intent, since return shipping fees inherit them.
FAQ
- Q: Why would the estimated and finalized tax amounts differ?
- A: The estimate is produced at calculation and the finalized figure at processing, and the tax provider can return a different amount between those moments. Treat a difference as expected and reconcile against the finalized value.
- Q: Does this change apply outside the United States?
- A: The automatic calculation starting October 23, 2026 applies to orders shipped to US addresses on stores using Shopify Tax or Tax Platform. The API fields themselves exist regardless and return zero where no tax applies, so querying them is safe for any store.
Resources
CalculatedReturnShippingFee object reference
Need guidance? Talk to Makro.