Shopify POSのカート更新がrejectを返す変更｜結果不明時の再試行とUIを見直す

Shopifyは2026年10月7日、POS UI extensionsの2026-10 APIで、POS側がカート変更を確認できない更新はPromiseをrejectする変更を告知しました。割引や顧客の設定を呼び出した後、無条件に成功表示へ進む拡張は見直しが必要です。会計中の拒否と結果不明を区別し、確認前の再試行で同じ操作を重ねない設計にします。

本稿は2026年10月27日に確認した公式資料に基づく移行解説です。対象はShopify POSのUI拡張を開発・保守する担当者であり、オンラインストア全体のカート仕様が一斉に変わるという話ではありません。以下の状態管理とテスト計画は本サイトの提案です。掲載コードは分岐の例で、実機での動作確認や配備は行っていません。

更新要求を送れたことと変更の確定を分ける

変更点はShopify公式のカート更新に関する告知で確認できます。旧版ではPOSが更新を適用したかにかかわらずresolveする呼び出しがありました。2026-10では、対象操作はPOSが成功を確認しなければrejectします。割引済みと画面に出たのに実際のカートが変わっていない、という食い違いを呼び出し側で扱う変更です。

影響は店舗単位の設定ではなく、拡張が宣言するAPIバージョンで判断します。2026-07以前はこの変更の対象外です。まず各拡張のapi_versionと、利用するカート更新メソッドを対応付けます。同じアプリに複数の拡張がある場合、一つの設定ファイルだけを見て全体の移行が終わったと判断しないようにします。

2026年10月28日追記：影響する呼び出しの確認漏れを防ぐため、公式告知の対象を明記します。bulkCartUpdate、removeLineItem、applyCartDiscount、addCartCodeDiscount、removeAllDiscounts、setCustomer、removeCustomer、addLineItemProperties、bulkAddLineItemProperties、removeLineItemProperties、setLineItemDiscount、bulkSetLineItemDiscounts、removeLineItemDiscount、addLineItemSellingPlan、removeLineItemSellingPlanが対象です。新しいupdateLineItemQuantityも初回提供からrejectを扱います。名前にcartを含む呼び出しだけでなく、明細のプロパティ・割引・販売プランを変更する箇所まで照合してください。対象条件は拡張が宣言する2026-10以降のAPI版です。

拒否と結果不明で再試行の判断を変える

告知は未確認の更新について二つの結果を区別しています。一つはPOSが要求を拒否し、カートが変更されていない場合です。例えば担当者が支払いへ進み、カート編集を受け付けない場面があります。もう一つは更新を確認できず、部分的に反映された可能性もある場合です。後者では再試行前にカートを読み直す必要があります。

両方を一律に「失敗したので同じ要求をもう一度送る」とすると、結果不明の操作を重ねるおそれがあります。画面を元へ戻すだけでも、すでに一部反映された状態とは一致しない場合があります。ここでは、成功、変更されなかった拒否、結果不明、その他のエラーを分ける方針を勧めます。その他には入力値の不備などもあるため、二つの文言だけですべてのエラーを説明しないでください。

スタッフ向け表示も結果に合わせます。拒否なら編集できる状態で操作し直す案内、結果不明なら現在のカートを確認する案内にします。単に赤い失敗表示を出すだけでは、担当者が連打すべきか、待つべきか、商品や金額を確認すべきかが分かりません。利用者に見せる言葉と、開発者が記録する原因分類を別に用意すると運用しやすくなります。

成功フラグと処理中表示を同じ真偽値にしない

更新ボタンの無効化、スピナー、成功通知、再確認の案内を一つのフラグで管理すると、例外時に状態が曖昧になります。処理中かどうかと、操作結果が確定したかどうかを分けてください。以下は、実際のカート変更をwriteへ渡して実行する説明用のラッパーです。UI更新とログの各関数は、利用中のフレームワークで実装する前提です。

async function runCartWrite(write, ui, record) {
  ui.setBusy(true);
  ui.setOutcome('pending');
  try {
    await write();
    ui.setOutcome('confirmed');
  } catch (error) {
    const message = error instanceof Error ? error.message : '';
    let outcome;
    if (message === 'POS refused the cart update. The cart was not changed.') {
      outcome = 'refused';
    } else if (message === 'POS could not confirm the cart update.') {
      outcome = 'needs-review';
    } else {
      outcome = 'error';
    }
    ui.setOutcome(outcome);
    record({ outcome });
  } finally {
    ui.setBusy(false);
  }
}

この例は自動で再試行しません。結果不明なら確認する状態へ進み、業務上の成功表示を保留します。また、finallyで処理中表示を解除するので、reject後にスピナーが残る実装を避けやすくなります。ただしUI関数や記録処理自体の例外、画面の破棄、処理の競合まで解決する完成コードではありません。実装時にはアプリのライフサイクルへ合わせてください。

エラー文言は公式告知が示す二種類を判別するためにだけ比較しています。将来の文言変更や想定外の値に備え、どちらにも一致しない分岐を残します。unknownの値を無理にErrorへ型変換して完了させず、汎用的なエラーとして扱える状態にします。記録には分類と操作名など必要な情報を使い、顧客情報を含むカート全体を安易に出力しない方がよいでしょう。

実際のカートを読み直してから表示を整える

状態の取得方法は公式のCart APIリファレンスで確認します。currentは現在のカートを参照し、変更を購読できる仕組みです。拡張内に保存した「割引を入れたはず」という値だけを表示の根拠にせず、POSから得る現在の状態と照合する設計にします。

結果不明時には、操作前の対象、意図した変更、読み直した状態を比較します。例えば特定の顧客を設定した操作なら、現在関連付けられた対象を見ます。明細を変更したなら、対象の識別情報と数量など、その操作に必要な範囲を確認します。カートの何かが変わったというだけでは、自分の要求が全部成功した証拠にはなりません。

読み直しと同時に、スタッフが別の変更を加える場面も考慮します。古いカートの内容を丸ごと復元すると、別操作まで取り消してしまう可能性があります。結果不明を解消する目的で、変更前のスナップショットをそのまま書き戻す方式は避けます。現在の状態を基準に、何が不足しているかを確認し、必要な操作だけを判断する方針にします。

連打と複数操作の途中失敗を試験に入れる

成功した一回の操作だけでは移行を確認できません。処理中に同じボタンを押した場合、別ボタンから同じ対象へ変更した場合、画面を閉じた場合も確認します。ボタンを無効化しても、別の入力経路や別ハンドラーから呼ばれる可能性があります。どの経路で要求が発生するかを洗い出し、二重実行を防ぐ単位を決めます。

複数のカート更新を順番に呼ぶ機能では、途中でrejectされたときの業務状態を考えます。最初の顧客設定が完了し、次の割引が失敗した場合、全体を単純に未実行とは扱えません。成功済みの操作と未確定の操作を区別し、画面へどこまで終わったかを示します。複数APIを呼ぶコードを、根拠なく一つのトランザクションとして扱わないことが重要です。

bulk系の操作を使っていても、告知が結果不明時の部分反映の可能性を示す点は意識します。まとめて呼べば必ず全件成功か全件失敗になると仮定せず、利用するメソッドの契約を確認します。再試行前に状態を読む方針は、呼び出し回数を減らす最適化と別の課題です。速く終わることより、会計前に表示と実状態が一致することを優先してください。

移行前に作る検証表

最初の検証項目は、通常の編集可能なカートで一回だけ更新し、成功表示と実状態が一致することです。次に、支払いへ移った場面など更新を受け付けない条件で、拒否を捕捉し処理中表示が解除されることを確認します。結果不明の分岐は、再試行が勝手に始まらず確認案内へ進むことをチェックします。

結果不明を実機で安定して再現できない場合は、テスト用のwrite関数をrejectさせてUI分岐を確認できます。ただし、それは拡張の分岐の試験であり、POS側の部分反映を実証した試験ではありません。モックで確認した項目と、実際のPOSで確認した項目を記録上も分けます。実機で未確認の現象を、検証済みとしてリリース資料へ書かないでください。

そのほか、入力値が不正な場合、対象明細が途中で消えた場合、操作画面を閉じた場合を試します。エラー通知が出ることだけでなく、成功バッジが残らないこと、次の操作へ進めること、不要な再送がないことを見ます。テスト結果にはAPI版、拡張の版、POSの利用環境、再現手順を添え、次の担当者が同じ条件を作れるようにします。

バージョンを上げる前に呼び出し箇所を直す

更新の順序は、対象呼び出しの棚卸し、例外処理と画面状態の修正、試験、API版の変更、配備後の確認に分けると追いやすくなります。共通ラッパーがある場合も、戻り値を無視する呼び出しや、awaitされていないPromiseが残っていないかを確認します。型チェックが通ることと、実行時のrejectを捕捉できることは別です。

版の扱いはShopify公式のAPIバージョニング資料も確認してください。旧版に一時的に残す選択をする場合でも、そのまま無期限に利用できる計画にはしません。対応するリリースノート、更新対象、保守期限の確認担当を残し、例外処理の準備が終わった段階で移行できる状態にします。

公開後は、未処理のPromise rejection、処理中表示の残留、結果不明からの再送件数など、自分たちの実装が観測できる項目を確認します。監視で操作内容を追うときも、個人情報を集め過ぎず、操作の種類と結果を中心に扱います。現場スタッフには、新しい確認案内が何を意味するかを共有しておくと、連打による混乱を減らせます。

会計前の判断を明確にする変更として取り込む

今回の変更は、catchを一つ足して終えるだけでなく、更新が確定したかをスタッフへ正しく伝える機会です。要求を送った、POSが反映を確認した、結果が分からないという状態を分ければ、表示だけ成功していた不整合を表面化できます。各呼び出しでrejectを扱い、結果不明では現在のカートを読み、確認した状態に基づいて次の操作を選ぶ流れへ整えてください。

参考資料

Shopify：POS UI extensions 2026-10のカート更新変更（2026年10月7日）
Shopify：POS Cart API（2026-10・2026年10月27日確認）
Shopify：APIバージョニング（2026年10月27日確認）