New tax fields for return shipping fees in the GraphQL Admin API

As of API version 2026-10, the GraphQL Admin API exposes the tax amounts calculated for return shipping fees. These amounts reflect the tax calculated by the merchant's tax provider for the fee.

What's new

CalculatedReturnShippingFee.taxAmountSet (MoneyBag!) — the estimated tax on the return shipping fee, in shop and presentment currencies. Available on the returnCalculate query, and zero when no tax applies to the fee.

ReturnShippingFee.finalizedTaxAmountSet (MoneyBag) — the tax charged on the return shipping fee, locked in when the return is processed. Returns null until the return is processed, and zero when no tax applies to the fee.

Use taxAmountSet to show the tax estimated when a return is being created, and finalizedTaxAmountSet to reconcile the tax actually charged. The two can differ when the tax provider returns a different amount at the time the return is processed.

Why it Matters

Starting October 23, 2026, Shopify will calculate tax on return shipping fees for orders shipped to the United States on stores that use Shopify Tax or Tax Platform. For more details, visit https://changelog.shopify.com/posts/tax-is-now-calculated-on-return-shipping-fees

Relevant Docs

• Tax is now calculated on return shipping fees
• CalculatedReturnShippingFee
• ReturnShippingFee
• returnCalculate
• returnProcess