mockup, screen, smartphone, website, blog, word, subscribe, social, media, channel, subscription, money, sale, youtube, contract, e commerce, number, netflix, streaming, stream, video, subscribe, subscribe, subscribe, subscribe, subscribe, youtube
Photo by viarami on Pixabay

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.

This is an editorial pen name used by the publication, not a claim of an independently verified personal identity. Original editorial credit: Desk Engagement.

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, a grace period, account hold, recovery or expiry. Explain the present consequence and give the person the correct route to address it.

Separate the states people experience

A renewal failure does not always mean access has expired. On Google Play, an account hold period begins after any grace period has ended. On the App Store, Billing Grace Period lets subscribers keep paid content while Apple keeps trying to collect payment; without it, their days of paid service pause until Apple collects payment.

Verified stateApp treatment
Grace period: Apple Billing Grace Period, or Google Play grace periodKeep the feature available and explain the payment issue without calling the plan cancelled.
Paused: Google Play account hold, or Apple billing retry without a grace periodExplain which benefit is paused and provide the correct payment-update route.
Payment recoversRestore the correct access and remove obsolete warnings.
Subscription expiresExplain the loss of paid access and the available resubscription route.

Know the timelines. In App Store Connect, select the app, click Subscriptions in the sidebar and set up Billing Grace Period, choosing 3, 16 or 28 days for all subscription products in the app; weekly subscriptions get at most 6 days. On Google Play, account hold is enabled by default and lasts 60 days minus any grace period, unless you change it in Play Console.

Apply the table to the states and entitlement rules of the billing route the customer actually used.

Subscription Renewal Lifecycle: Key Events and Actions

  • Renewal failsStore initiates retries or begins grace period.
  • Grace period (3–28 days, Apple; up to 60 days minus grace, Google)User retains access; app should inform but not revoke.
  • Account hold (Google Play) or billing retry (Apple without grace)Access paused; app must guide user to update payment method.
  • Payment recoveredRestore access immediately; clear prior warnings.
  • Subscription expiresAccess lost; prompt user to resubscribe via store.

Key Subscription Renewal Timelines (Australia)

Google Play Account Hold
60 days minus any grace period (default setting)
Test Environment Support
Sandbox testing available for both platforms

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 real-time developer notifications and query purchases.subscriptionsv2.get with the purchase token for the latest state.

Google Play's real-time developer notifications include SUBSCRIPTION_IN_GRACE_PERIOD when a subscription enters grace period, and SUBSCRIPTION_ON_HOLD when it enters account hold. SUBSCRIPTION_RECOVERED signals that a subscription was recovered from account hold, and SUBSCRIPTION_CANCELED that it was either voluntarily or involuntarily cancelled. Keep access during a grace period; when a subscription enters account hold, Google says to block access to the entitlement.

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.

Sample wording during a grace period: "Your last renewal payment didn't go through. You still have access for now. Update your payment method to keep your plan." During a hold: "Your premium features are paused because the renewal payment failed. Update your payment method to restore them."

Route an Apple purchase to Apple management and a Google Play purchase to Google Play management. On iPhone, the person updates payment details in Settings, by tapping their name and then Payment & Delivery. Google Play subscriptions are managed under Play > Account > Subscriptions, and the In-App Messaging API shows a snackbar that the payment was declined, with a deep link to fix the payment method on Google Play.

Reach people outside the app too. When access is suspended, Google suggests a push notification or an email telling the user that their subscription is no longer active due to payment decline. Send one message per state change and point it to the store's payment-update route, not to a card form in the app.

Drive push messages from the verified store events, not from a timer. Sample push for a grace period: "Your payment didn't go through. Update it to keep Premium." Sample push for account hold: "Premium is paused until your payment is updated." Open the app's subscription screen from the notification, re-check the state there, then hand over to the store route. When SUBSCRIPTION_RECOVERED arrives, cancel any queued reminder.

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. For Apple, turn on Billing Grace Period in the sandbox first and use the sandbox environment to test how the app handles subscribers entering and exiting the grace period.

More from Push Messaging