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

What Changed

Shopify has added new tax fields for return shipping fees to the GraphQL Admin API, effective as of API version 2026-10. These fields expose tax amounts calculated by a merchant’s configured tax provider on return shipping fees, which were previously not available through the API.

Two new fields are now accessible:

• CalculatedReturnShippingFee.taxAmountSet (type MoneyBag!): Returns the estimated tax on a return shipping fee in both shop and presentment currencies. This field is available on the returnCalculate query and returns zero when no tax applies to the fee.
• ReturnShippingFee.finalizedTaxAmountSet (type MoneyBag): Returns the finalized tax amount charged on the return shipping fee once the return has been processed.

Why This Matters for App Developers

Apps that handle returns, exchanges, or reverse logistics for Shopify merchants previously had limited visibility into the tax implications of return shipping fees. This gap made it difficult to provide accurate cost breakdowns to merchants or customers during the return flow, particularly in regions where shipping fees are taxable.

With these new fields, apps can now surface precise tax calculations at both the estimate stage (via returnCalculate) and the finalized stage (once a return is completed). This is relevant for apps built around order management, customer service, returns portals, and financial reconciliation.

Practical Implications

Developers working with the Returns API should update their GraphQL queries to request these new fields where tax transparency is required. Since taxAmountSet and finalizedTaxAmountSet use the MoneyBag type, responses will include values in both shop currency and presentment currency, so apps displaying multi-currency storefronts should handle both correctly.

Developers should also test behavior in regions where return shipping fees are not taxed, since taxAmountSet will return zero in those cases rather than null. Apps building financial reports or tax reconciliation tools should distinguish between the estimated amount (pre-finalization) and the finalized amount to avoid discrepancies in merchant-facing reports.

Read the full announcement →