Subscription Recovery Architecture for iOS and Android

---
title: "Subscription Recovery Architecture: iOS & Android"
published: true
description: "Build a server-side webhook pipeline that processes Apple and Google billing retry events, manages grace period state machines, and recovers ~15% of involuntary churn."
tags: kotlin, android, ios, mobile
canonical_url: https://blog.mvp-factory.com/subscription-recovery-architecture-ios-android
---

## What we are building

Let me show you a pattern I use in every project that handles subscriptions: a unified server-side webhook pipeline that catches failed payments before they become lost customers.

Involuntary churn — expired cards, insufficient funds, billing errors — accounts for 20–40% of all subscription cancellations. The user *wanted* to stay subscribed. Their payment just failed. By building an idempotent event pipeline that processes Apple and Google billing retry webhooks, manages grace period state machines, and triggers coordinated re-engagement notifications, you can recover roughly 15% of that lost revenue.

We will walk through the state machine, the webhook ingestion layer, the notification strategy, and the entitlement logic. Working Kotlin snippets included.

## Prerequisites

- A backend service (Kotlin/Spring used here, but the architecture applies anywhere)
- Apple App Store Server Notifications V2 configured
- Google Play Real-Time Developer Notifications (RTDN) via Cloud Pub/Sub
- A persistence layer for event deduplication
- Push notification and email delivery infrastructure

## Step 1: Understand the webhook event taxonomy

Here is the gotcha that will save you hours: Apple and Google webhooks are **not** interchangeable. The event naming, timing, and retry semantics differ in ways that will bite you.

| Lifecycle Stage | Apple (V2 Notifications) | Google Play (RTDN) |
|---|---|---|
| Payment fails | `DID_FAIL_TO_RENEW` | `SUBSCRIPTION_IN_BILLING_RETRY_PERIOD` |
| Grace period active | `subtype: GRACE_PERIOD` | `SUBSCRIPTION_IN_GRACE_PERIOD` |
| Account hold begins | N/A (Apple uses billing retry) | `SUBSCRIPTION_ON_HOLD` |
| Recovery succeeds | `DID_RENEW` | `SUBSCRIPTION_RECOVERED` |
| Final expiration | `EXPIRED` (subtype: `BILLING_RETRY_PERIOD`) | `SUBSCRIPTION_EXPIRED` |

Apple's grace period lasts 6 or 16 days depending on billing cycle. Google offers a configurable grace period (default 3–7 days) plus an additional account hold period of up to 30 days. This asymmetry matters a lot for your state machine design.

## Step 2: Define the unified state machine

Your entitlement service needs a single subscription state that abstracts over both platforms:

kotlin
enum class SubscriptionState {
ACTIVE,
GRACE_PERIOD, // Payment failed, user retains access
BILLING_RETRY, // Past grace, platform retrying (Google: account hold)
EXPIRED, // All recovery attempts exhausted
RECOVERED // Transient state → transitions to ACTIVE
}

The key architectural decision: users retain full access during `GRACE_PERIOD` and degraded or no access during `BILLING_RETRY`. Apple *requires* you to maintain access during their grace period if you opt in.

## Step 3: Build the idempotent event pipeline

Here is the minimal setup to get this working. Both Apple and Google retry delivery on failure, and network issues cause duplicates. Your ingestion layer must handle this:

kotlin
@PostMapping("/webhooks/apple")
suspend fun handleAppleNotification(@RequestBody payload: SignedPayload) {
val notification = appleJWSVerifier.verify(payload)
val eventId = notification.notificationUUID

// Idempotency check — deduplicate on event ID
if (eventStore.exists(eventId)) {
    return ResponseEntity.ok().build()
}

eventStore.save(
    ProcessedEvent(
        id = eventId,
        platform = Platform.APPLE,
        type = notification.notificationType,
        originalTransactionId = notification.data.transactionInfo.originalTransactionId,
        processedAt = Instant.now()
    )
)

subscriptionStateMachine.transition(notification)

}

Critical implementation details:

1. **Return 2xx immediately** after persisting the raw event, then process asynchronously. Apple retries with exponential backoff for up to 72 hours on non-2xx responses. Google retries for up to 3 days.
2. **Verify signatures.** Apple V2 notifications are JWS-signed. Google RTDN messages come through Cloud Pub/Sub with built-in authentication. Never process unverified payloads.
3. **Use platform transaction IDs** as your correlation key: `originalTransactionId` for Apple, `purchaseToken` for Google.

## Step 4: Wire up the retry notification strategy

The docs do not mention this, but passive webhook processing alone is not enough. You need an active notification strategy coordinated with the platform's own retry schedule:

plaintext
Grace Period Day 1 → Push: "Your payment failed — update your card to keep access"
Grace Period Day 3 → Email: "You're about to lose access to [Premium Feature]"
Billing Retry Day 1 → Push: "Your subscription is paused — tap to restore"
Billing Retry Day 7 → Email: "We miss you — here's a direct link to update payment"

This four-touch sequence across push and email recovers approximately 12–18% of billing failures that would otherwise churn. The median across multiple apps sits around 15%.

Both platforms support deep linking directly to payment update screens — `StoreKit.AppStore.showManageSubscriptions(in:)` on iOS and `https://play.google.com/store/account/subscriptions` with your package name and SKU on Android. Reducing friction from notification to payment update is the biggest single win in this pipeline.

## Step 5: Coordinate entitlement access

Your entitlement check becomes a function of the state machine, not a simple boolean:

kotlin
fun resolveAccess(subscription: Subscription): AccessLevel = when (subscription.state) {
ACTIVE, RECOVERED -> AccessLevel.FULL
GRACE_PERIOD -> AccessLevel.FULL // Required by Apple if opted in
BILLING_RETRY -> AccessLevel.DEGRADED // Show upgrade prompts
EXPIRED -> AccessLevel.NONE
}

The `DEGRADED` state during billing retry is worth thinking about. Show the user what they are missing without fully locking them out. This converts better than a hard paywall because the user did not *choose* to leave.

## Gotchas

- **Do not treat Apple and Google webhooks as identical.** Platform-specific `if/else` branches scattered through your codebase lead to bugs you will not catch until they cost you money. Build a normalization layer.
- **Webhook delivery is at-least-once, not exactly-once.** Without deduplication on event IDs, you will hit data integrity issues. The idempotency check is not optional.
- **Monitor your recovery rate** (percentage of billing failures that resolve to recovered), grace period conversion, webhook processing lag (p95), and duplicate event rate. Without these metrics, you have no visibility into how much revenue your pipeline is saving.
- **Apple's grace period opt-in carries obligations.** If you enable it, you *must* maintain full access during the grace window. Do not half-commit to this.

## Wrapping up

The architecture boils down to three things: a unified state machine that normalizes Apple and Google billing states, an idempotent event pipeline that handles at-least-once delivery, and a time-sequenced notification strategy that actively converts failed payments. The state machine and pipeline are the plumbing. The notification sequence is where the 15% recovery rate comes from.

If you are starting from scratch, invest in the normalization layer and observability from day one. Your future self will thank you when a billing edge case surfaces at 2 AM.

- [Apple App Store Server Notifications V2](https://developer.apple.com/documentation/appstoreservernotifications)
- [Google Play Real-Time Developer Notifications](https://developer.android.com/google/play/billing/rtdn-reference)