返送料の税額フィールドがGraphQL Admin APIに追加
2026-10対応 ― 返品フローの税計算を正確に取得・表示できるようになります
APIバージョン 2026-10 より、GraphQL Admin APIに返送料の税額を返す2つの新フィールドが追加されました。Shopify Tax または Tax Platform を利用している米国向け店舗で、2026年10月23日から返送料への課税が開始される変更への対応に必要です。返品フローを自社実装している開発者は早急に確認してください。
1変更内容の図解：Before / After
2業務に活かせる具体ユースケース
- 課題
- 返品時に返送料の税額をカスタム返品画面に表示したいが、APIから取得できない
- 打ち手
-
returnCalculateクエリでtaxAmountSetを取得し、返品確認画面に「返送料税額：〇〇円」として表示する - 効果
- 顧客が返品前に税込みコストを把握でき、問い合わせ削減・透明性向上につながる
- 技術メモ
- フィールド型は
MoneyBag!（Non-null）。税が不要な場合はゼロが返るため、null チェック不要
- 課題
- 返品処理後の実際の税額と事前見積もりがズレており、会計システムとの照合に手間がかかる
- 打ち手
- 返品処理完了後に
finalizedTaxAmountSetを取得し、ERPや会計SaaSへ確定税額を連携する - 効果
- 見積もりと確定額の差分を自動で記録でき、経理担当者の手作業修正が不要になる
- 技術メモ
- 型は
MoneyBag（nullable）。returnProcessミューテーション完了までnullを返すため、処理後に再フェッチするロジックが必要
- 課題
- Shopify Tax / Tax Platform 導入後、2026-10-23 以降の米国向け返品で税計算エラーが発生しないか確認したい
- 打ち手
- ステージング環境で
2026-10APIバージョンへ切り替え、returnCalculate→returnProcessのフローを通しテストし、両フィールドの値を検証する - 効果
- 本番リリース前に税額取得ロジックの不具合を発見でき、課税開始日前に安全に対応できる
- 技術メモ
- 課税対象は「米国向け注文 × Shopify Tax または Tax Platform 利用店舗」に限定。他国・他税プロバイダーは元記事に記載なし
3技術者目線のポイント
| 項目 | 内容 |
|---|---|
| 対応 API バージョン | 2026-10 以降。それ以前のバージョンでは新フィールドは取得不可 |
| taxAmountSet の型 |
MoneyBag!（Non-null）。ショップ通貨・提示通貨の両方を含む。tax 不要時はゼロ値 |
| finalizedTaxAmountSet の型 |
MoneyBag（nullable）。returnProcess 完了前は null。tax 不要時はゼロ値 |
| 利用可能クエリ / ミューテーション |
returnCalculate（taxAmountSet）、returnProcess 後の ReturnShippingFee（finalizedTaxAmountSet） |
| 金額差異への注意 | 見積もり時と処理時でtaxプロバイダーが返す金額が異なる場合があり、両フィールドの値が一致しないケースが発生しうる |
| 課税開始日と対象範囲 | 2026年10月23日から。対象は米国向け注文 × Shopify Tax または Tax Platform 利用店舗のみ（元記事より） |
移行チェックリスト
- GraphQL クライアントのAPIバージョンを
2026-10へ更新 -
returnCalculateクエリにtaxAmountSetフィールドを追加 -
ReturnShippingFee取得箇所にfinalizedTaxAmountSetを追加し、nullガード処理を実装 - 会計・ERP連携スクリプトへ確定税額の受け渡しロジックを追加
- 米国向け注文かつ Shopify Tax 利用の場合のみ税額が発生することをテストで確認
返品フローを自社実装している米国向け EC 事業者・開発者は、API 2026-10 への移行と taxAmountSet / finalizedTaxAmountSet の組み込みを 2026年10月23日の課税開始前に完了させることで、返送料にかかる税額を正確に表示・記録できます。
Source: https://shopify.dev/changelog/new-return-shipping-fee-tax-fields | 公開日: 2026年10月1日
Share:
購入者からの注文変更リクエストを管理する新API
ディスカウントアプリにApp Intentsを導入する方法