Shopify’s GraphQL Admin API version 2027‑01 introduces a subtle but important change to the CustomerPaymentMethod.revokedReason field. In addition to the existing TOO_MANY_CONSECUTIVE_FAILURES, the API now returns a new enum value RETRY_DECLINED when a payment processor blocks any further retry attempts on a subscription payment method. This post breaks down the update, explains who needs to care, and gives you concrete steps to make your apps and integrations future‑proof.
What Changed in the API
Previously, when a saved payment method was revoked because the processor refused further charges, the revokedReason field always reported TOO_MANY_CONSECUTIVE_FAILURES. Starting with version 2027‑01, Shopify distinguishes two scenarios:
• TOO_MANY_CONSECUTIVE_FAILURES – the usual case where multiple charge attempts failed in a row.
• RETRY_DECLINED – the processor has explicitly blocked any additional retries, meaning the merchant must replace the payment method before any future attempts.
Who Is Affected?
The change is primarily developer‑focused. Any app, custom integration, or theme that reads CustomerPaymentMethod.revokedReason needs to handle the new enum. Merchants indirectly benefit because the additional granularity lets your app surface clearer messages (e.g., “Your processor blocked further retries – please add a new card”). If you rely on webhooks alone, you’ll still receive the same customer_payment_methods/revoke payload, but you’ll need to query the updated field to differentiate the reasons.
How to Detect RETRY_DECLINED
graphql
query GetRevokedReason($id: ID!) {
customerPaymentMethod(id: $id) {
revokedReason
}
}
The revokedReason field will now return either "RETRY_DECLINED" or "TOO_MANY_CONSECUTIVE_FAILURES". Compare the string to trigger the appropriate UI flow.
Updating Your App Logic
If you previously treated every revocation as a generic failure, you’ll want to add branching logic. For example:
javascript
if (revokedReason === 'RETRY_DECLINED') {
// Show merchant a message that the processor blocked retries
// Prompt the buyer to add a new payment method
} else if (revokedReason === 'TOO_MANY_CONSECUTIVE_FAILURES') {
// Suggest the buyer update the existing card or retry later
}
By surfacing the exact cause, you reduce confusion, lower support tickets, and improve recovery rates for subscription revenue.
Testing & Best Practices
Action Checklist for Developers
Conclusion & Next Steps
The addition of RETRY_DECLINED gives you a clearer window into why a subscription payment method was disabled, enabling more precise messaging and faster recovery. Update your API version, adjust your revocation handling, and you’ll see a smoother experience for both merchants and buyers. Need help implementing the change? Reach out to our Shopify Partner support or drop a comment below – we’re happy to walk you through the integration.
