totalUnsettledSet の二重計算バグ修正

8月 15, 2026

ORDERS API / BUG FIX

totalUnsettledSet の二重計算バグ修正

保留中キャプチャで金額が膨らんでいた問題が、全APIバージョンに即時適用で解消

このバグ修正は Shopifyの決済フローでマルチキャプチャ（部分・複数キャプチャ）を利用しているすべての開発者・事業者に影響します。2026年4月24日より全APIバージョンに即時適用され、コード変更は不要です。OrderTransaction.totalUnsettledSet が返す金額が正しくなり、キャプチャ可能残額の計算に依存するアプリやダッシュボードの数値が修正されます。

1何が変わったか：Before / After 図解

totalUnsettledSet はゲートウェイ側でまだキャプチャ可能な金額を表すフィールドです。PENDINGのキャプチャは「すでに処理中」として差し引かれるのが正しい挙動です。

2業務に活かせるユースケース

課題: マルチキャプチャ対応の受注管理システムで「追加でキャプチャできる金額」を画面に表示しているが、PENDING状態のキャプチャがある注文で金額が実際より大きく表示されてしまっていた。
打ち手: totalUnsettledSet をそのまま表示ロジックに使用しているコードはそのままで問題なし。修正後の正しい値が自動的に返ってくるため、UI側の表示が自然に正確になる。
効果: スタッフが誤った残高を見てキャプチャ操作を行うミスが減少。分割請求や後日キャプチャを多用するB2B・大型注文で特に恩恵が大きい。
技術メモ: コード変更不要。既存のGraphQLクエリはそのまま動作し、返却値だけが正しくなる。

課題: Shopify Paymentsを使った注文で、キャプチャが PENDING → SUCCESS と遷移する際に totalUnsettledSet の値が一時的に膨らみ、売上レポートや在庫・財務連携システムとの数値が合わなかった。
打ち手: 修正後はPENDING状態でも正しい未確定額が返るため、webhookやポーリングで値を取得しているシステムは再計算や補正ロジックを外すことを検討できる。
効果: Shopify Payments のキャプチャフロー移行（PENDING経由）に起因する数値ズレが解消。外部ERPや会計ツールとのデータ整合性が向上する。
技術メモ: Shopify Payments がキャプチャを PENDING→SUCCESS と遷移させる新フロー導入後にこのバグが顕在化したと公式が説明している。

課題: 部分キャプチャを活用する出荷連動型の請求アプリで、残キャプチャ可能額を元に次回キャプチャ額の上限値を動的に設定しているが、上限が過大になる不具合が発生していた。
打ち手: totalUnsettledSet を上限値のソースとして使う設計はそのまま維持。バグ修正により正しい上限値が返るようになったことで、超過キャプチャを誤って提案するリスクが排除される。
効果: ゲートウェイエラー（キャプチャ上限超過）の発生率低下が期待できる。ユーザーへの「キャプチャ可能額が足りない」エラーも減少する見込み。
技術メモ: 影響範囲は multi-capturable orders のみ（通常の単一キャプチャ注文は影響なし）。

3技術者が押さえておくべきポイント

項目	詳細
対象フィールド	`OrderTransaction.totalUnsettledSet`（GraphQL Admin API）
影響するAPIバージョン	全バージョンに即時適用（Shopify APIブレーキングチェンジポリシーに基づく）
コード変更の要否	不要。既存クエリはそのまま機能し、返却値が正しくなるのみ
影響する注文タイプ	multi-capturable orders（部分キャプチャ・複数キャプチャ対応の注文）のみ
バグの経緯	マルチキャプチャサポート追加時に混入。Shopify Payments がPENDING経由フローへ移行後に顕在化
バグ修正の即時適用について	公式APIブレーキングチェンジポリシーでは「ドキュメント記載の挙動に合わせるバグ修正は全バージョン即時適用」と定義されている