開発者向けの変更です。
定期購入を扱うアプリの開発者に関わる話。
取り消し理由に、新しい値 RETRY_DECLINED が加わります
発表は2026年11月4日の developer changelog です。
出典: Shopify developer changelog「RETRY_DECLINED added to CustomerPaymentMethodRevocationReason」2026年11月4日
https://shopify.dev/changelog/posts/retry_declined-added-to-customerpaymentmethodrevocationreason
フラグは「Update」。
タグは「GraphQL Admin API」です。
As of GraphQL Admin API version2027-01, CustomerPaymentMethod.revokedReason can return a new value: RETRY_DECLINED.
（GraphQL Admin API の 2027-01 から、CustomerPaymentMethod.revokedReason が新しい値 RETRY_DECLINED を返すことがあります）
対象は、保存された支払い方法の取り消し理由。
変わるのは API の 2027-01 からです。
決済事業者が再試行を止めたときに使われます
この値が返るのは、定期購入の支払い方法が取り消された場面です。
Shopify uses this value when a subscription payment method is revoked because the payment processor has blocked any further retry attempts.
（決済事業者がこれ以上の再試行を止めたために、定期購入の支払い方法が取り消されたとき、Shopify はこの値を使います）
きっかけは、決済事業者の側の判断。
これ以上は請求を試せない状態です。
古い版では、今までどおり TOO_MANY_CONSECUTIVE_FAILURES が返ります
2027-01 より前の版では、返る値は変わりません。
On earlier API versions, these revocations continue to return TOO_MANY_CONSECUTIVE_FAILURES.
（それより前の API の版では、同じ取り消しに TOO_MANY_CONSECUTIVE_FAILURES が返り続けます）
つまり、同じ取り消しでも版によって値が違います。
2027-01 に上げると、この場面で返る値が変わる形。
公式は、店と購入者への伝え方に使うよう勧めています
公式は、この値をどう使うかも書いています。
If your app reads CustomerPaymentMethod.revokedReason using API version 2027-01, use RETRY_DECLINED to indicate to merchants and buyers that the processor has blocked further charges to the saved payment method and that a different payment method is required.
（2027-01 で CustomerPaymentMethod.revokedReason を読むアプリは、RETRY_DECLINED を使って、保存された支払い方法への請求を決済事業者が止めたこと、別の支払い方法が要ることを店と購入者に伝えます）
伝える中身は2つ。
保存された支払い方法には、もう請求できないこと。
別の支払い方法が要ることです。
Webhook の中身は変わりません
取り消しを知らせる Webhook は、今までと同じ形です。
The customer_payment_methods/revoke webhook payload is unchanged. After receiving the webhook, query CustomerPaymentMethod.revokedReason to determine whether the payment method was revoked because of RETRY_DECLINED or TOO_MANY_CONSECUTIVE_FAILURES.
（customer_payment_methods/revoke の Webhook の中身は変わりません。Webhook を受けたあと、CustomerPaymentMethod.revokedReason を問い合わせて、RETRY_DECLINED と TOO_MANY_CONSECUTIVE_FAILURES のどちらで取り消されたかを見分けます）
理由を知るには、Webhook のあとに API で問い合わせる流れ。
公式は、Webhook を受けたあと API で理由を問い合わせるよう書いています。
🔴 公式に書かれていないこと
次の点は、一次ソースにありません。
- API の 2027-01 がいつ使えるようになるかは、この changelog に書かれていません
- どの決済事業者で、どんなときに再試行が止められるかは書かれていません
- 日本の店や、日本で使える決済で RETRY_DECLINED が返るかは書かれていません
- 店の管理画面や購入者向けの画面に、何か表示が出るかは書かれていません。書かれているのは、アプリが値を読んで伝えることまでです
- RETRY_DECLINED で取り消された支払い方法を、あとで使えるように戻せるかは書かれていません
- 🔴 本記事は API を呼んで値を確かめていません。記載が無いことをもって「できる」とも「できない」とも書きません
開発者がやることを整理します
手順は次の4つです。
- 自分のアプリが
CustomerPaymentMethod.revokedReasonを読んでいるかを確かめる - 2027-01 に上げる前に、TOO_MANY_CONSECUTIVE_FAILURES だけを前提にした分岐が無いかを見る
- RETRY_DECLINED のときに、別の支払い方法が要ると店と購入者に伝える文面を用意する
customer_payment_methods/revokeの Webhook を受けたら、理由を API で問い合わせる流れにする
🔵 上の手順はキクシル編集部の整理で、公式の記載ではありません。一次ソースが書くのは、値の意味と、伝える中身と、Webhook のあとに問い合わせることまでです。
出典
- Shopify developer changelog「RETRY_DECLINED added to CustomerPaymentMethodRevocationReason」2026年11月4日
https://shopify.dev/changelog/posts/retry_declined-added-to-customerpaymentmethodrevocationreason
上記の Shopify 公式の情報だけを一次情報として使っています。
