POS UIエクステンション 2026-10
カートmutationの破壊的変更
未確認の書き込みがrejectに変わる——try/catchなしでは止まらない
POS UIエクステンションのAPIバージョン2026-10から、Shopify POSがカートの変更を確認できなかった場合にカートmutationがrejectされるようになります。影響を受けるのはapi_version = "2026-10"を宣言したエクステンションのみで、2026-07以前は影響なしです。各呼び出し箇所でのエラーハンドリング追加が必須となります。
1Before / After 図解
2対象となるmutation一覧
| mutation名 | 2026-10での扱い | 備考 |
|---|---|---|
| bulkCartUpdate | reject対象 | 未確認時にreject |
| removeLineItem | reject対象 | 未確認時にreject |
| applyCartDiscount | reject対象 | 未確認時にreject |
| addCartCodeDiscount | reject対象 | 未確認時にreject |
| removeAllDiscounts | reject対象 | 未確認時にreject |
| setCustomer / removeCustomer | reject対象 | 未確認時にreject |
| addLineItemProperties 他3件 | reject対象 | bulkAdd/removeも同様 |
| setLineItemDiscount 他2件 | reject対象 | bulk/removeも同様 |
| addLineItemSellingPlan / remove… | reject対象 | 未確認時にreject |
| updateLineItemQuantity | 2026-10新規追加 | 初回リリースからreject |
3エラーメッセージの種類
4業務ユースケース
- 課題
- 決済画面へ移行後にエクステンションからカート割引を適用しようとすると、従来は失敗しても成功表示されたままになっていた
- 打ち手
- 2026-10へ移行しtry/catchを追加。catchブロック内でトースト通知「カートを更新できませんでした。再度お試しください」を表示
- 効果
- スタッフが割引未適用のまま決済を進めるミスを防止。POSの状態とUIの表示が常に一致する
- 技術メモ
- エラーメッセージ①（refused）はリトライ可能。決済フローを抜けた後に再試行するロジックを実装することで回復できる
- 課題
- カート行アイテムのプロパティ追加（addLineItemProperties）が失敗しても従来は検知できず、注文データに必要な情報が欠落することがあった
- 打ち手
- mutation呼び出しをawaitで待機し、reject時はエラーパターン②を確認。カートを読み直してプロパティの有無を確認してからリトライ
- 効果
- 部分書き込みの状態を検出でき、注文データの不整合を防止。サポート対応コストを削減
- 技術メモ
- エラーメッセージ②（could not confirm）では部分書き込みが起きている可能性があるため、リトライ前に必ずCartを読み取ること
- 課題
- セリングプランの追加（addLineItemSellingPlan）失敗時にローディングスピナーが消えず、レジ端末がフリーズしたように見える問題があった
- 打ち手
- catchブロックにローディング解除（setLoading(false)）と確認UIの非表示処理を追加。エラー時のクリーンアップを必ず実施
- 効果
- rejectが捕捉されずハンドラが途中で止まる問題を解消。スタッフ体験の向上と業務停止リスクを低減
- 技術メモ
- 公式の注意点として「rejectを捕捉しないとローディング状態のクリアや確認ステップのスキップが起きる」と明記されている
5技術者向けポイント
変更はストア単位ではなくエクステンション単位。同一アプリでもエクステンションが宣言するapi_versionごとに挙動が異なる。2026-07以前を使い続けるエクステンションは影響を受けない。
2026-07はAPIバージョニングのサポート終了まで引き続き利用可能。すぐに移行できない場合はapi_versionを2026-07以前のままにしておき、ハンドリング実装後に2026-10へ切り替える。
全カートmutationの呼び出し箇所にtry/catchまたは.catch()を追加する。既にcatchが付いている場合はそちらが発火するだけで追加対応は軽微。
このmutationは2026-10で新たに追加されたAPI。初回リリースからreject動作が前提のため、既存コードへの影響はないが、新規実装時は必ずtry/catchを付ける。
2種類のエラーメッセージは未確認書き込みの場合のみ。割引値不正・顧客情報不備などの別原因でもrejectは発生する。2種を区別が必要な場合のみmessageプロパティでマッチする実装推奨。
POS UIエクステンションを2026-10へアップグレードする前に、全カートmutationへのtry/catchを必ず実装することで、サイレントな書き込み失敗を確実なエラーハンドリングに転換できます。
Source: https://shopify.dev/changelog/cart-mutations-reject-unconfirmed-writes-in-pos-ui-extensions-2026-10 | 公開日: 2026年10月7日
Share:
Shopify Flow: トリガーコールバックが相対URLに対応
POS UI拡張の割引額返却値が変更—パーセント割引の正確な値を取得