Push Messaging
Part of Mobile subscription and upgrade journeys
Handling a failed subscription renewal in the app
Map a failed renewal to verified subscription states, correct feature access and a clear in-app recovery route.
When a renewal payment fails, check the subscription's verified state before you change access or show a message. A failed charge may be followed by retries, continued access, account hold, recovery or expiry. Explain the present consequence and give the person the correct route to address it.
Key Facts: Handling Failed Subscription Renewals
- Check verified state first
- Never assume access has expired after a failed renewal.
- Apple: Use App Store Server API
- Enable notifications for real-time status changes.
- Google Play: Query subscriptionsv2.get
- Use purchase token to verify latest subscription state.
- Test with Google Play test methods
- Simulate declined payments to validate app behaviour.
Separate the states people experience
A renewal failure does not always mean access has expired. States can change in response to payment declines and other lifecycle events. Check the verified state for the billing route before deciding whether paid benefits continue or should be blocked.
| Verified state | App treatment |
|---|---|
| Paid access continues during recovery | Keep the feature available and explain the payment issue without calling the plan cancelled. |
| Paid access is on hold | Explain which benefit is paused and provide the correct payment-update route. |
| Payment recovers | Restore the correct access and remove obsolete warnings. |
| Subscription expires | Explain the loss of paid access and the available resubscription route. |
Apply the table to the states and entitlement rules of the billing route the customer actually used.
Check authoritative status
A store notification can signal that something changed. Confirm the latest subscription state before applying an entitlement change.
For Apple purchases, use the App Store Server API and enable App Store Server Notifications to receive real-time status changes. For Google Play purchases, process subscription notifications and query purchases.subscriptionsv2.get with the purchase token for the latest state.
Plan for repeated or delayed notifications, an app reinstall and a payment fixed while the app is open. Keep the entitlement record separate from an analytics event or warning banner.
Showing a banner must not remove access; dismissing one must not grant access after the verified state moves to hold or expiry. Refresh the state when the person returns to a paid feature or completes a recovery action.
Give a useful recovery route
Say what is known: that the store reports a payment issue, whether paid access currently continues and where the customer can update the payment method. Do not display card details or guess why a payment was declined. Keep any in-app message consistent with the store message.
Route an Apple purchase to Apple management and a Google Play purchase to Google Play management. Map any other supported billing route separately. After verified recovery, remove the stale warning. While recovery is pending, do not claim the payment succeeded.
Check edge cases before release
Include failure at trial-to-paid conversion, recovery after a payment failure, expiry, cancellation during recovery and a second device in the release check plan. For each case, compare expected access, message and destination with the store's reported status.
Use Google Play test payment methods to simulate a declined payment, then check the app's handling against its expected entitlement and message.
