The Users You Cut Off as Churned Were Still Willing to Pay — Implementing Grace Periods That Keep Access Alive

Normalizing store notifications on the server

App Store Server Notifications V2 (ASSN V2) and Google Play's Realtime Developer Notifications (RTDN) push payment failures and recoveries in real time. If you update your own entitlement table from them, the app can fetch the latest state on launch. I host my Rork (Expo) backends on Cloudflare Workers, so here is an example of receiving them in a Worker.

// worker/notifications.ts (Cloudflare Workers)
// Map each store's notification types to EntitlementState
type Store = 'apple' | 'google';
 
function mapApple(notificationType: string, subtype?: string): EntitlementState {
  switch (notificationType) {
    case 'DID_RENEW':
    case 'SUBSCRIBED':
      return 'active';
    case 'DID_FAIL_TO_RENEW':
      // subtype GRACE_PERIOD means grace; otherwise move to hold
      return subtype === 'GRACE_PERIOD' ? 'grace' : 'hold';
    case 'EXPIRED':
      return 'expired';
    default:
      return 'active'; // unknown types lean toward keeping access (never lock out by mistake)
  }
}
 
function mapGoogle(notificationType: number): EntitlementState {
  // Google Play RTDN subscriptionNotificationType
  switch (notificationType) {
    case 2:  // SUBSCRIPTION_RENEWED
    case 4:  // SUBSCRIPTION_PURCHASED
    case 7:  // SUBSCRIPTION_RESTARTED (recovered from hold)
      return 'active';
    case 6:  // SUBSCRIPTION_IN_GRACE_PERIOD
      return 'grace';
    case 5:  // SUBSCRIPTION_ON_HOLD
      return 'hold';
    case 3:  // SUBSCRIPTION_CANCELED
    case 13: // SUBSCRIPTION_EXPIRED
      return 'expired';
    default:
      return 'active';
  }
}

Notice that default leans toward active (keeping access). Rather than locking someone out on an unknown notification type, it is safer for both the user experience and revenue to keep access and revoke on the next definitive notification. The principle: only lock out when you positively know the subscription cancelled or expired.

Always verify the signature before processing a store notification. ASSN V2 arrives as a JWS and Google RTDN as a Pub/Sub message; skipping verification lets a forged notification manipulate entitlements. I cover signature verification and idempotency (not double-processing the same notification) in detail in the guide to running App Store Server Notifications V2 yourself.

Leaning access toward "keep during grace, suspend at hold"

When it comes time to use the normalized state in the app, one more decision remains: present features differently for grace versus hold. I settled on these rules.

• active / grace: all premium features work. Show a subtle banner only during grace.
• hold: lock premium features, but keep the data and state clearly that "update your card and you're back instantly."
• expired: return to the normal non-member flow.

// subscription/access.ts
import { EntitlementSnapshot } from './types';
 
export function canUsePremium(snap: EntitlementSnapshot): boolean {
  // grace keeps access. hold/expired/never do not.
  return snap.state === 'active' || snap.state === 'grace';
}
 
// Decide which kind of message to show
export type RecoveryPrompt = 'none' | 'soft' | 'hard';
 
export function recoveryPrompt(snap: EntitlementSnapshot): RecoveryPrompt {
  if (snap.state === 'grace') return 'soft'; // still usable; nudge quietly
  if (snap.state === 'hold') return 'hard';  // not usable; prompt clearly
  return 'none';
}

That canUsePremium includes grace as true is the heart of this article. Many implementations restrict it to state === 'active' only, killing the recovery opportunity that the grace period represents.

Splitting the in-app recovery flow into soft and hard

The UI branches on the return value of recoveryPrompt. During grace (soft), don't stop any features — just show a small notice at the top of the screen. At hold (hard), block before the premium screen and send the user directly to the store's subscription management page.

// components/RecoveryBanner.tsx
import { Linking, Platform, Pressable, Text, View } from 'react-native';
import { recoveryPrompt } from '../subscription/access';
import { EntitlementSnapshot } from '../subscription/types';
 
// Open the store's subscription management screen (the user updates their card here)
function openManageSubscription() {
  const url = Platform.OS === 'ios'
    ? 'https://apps.apple.com/account/subscriptions'
    : 'https://play.google.com/store/account/subscriptions';
  Linking.openURL(url);
}
 
export function RecoveryBanner({ snap }: { snap: EntitlementSnapshot }) {
  const kind = recoveryPrompt(snap);
  if (kind === 'none') return null;
 
  const soft = kind === 'soft';
  return (
    <View style={{
      padding: 12,
      backgroundColor: soft ? '#FFF7E6' : '#FDECEC',
    }}>
      <Text style={{ fontWeight: '600', marginBottom: 4 }}>
        {soft ? 'We need to verify your payment' : 'Premium is paused'}
      </Text>
      <Text style={{ marginBottom: 8 }}>
        {soft
          ? `You can keep using everything until you update your card${
              snap.graceUntil ? ` (through ${formatDate(snap.graceUntil)})` : ''
            }.`
          : 'Update your payment method and you are back instantly. Your data is still here.'}
      </Text>
      <Pressable onPress={openManageSubscription}>
        <Text style={{ color: '#2563EB', fontWeight: '600' }}>
          Manage subscription
        </Text>
      </Pressable>
    </View>
  );
}
 
function formatDate(iso: string): string {
  const d = new Date(iso);
  return d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
}

Not writing "your data is still here" during the soft state is intentional. The user can still use the app during grace, so emphasizing data retention only stirs up anxiety. I surface data retention only in the hard state, where "fix it and you're back" is the reassuring message to lead with. A single line moves the recovery rate, so this is worth A/B testing.

Three pitfalls that trip people up

Here are traps I actually hit while running this in production.

First, computing the expiration in local time. Always store graceUntil as UTC ISO8601 and convert to the device timezone only at the moment of display. If the date drifts between server and client, you'll cut access while the grace hasn't expired, or the reverse.

Second, missing the recovery notification out of hold. When a user fixes their card, Apple sends DID_RENEW and Google sends SUBSCRIPTION_RESTARTED (type 7). Forget to handle these recovery notifications and the user has paid again but access doesn't return — the worst kind of support ticket. Always handle the transition back to active.

Third, the difficulty of testing in Sandbox. Grace and hold rarely occur naturally outside production. Apple's Sandbox compresses the subscription period to minutes, so triggering a failure deliberately requires steps like disabling the payment method on the Sandbox account. Google lets you simulate grace and hold through license testers in the Play Console. Make sure your test plan includes "do the failure notifications actually arrive." Refund-driven lapses are also easy to confuse, so validate them alongside the implementation for detecting refunds and revoking entitlements.

Measure the recovery rate and refine the copy

Once it's shipped, track the impact with a single number. I watch the recovery rate: of users who entered grace or hold, the share that returned to active within 30 days. Knowing this gives you a basis for improving the banner copy and timing.

To measure it, record state transitions as events.

// Emit an event the moment the state changes (analytics backend is up to you)
function onEntitlementChange(prev: EntitlementState, next: EntitlementState) {
  if (prev === 'active' && (next === 'grace' || next === 'hold')) {
    track('billing_issue_entered', { from: prev, to: next });
  }
  if ((prev === 'grace' || prev === 'hold') && next === 'active') {
    track('billing_issue_recovered', { from: prev });
  }
}

Take the ratio of billing_issue_entered to billing_issue_recovered and you get the recovery rate. Recovery from hold is harder than from grace, so viewing them separately makes the value of the grace period show up clearly in the numbers.

A failed payment is not a lost customer — it's a recoverable one. Start by checking your own app: are you locking out failed-payment users on state === 'active' alone? Adding grace to that one line in canUsePremium is enough to reach revenue you have been quietly leaving on the table.