トークン移行エラーを7日間リカバリ可能に

DEV UPDATE

ユーザーセッションなし移行でレスポンスを失っても再試行で復旧できます

このアップデートは、ユーザーセッションなしでオフライントークンを移行するアプリ開発者を対象に、2026年9月29日より有効です。移行レスポンスの消失時に元の非有効期限トークンで再試行することで、マーチャントに再認証を求めずトークンを復旧できます。既存のフローを変更しなくても動作し続けます。

課題: 移行リクエスト後にサーバーが再起動しレスポンスが失われ、新トークンの保存に失敗した
打ち手: 初回交換から7日以内に、同一の非有効期限トークンと有効なクライアント認証情報で同じ移行リクエストをリトライする
効果: マーチャントにアプリを再起動させることなく、同一のアクセストークンとリフレッシュトークンのペアを取得して保存できる
技術メモ: 返却されるアクセストークンとリフレッシュトークンの値は初回と同一。アクセストークンの有効期限は必要に応じて延長される。リフレッシュトークンの有効期限は延長されない点に注意

課題: 大量ストアを一括移行するバッチ処理で、一部ストアのレスポンス保存が間欠的に失敗する
打ち手: バッチ処理にリトライロジックを追加し、移行失敗ストアを7日以内に自動再試行するキューを設ける
効果: 移行成功率を高め、マーチャントへの手動介入依頼メールやサポート対応を削減できる
技術メモ: リトライ成功後は必ずアクセストークン・リフレッシュトークン・有効期限をセットで永続化し、旧トークンを破棄すること。7日の起算点は「そのストアと元トークンに対する初回交換時点」

課題: リトライしても invalid_subject_token が返りトークン復旧ができない
打ち手: invalid_subject_token を受け取った場合は7日の回収期間が終了したと判断し、IDトークン交換または認可コードグラントで新しいトークンを取得してストア認証情報を更新する
効果: エラーハンドリングが明確になり、リカバリ不能なケースでも適切なフォールバックフローを構築できる
技術メモ: invalid_subject_token が返るタイミング: ①7日間経過後、②アプリが発行済みペアを正常にリフレッシュ済み、③同一ストアの後続トークン取得（新認可コードやIDトークン交換）でペアが置き換わった後

観点	詳細
対象スコープ	ユーザーセッションなしでの非有効期限オフライントークン → 有効期限付きオフラインアクセストークン移行のみ
リカバリ有効期間	初回交換から最大7日間。ストア×元トークンの組み合わせ単位で管理される
返却値の仕様	リトライ時のアクセストークン・リフレッシュトークンは初回と同一値。アクセストークンの有効期限は必要に応じて延長されるが、リフレッシュトークンの有効期限は延長されない
リカバリ終了条件	①7日経過 ②発行済みペアの正常リフレッシュ ③同一ストアの後続トークン取得（新認可コードまたはIDトークン交換）のいずれか
旧トークンの扱い	移行後の元非有効期限トークンはGraphQL Admin APIリクエストには使用不可。リカバリ成功後は即座に破棄すること
既存フロー変更	不要。変更しなくても既存の動作は維持される。リトライロジックの追加は任意だが推奨

実装フロー（推奨）

「非有効期限トークンの移行でレスポンスを失っても7日間は元トークンで再試行できるため、マーチャントへの再認証依頼なしにアクセスを復旧でき、移行の信頼性とUXを同時に向上できます。」

Source: https://shopify.dev/changelog/more-resilient-token-exchanges-when-migrating-tokens-without-a-user-session | 公開日: 2026年9月29日 ※本記事はShopify公式ではなく独立系メディアcompassによる解説です。最終確認は必ず公式ドキュメントをご参照ください。