RETRY_DECLINED added to CustomerPaymentMethodRevocationReason
Source: Shopify Dev Changelog
What Changed
Shopify has added a new enum value, RETRY_DECLINED, to CustomerPaymentMethodRevocationReason in the GraphQL Admin API, effective with API version 2027-01. This value can now be returned by the revokedReason field on the CustomerPaymentMethod object.
RETRY_DECLINED is used specifically when a subscription payment method is revoked because the payment processor has explicitly blocked further retry attempts. This is distinct from the existing TOO_MANY_CONSECUTIVE_FAILURES value, which is returned when Shopify stops retrying after reaching its own internal retry limit.
Apps querying CustomerPaymentMethod.revokedReason on API versions earlier than 2027-01 will continue to receive TOO_MANY_CONSECUTIVE_FAILURES for both scenarios. The distinction only becomes available once an app upgrades to the 2027-01 API version.
Why This Matters for App Developers
Apps that manage subscriptions, dunning flows, or customer payment method status (particularly subscription billing apps, retention tools, and customer-facing account portals) rely on revokedReason to explain why a payment method stopped working. Previously, a single generic reason covered both processor-level blocks and Shopify’s retry exhaustion, making it difficult to give merchants or buyers an accurate explanation or next step.
With RETRY_DECLINED, apps can differentiate between a processor actively rejecting retries (often indicating a hard decline, fraud flag, or closed account) versus Shopify simply exhausting its standard retry schedule. This distinction can inform different messaging or recovery flows, such as prompting the customer to update their payment method immediately versus waiting for a scheduled retry.
What to Watch For
Developers should audit any logic that branches on revokedReason values, including conditional messaging, webhook handlers, or support documentation. Upgrading to API version 2027-01 is required to receive RETRY_DECLINED. Apps that have hardcoded checks only for TOO_MANY_CONSECUTIVE_FAILURES should update their enum handling to avoid silently misclassifying these new cases.