Use this page with AI

Copy this into your coding assistant and add your request.

Read https://openiap.dev/docs/lifecycle/subscription and https://openiap.dev/llms.txt. Follow the reading instructions, detailed reference, and linked guides relevant to my task before making changes.
Inspect my existing project and reuse its framework and conventions. Ask me for missing product decisions. Implement the requested behavior and run the applicable checks.
Show the working result, the commands and actual test results, and any remaining limitations. Keep your explanation brief.

My request: [describe what customers should be able to do]

Subscription

Understanding how subscriptions work on each platform is crucial for proper implementation. iOS and Android handle subscription data very differently, especially when it comes to renewal information.

Live example (full subscription flow — fetch, purchase, upgrade / downgrade, cancellation, restore): expo-iap · react-native-iap · flutter_inapp_purchase · kmp-iap

Android examples on this page describe Google Play. Community providers expose only the lifecycle data their store supplies and need that store's server verification. Installing a provider does not add its backend support to IAPKit.

Platform Comparison#

The key difference is where subscription information is available. iOS provides rich data client-side, while Android requires server-side calls for detailed information.

Information	iOS Client	Android Client	Server (Both)
Auto-renew status	✅ `willAutoRenew`	⚠️ `autoRenewingAndroid` (null when unavailable)	✅
Next renewal product	✅ `autoRenewPreference`	❌	✅
Pending upgrade/downgrade	✅ `pendingUpgradeProductId`	✅ `pendingPurchaseUpdateAndroid`	✅
Expiration reason	✅ `expirationReason`	❌	✅
Grace period status	✅ `gracePeriodExpirationDate`	❌	✅
Billing retry status	✅ `isInBillingRetry`	⚠️ `isSuspendedAndroid` (state only, no retry details)	✅
Renewal date	✅ `renewalDate`	❌	✅
Detailed subscription state	✅	❌	✅

💡 Key Takeaway

iOS: Rich client-side data via RenewalInfoIOS, but server validation is still recommended for production apps.

Android: client-side subscription lifecycle data is limited to autoRenewingAndroid, isSuspendedAndroid, and pendingPurchaseUpdateAndroid — the purchase itself still carries productId, purchaseToken, transactionDate, and purchaseState. Expiry and renewal dates and detailed subscription state require server-side validation. Store support varies; null renewal status means unknown, not cancelled. The required isAutoRenewing compatibility hint cannot represent unknown.

Both platforms: Use getActiveSubscriptions or getAvailablePurchases to verify purchases client-side, and implement server-side validation for authoritative subscription status.

Recommendation: Use IAPKit for server-side verification to get unified subscription data across both platforms—including all the iOS-only fields for Android subscriptions.

Purchase Verification#

Regardless of platform, you should verify purchases using OpenIAP's APIs. These APIs retrieve the latest subscription data from the store and provide a unified interface.

Client-Side Verification#

Use these APIs to check subscription status in your app:

getActiveSubscriptions: Returns only currently active subscriptions. Best for checking entitlements.
getAvailablePurchases: Returns the purchases the store still holds — owned non-consumables, active subscriptions, and unfinished transactions. It is not a purchase-history source on either platform. The framework SDKs default onlyIncludeActiveItemsIOS to true, so iOS reads Transaction.currentEntitlements; pass { onlyIncludeActiveItemsIOS: false } to read Transaction.all including expired and revoked entries. Android's queryPurchasesAsync returns only currently-owned purchases and has no equivalent option. For full iOS history use getAllTransactionsIOS.

These APIs query the store directly and return the latest data, including renewal information on iOS.

Server-Side Verification (Recommended)#

For production apps, implement server-side validation for authoritative subscription status:

iOS: App Store Server API + App Store Server Notifications V2
Android: Google Play Developer API + RTDN (Real-time Developer Notifications)

💡 Easy Server Verification with IAPKit

Setting up server-side verification can be complex. OpenIAP's hosted backend IAPKit provides a simple, unified API for server-side receipt validation across both iOS and Android platforms.

With IAPKit, you can verify purchases, manage subscriptions, and handle webhooks without building complex server infrastructure from scratch.

Learn more about IAPKit integration in our announcement.

⚠️ Why server-side validation?

Subscription Lifecycle#

This section shows how to handle subscription states throughout the app lifecycle. The flows apply to both iOS and Android unless noted.

On App Launch#

Check for existing subscriptions when the app starts. This handles purchases made while the app was closed.

1. initConnection()

2. getAvailablePurchases() → [PurchaseIOS]

3. For each purchase:

→ check purchaseState

→ validate with server

→ update local entitlements

→ finishTransaction() for unfinished transactions

Note: iOS transaction queue persists unfinished transactions

Android example

1. initConnection()

2. getAvailablePurchases() → [PurchaseAndroid]

3. For each purchase:

→ check purchaseState

→ check isAcknowledgedAndroid

→ validate with server

→ update local entitlements

→ finishTransaction() if not acknowledged

⚠️ Unacknowledged purchases auto-refund after 3 days

New Purchase Flow#

When a user initiates a new subscription purchase. Purchase states differ between platforms:

1. requestPurchase({ request: { apple: { sku } }, type: 'subs' }) → StoreKit payment sheet

2. purchaseUpdatedListener receives PurchaseIOS

→ validate → deliver → finishTransaction()

A delivered PurchaseIOS always carries purchaseState: 'purchased' — StoreKit only hands the listener completed transactions, so the pending and unknown members of the shared enum never appear on iOS. Anything that is not a completed purchase arrives through purchaseErrorListener instead: Ask to Buy and other deferred payments as ErrorCode.DeferredPayment ('deferred-payment'), cancellations as ErrorCode.UserCancelled.

Android example

1. requestPurchase({ request: { google: { skus } }, type: 'subs' }) → Google Play payment sheet

2. purchaseUpdatedListener receives PurchaseAndroid

3. Check purchaseState:

• purchased → validate → deliver → finishTransaction()

• pending → awaiting payment (slow payment methods)

• unknown → unrecognized state, handle defensively

These are the OpenIAP wire values. The underlying Play Billing constants are PURCHASED = 1, PENDING = 2, UNSPECIFIED = 0.

⚠️ Must acknowledge within 3 days or auto-refund

Checking Subscription Status#

Periodically verify subscription status, especially for subscription state changes:

1. getActiveSubscriptions() → [ActiveSubscription]

2. For each subscription:

• isActive = true → grant access

• check renewalInfoIOS for details:

- willAutoRenew = false → show renewal prompt

- isInBillingRetry = true → show payment issue

- pendingUpgradeProductId → show pending change

• check expirationDateIOS on the subscription → show expiry info

3. No active subscriptions → revoke access

Android example

1. getActiveSubscriptions() → [ActiveSubscription]

2. For each subscription:

• isActive = true → grant access

• check autoRenewingAndroid, currentPlanId / basePlanIdAndroid (limited client data)

3. No active subscriptions → revoke access

Note: For detailed status (expiry, grace period, etc.), use server-side Play Developer API

Detecting Cancellations#

Users can cancel subscriptions at any time. The subscription remains active until expiration.

Detection: willAutoRenew = false

User still has access:

• Until expirationDateIOS on ActiveSubscription

Actions:

→ Show "subscription ends on [expirationDateIOS]"

→ Offer re-subscribe option

→ Keep access until expiration

Android example

Renewal disabled: autoRenewingAndroid === false; null means unknown

User still has access:

• Until server-side expiryTime (not available client-side)

Actions:

→ Query server for exact expiry date

→ Offer re-subscribe option

→ Keep access until server confirms expiry

Handling Expiration#

When a subscription expires (cancelled + period ended), revoke access:

1. getActiveSubscriptions() returns empty or no matching product

2. Verify with server (recommended)

3. Revoke premium access

4. Show re-subscribe prompt

Restoring Purchases#

Users may need to restore subscriptions on new devices or after reinstalling:

1. User taps "Restore Purchases"

2. getAvailablePurchases() → [PurchaseIOS]

3. StoreKit fetches from Apple ID's purchase history

4. Validate each purchase with server

5. Grant access for valid subscriptions

6. finishTransaction() for each restored purchase

Note: iOS requires "Restore Purchases" button per App Store guidelines

Android example

1. User taps "Restore Purchases"

2. getAvailablePurchases() → [PurchaseAndroid]

3. Play Billing returns purchases for current Google account

4. Validate each purchaseToken with server

5. Server checks subscription status via Play Developer API

6. Grant access for active subscriptions

Note: Android ties purchases to Google account, auto-restored on same account

Example Scenario#

Understanding how subscription states change over time helps implement correct handling:

Timeline: Cancelled Subscription

Day 1: User cancels subscription

• Subscription still valid until Day 30 (billing period end)

• iOS: willAutoRenew = false

• Android: autoRenewingAndroid === false when reported; null means unknown

Day 15: User restores purchases

• getAvailablePurchases() returns the purchase (not expired)

• ✅ Grant access (still valid until Day 30)

Day 35: User restores purchases

• iOS: currentEntitlements returns empty (expired)

• Android: queryPurchases returns empty (expired)

• ✅ No access (correctly expired)

⚠️ The Refund Edge Case

When to Validate#

Server validation is needed at these key points:

After purchase — Verify the purchase is legitimate
On restore — Check current status (active/cancelled/refunded/expired)
Periodically for active subscriptions — Detect refunds and cancellations
On app launch — Sync subscription state with server

📝 iOS vs Android: Data Availability

iOS: You can get purchase data from Transaction.all (including expired ones), but there may be synchronization delays between devices. The client can check expiry/renewal info, but server validation is still recommended for security.

Android: Server-side validation is mandatory for subscription management. The client can't access expiry time — you must use Google Play Developer API to get subscription status, renewal dates, grace periods, etc. This is why server-side purchase history management is essential.

⚠️ Important Notes

Always finish transactions: Unfinished transactions will keep appearing on app launch. Call finishTransaction() after validation and content delivery.
Google Play 3-day window: Play purchases must be acknowledged within 3 days or they're automatically refunded.
Server validation: Client-side checks can be bypassed. Always validate with your server for authoritative subscription status.
Background renewals: Subscriptions renew when app isn't running. Use server notifications (RTDN for Android, App Store Server Notifications for iOS) to track real-time changes.

iOS Subscription Overview#

iOS provides rich subscription data client-side through StoreKit 2. The RenewalInfoIOS type contains detailed renewal information that lets you build subscription management UI without server calls. However, server validation is still recommended for production apps.

RenewalInfoIOS Fields#

This type is available on PurchaseIOS and ActiveSubscription via the renewalInfoIOS property:

willAutoRenew: Whether the subscription will automatically renew. If false, the user has cancelled but still has access until expiry.
autoRenewPreference: The product ID that will be used at the next renewal. If different from the current product, the user has scheduled a tier change.
pendingUpgradeProductId: Convenience field showing the pending tier change target. Calculated by comparing productId and autoRenewPreference.
renewalDate: Next renewal date (timestamp in milliseconds).
expirationReason: StoreKit's raw integer expiration-reason value represented as a string ("1", "2", …), not a symbolic name. Preserve unknown future values rather than mapping them to a fallback.
gracePeriodExpirationDate: Grace period end date if in grace period due to billing issues.
isInBillingRetry: Whether Apple is currently retrying a failed payment.
renewalOfferId / renewalOfferType: The offer applied to the next renewal. renewalOfferType carries values such as "PROMOTIONAL", "SUBSCRIPTION_OFFER_CODE", and "WIN_BACK".

Detecting Tier Changes (Upgrade/Downgrade)#

Understanding how tier changes work on iOS is crucial for proper subscription management. The behavior differs between upgrades and downgrades.

Upgrade Flow#

When a user upgrades (e.g., monthly → yearly), Apple processes the change immediately with a prorated refund for the remaining time on the old plan. However, the purchase data updates in stages:

Immediately after upgrade: The productId may still show the old tier (monthly), but autoRenewPreference shows the new tier (yearly). The pendingUpgradeProductId is set to the new tier.
After processing (few minutes): The productId updates to the new tier (yearly), and pendingUpgradeProductId becomes null since there's no longer a pending change.

📌 How to detect pending upgrades

Check pendingUpgradeProductId. If it has a value different from productId, there's a pending tier change:

pendingUpgradeProductId exists: Show UI indicating "Your subscription will change to [new tier]"
pendingUpgradeProductId is null: No pending change; the current productId is the active subscription

This logic is already calculated in pendingUpgradeProductId by comparing productId with autoRenewPreference.

Downgrade Flow#

Downgrades (e.g., yearly → monthly) are scheduled to take effect at the end of the current billing period:

productId: Shows current tier (yearly) - user keeps premium access
autoRenewPreference: Shows future tier (monthly)
pendingUpgradeProductId: Shows monthly (pending downgrade)

The user retains their current tier until expiry, then switches to the lower tier.

Other Subscription States#

Cancellation: isActive is true but willAutoRenew is false. User has access until expiration.
Grace Period: gracePeriodExpirationDate has a value. Billing failed but user still has access temporarily.
Billing Retry: isInBillingRetry is true. Apple is retrying the payment.

Server-Side Validation#

While iOS provides rich client-side data, server validation is still recommended:

App Store Server API: Verify subscription status and get transaction history
App Store Server Notifications V2: Receive real-time webhook events (renewals, cancellations, refunds, Family Sharing changes)

Server validation is especially important for cross-platform apps, fraud prevention, and accurate analytics.

getActiveSubscriptions - Get active subscriptions with renewal info
getAvailablePurchases - Get all purchases including expired
subscriptionStatusIOS - Get detailed subscription status
RenewalInfoIOS - Type reference

Android example

Android Subscription Overview#

Android's Play Billing Library takes a server-centric approach. Client-side data is intentionally limited, and detailed subscription information must be fetched from Google Play Developer API via your backend.

What's Available Client-Side#

The PurchaseAndroid object provides only basic information:

productId: The purchased product ID
purchaseToken: Token for server-side validation (key for all server API calls)
autoRenewingAndroid: Store-reported renewal status; null when unavailable. It does not prove entitlement or cancellation.
isSuspendedAndroid: Whether the subscription is suspended by a billing issue
pendingPurchaseUpdateAndroid: The product IDs and purchase token of an uncommitted plan change (Play Billing 5.0+)
transactionDate: Original purchase timestamp (Unix milliseconds)
purchaseState: purchased, pending, or unknown

What Requires Server API#

Unlike iOS where RenewalInfoIOS provides rich client-side data, the following information on Android is only available via Google Play Developer API:

Next renewal date / Expiration date
The effective date of a pending upgrade/downgrade — the pending change itself is on the client as pendingPurchaseUpdateAndroid
Expiration reason
Grace period status
Billing retry details (attempt counts, next retry time) — the billing-issue state itself is on the client as isSuspendedAndroid
Detailed subscription state (SUBSCRIPTION_STATE_ACTIVE, SUBSCRIPTION_STATE_CANCELED, SUBSCRIPTION_STATE_PAUSED, SUBSCRIPTION_STATE_ON_HOLD, SUBSCRIPTION_STATE_IN_GRACE_PERIOD, SUBSCRIPTION_STATE_EXPIRED, SUBSCRIPTION_STATE_PENDING, SUBSCRIPTION_STATE_PENDING_PURCHASE_CANCELED, SUBSCRIPTION_STATE_UNSPECIFIED)

Server-Side Requirements#

To build complete subscription management on Android, you need a backend that communicates with Google Play:

1. Google Play Developer API#

Use purchases.subscriptionsv2.get with the purchase token to get:

subscriptionState: Current state (SUBSCRIPTION_STATE_ACTIVE, SUBSCRIPTION_STATE_CANCELED, SUBSCRIPTION_STATE_IN_GRACE_PERIOD, SUBSCRIPTION_STATE_ON_HOLD, SUBSCRIPTION_STATE_PAUSED, SUBSCRIPTION_STATE_EXPIRED, SUBSCRIPTION_STATE_PENDING, SUBSCRIPTION_STATE_PENDING_PURCHASE_CANCELED, SUBSCRIPTION_STATE_UNSPECIFIED). SUBSCRIPTION_STATE_PENDING means the initial purchase has not completed; SUBSCRIPTION_STATE_PENDING_PURCHASE_CANCELED is a pending upgrade or downgrade that was cancelled — resolve the still-active subscription it belongs to through linkedPurchaseToken.
expiryTime: When the subscription expires
autoRenewEnabled: Whether auto-renewal is enabled
linkedPurchaseToken: Previous token if this is an upgrade/downgrade (links subscription history)
canceledStateContext: Cancellation details (user-initiated, system-initiated, developer-initiated)

2. Real-time Developer Notifications (RTDN)#

RTDN pushes subscription events to your server via Google Cloud Pub/Sub. Essential because subscription state can change without app interaction.

Key notification types:

SUBSCRIPTION_PURCHASED (4): New subscription or deferred change took effect
SUBSCRIPTION_RENEWED (2): Successful renewal
SUBSCRIPTION_CANCELED (3): User cancelled (still active until expiry)
SUBSCRIPTION_EXPIRED (13): Subscription expired
SUBSCRIPTION_IN_GRACE_PERIOD (6): Billing failed, grace period started
SUBSCRIPTION_ON_HOLD (5): Account hold after the grace period ended — entitlement suspended (distinct from the user-initiated PAUSED state)
SUBSCRIPTION_RECOVERED (1): Billing retry succeeded
SUBSCRIPTION_REVOKED (12): Access revoked (refund, etc.)

📝 Setting up RTDN

Recommended Architecture#

The typical flow for Android subscription management:

App completes purchase: Receives purchaseToken from Play Billing
App sends token to your server: Backend validates the purchase
Server calls Play Developer API: Fetches detailed subscription status
Server returns status to app: App displays subscription info
RTDN updates server: When subscription state changes, server is notified
App refreshes from server: Periodically or on app launch

⚠️ Why this architecture?

Google designed Play Billing server-centric for several reasons:

Client-side data can be manipulated; server-side is authoritative
Subscription state can change without app interaction (renewals, cancellations via Play Store)
RTDN ensures real-time updates even when app isn't running

For an iOS-like client experience on Android, build a backend that syncs with Google Play and caches subscription status.

Handling Tier Changes#

Upgrades/Downgrades#

The client exposes the pending change itself via pendingPurchaseUpdateAndroid (the new product IDs and purchase token), but its effective date and linkage still come from the server:

DEFERRED mode: Change is scheduled but not reflected in client data. Track in your backend.
linkedPurchaseToken: Server API returns this to link old and new subscriptions.
RTDN: Receives SUBSCRIPTION_PURCHASED when deferred change takes effect.

See Subscription Upgrade/Downgrade for implementation details.

Cancellations#

Google Play can report renewal disabled through autoRenewingAndroid === false. A null value means unknown; do not infer cancellation from the legacy isAutoRenewing hint. For cancellation details (when, why, by whom), use the Google Play server API's canceledStateContext. Other stores require their own server verification.

getActiveSubscriptions - Get active subscriptions (limited data)
getAvailablePurchases - Get all purchases including subscriptions
Google RTDN Reference - Real-time developer notifications
Google Play Developer API - Server-side subscription validation

Summary#

iOS

Rich client-side data via RenewalInfoIOS
Use pendingUpgradeProductId for tier change detection
Server-side recommended for production apps
App Store Server Notifications V2 for webhooks

Android

Client-side subscription lifecycle data limited to autoRenewingAndroid, isSuspendedAndroid, and pendingPurchaseUpdateAndroid
Null renewal status means unknown, not cancelled
Server-side required for detailed subscription info
Use Google Play Developer API for authoritative data
RTDN for real-time subscription updates

🔗 Related Documentation

Subscription

Platform Comparison#

Purchase Verification#

Client-Side Verification#

Server-Side Verification (Recommended)#

Subscription Lifecycle#

On App Launch#

New Purchase Flow#

Checking Subscription Status#

Detecting Cancellations#

Handling Expiration#

Restoring Purchases#

Example Scenario#

When to Validate#

iOS Subscription Overview#

RenewalInfoIOS Fields#

Detecting Tier Changes (Upgrade/Downgrade)#

Upgrade Flow#

Downgrade Flow#

Other Subscription States#

Server-Side Validation#

Related APIs#

Summary#

iOS

Android