useBuyerJourneyIntercept廃止と移行ガイド

7月 21, 2026

API CHANGE

useBuyerJourneyIntercept
廃止と移行ガイド

クライアントサイドのバリデーションから、サーバーサイドFunctionsへ

2026-07 APIバージョンより、checkout UI extensionsで使用されてきた useBuyerJourneyIntercept フックと、それが依存する block_progress ケイパビリティが非推奨（deprecated）となりました。既存の拡張機能は現行・過去のAPIバージョンでは引き続き動作しますが、将来のバージョンで削除される予定のため、今から移行計画を立てる必要があります。移行先はShopify Functionsのサーバーサイド処理です。

BACKGROUND

01何が廃止されるのか

今回の非推奨化の対象は以下の2点です。

廃止対象①

useBuyerJourneyIntercept

checkout UI extensionsで使用するPreactフック。購入フローの途中でビジネスロジックを差し込み、進行をブロックする役割を担っていた。

廃止対象②

block_progress ケイパビリティ

shopify.extension.toml 設定ファイルに記述するケイパビリティ宣言。このフックを使う拡張機能には必須の設定だったが、フックと共に非推奨となる。

ARCHITECTURE

02Before / After：アーキテクチャの変化

USE CASES

03業務別移行ユースケース

課題: 特定の顧客セグメントや購入条件に応じたビジネスルール（例：法人向け購入条件、年齢確認など）をチェックアウト時に強制していた
打ち手: Cart and Checkout Validation Functionへ移行。サーバーサイドで同等のルールチェックを実装する
効果: 通常チェックアウトだけでなく、エクスプレスウォレット（Shop Pay等）やエージェント型チェックアウトでも同じルールが一貫して適用される
技術メモ: Functionはサーバーサイド実行のため、クライアント環境の差異に依存しない安定したバリデーションが実現できる

課題: 特定の割引コードをチェックアウト途中で拒否し、ユーザーにカスタムエラーメッセージを表示していた
打ち手: Discount Function APIへ移行。同APIは現在、カスタムメッセージ付きで割引コードを拒否する機能をサポート
効果: 割引コード拒否のロジックをUI extensionから切り離し、Function側で管理することで保守性が向上する
技術メモ: Discount Function APIがカスタムメッセージ付き拒否をサポートしたことで、移行後もユーザー体験を損なわずに同等の制御が可能

課題: 上記に該当しないカスタムユースケースで useBuyerJourneyIntercept を使用しており、Functionsへの移行パスが不明確
打ち手: Shopifyコミュニティフォーラム（https://community.shopify.dev/t/the-buyer-journey-intercept-api-is-now-deprecated/35930）に自身のユースケースを投稿し、代替策を相談する
効果: Shopifyチームおよびコミュニティから移行方針のフィードバックを得られる可能性がある
技術メモ: 公式が明示的にコミュニティへの投稿を案内しているため、エッジケースはまず情報収集を優先すること

DEVELOPER NOTES

04技術者が押さえるべき5つのポイント

項目	内容
非推奨開始バージョン	2026-07 APIバージョンより非推奨。既存の拡張機能は現行・過去バージョンでは引き続き動作する
削除時期	将来のバージョンで削除予定。具体的なバージョンは元記事に記載なし。早期の移行計画を推奨
toml設定の変更	`shopify.extension.toml` に記載している `block_progress` ケイパビリティも削除が必要。設定ファイルの見直しを忘れずに
主な移行先①	ビジネスルール強制 → Cart and Checkout Validation Function（サーバーサイド、全チェックアウト面で動作）
主な移行先②	割引コード拒否 → Discount Function API（カスタムメッセージ付き拒否をサポート済み）