diff --git a/docs/docs/api/methods/listeners.md b/docs/docs/api/methods/listeners.md
index b8205b80e..5dc440149 100644
--- a/docs/docs/api/methods/listeners.md
+++ b/docs/docs/api/methods/listeners.md
@@ -379,19 +379,14 @@ For simpler usage, consider using the `useIAP` hook which automatically manages
 import {useIAP} from 'react-native-iap';
 
 export default function StoreComponent() {
-  const {currentPurchase, currentPurchaseError} = useIAP();
-
-  useEffect(() => {
-    if (currentPurchase) {
-      handlePurchaseUpdate(currentPurchase);
-    }
-  }, [currentPurchase]);
-
-  useEffect(() => {
-    if (currentPurchaseError) {
-      handlePurchaseError(currentPurchaseError);
-    }
-  }, [currentPurchaseError]);
+  const {/* other props */} = useIAP({
+    onPurchaseSuccess: async (purchase) => {
+      await handlePurchaseUpdate(purchase);
+    },
+    onPurchaseError: (error) => {
+      handlePurchaseError(error);
+    },
+  });
 
   // Rest of component
 }
diff --git a/docs/docs/api/use-iap.md b/docs/docs/api/use-iap.md
index b67e8b948..9ea031033 100644
--- a/docs/docs/api/use-iap.md
+++ b/docs/docs/api/use-iap.md
@@ -23,9 +23,8 @@ import {useIAP} from 'react-native-iap';
 The `useIAP` hook follows React Hooks conventions and differs from calling functions directly from `react-native-iap` (index exports):
 
 - **Automatic connection**: Automatically calls `initConnection` on mount and `endConnection` on unmount.
-- **Void-returning methods**: Methods like `fetchProducts`, `requestPurchase`, `getAvailablePurchases`, etc. return `Promise<void>` in the hook. They do not resolve to data. Instead, they update internal state exposed by the hook: `products`, `subscriptions`, `availablePurchases`, `currentPurchase`, etc.
-- **Don’t await for data**: When using the hook, do not write `const x = await fetchProducts(...)`. Call the method, then read the corresponding state from the hook.
-- **Prefer callbacks over `currentPurchase`**: `currentPurchase` was historically useful for debugging and migration, but for new code you should rely on `onPurchaseSuccess` and `onPurchaseError` options passed to `useIAP`.
+- **Void-returning methods**: Methods like `fetchProducts`, `requestPurchase`, `getAvailablePurchases`, etc. return `Promise<void>` in the hook. They do not resolve to data. Instead, they update internal state exposed by the hook: `products`, `subscriptions`, `availablePurchases`, etc.
+- **Don't await for data**: When using the hook, do not write `const x = await fetchProducts(...)`. Call the method, then read the corresponding state from the hook.
 
 ## Basic Usage
 
@@ -35,8 +34,6 @@ const {
   products,
   subscriptions,
   availablePurchases,
-  currentPurchase, // Debugging/migration friendly; prefer callbacks
-  currentPurchaseError, // Debugging/migration friendly; prefer callbacks
   fetchProducts,
   requestPurchase,
   validateReceipt,
@@ -144,19 +141,6 @@ interface UseIAPOptions {
   ));
   ```
 
-#### currentPurchase
-
-- **Type**: `Purchase | null`
-- **Description**: Last purchase event captured by the hook. This value is primarily helpful for debugging and migration. For production flows, prefer handling purchase results via `onPurchaseSuccess` and errors via `onPurchaseError` passed to `useIAP`.
-- **Example (debug logging only)**:
-
-  ```tsx
-  useEffect(() => {
-    if (currentPurchase) {
-      console.log('Debug purchase event:', currentPurchase.id);
-    }
-  }, [currentPurchase]);
-  ```
 
 #### currentPurchaseError
 
@@ -235,7 +219,7 @@ interface UseIAPOptions {
   ```tsx
   const buyProduct = async (productId: string) => {
     try {
-      // In hook: returns void. Listen via callbacks or `currentPurchase`.
+      // In hook: returns void. Listen via callbacks.
       await requestPurchase({
         request: {
           ios: {sku: productId},
diff --git a/docs/docs/examples/available-purchases.md b/docs/docs/examples/available-purchases.md
index f35f04ad7..a32afc37f 100644
--- a/docs/docs/examples/available-purchases.md
+++ b/docs/docs/examples/available-purchases.md
@@ -10,11 +10,11 @@ import AdFitTopFixed from "@site/src/uis/AdFitTopFixed";
 
 <AdFitTopFixed />
 
-This example shows how to list and restore previously purchased items (non‑consumables and active subscriptions) using `getAvailablePurchases()` and `getActiveSubscriptions()`.
+This guide demonstrates how to list and restore previously purchased items (non‑consumables and active subscriptions) using `getAvailablePurchases()` and `getActiveSubscriptions()`.
 
-View the full example source:
-
-- GitHub: https://github.com/hyochan/react-native-iap/blob/main/example/app/available-purchases.tsx
+:::note
+The complete working example can be found at [example/screens/AvailablePurchases.tsx](https://github.com/hyochan/react-native-iap/blob/main/example/screens/AvailablePurchases.tsx). Note that the example code was heavily vibe-coded with Claude and is quite verbose/messy for demonstration purposes - use it as a reference only.
+:::
 
 ## Restore Flow
 
diff --git a/docs/docs/examples/offer-code.md b/docs/docs/examples/offer-code.md
index 561ec6709..d3f040c6e 100644
--- a/docs/docs/examples/offer-code.md
+++ b/docs/docs/examples/offer-code.md
@@ -10,11 +10,11 @@ import AdFitTopFixed from "@site/src/uis/AdFitTopFixed";
 
 <AdFitTopFixed />
 
-Redeem App Store offer/promo codes using the native iOS sheet. This is useful for subscription promotional codes and requires a real iOS device.
+This guide demonstrates how to redeem App Store offer/promo codes using the native iOS sheet. This is useful for subscription promotional codes and requires a real iOS device.
 
-View the full example source:
-
-- GitHub: https://github.com/hyochan/react-native-iap/blob/main/example/app/offer-code.tsx
+:::note
+The complete working example can be found at [example/screens/OfferCode.tsx](https://github.com/hyochan/react-native-iap/blob/main/example/screens/OfferCode.tsx). Note that the example code was heavily vibe-coded with Claude and is quite verbose/messy for demonstration purposes - use it as a reference only.
+:::
 
 ## Usage
 
diff --git a/docs/docs/examples/purchase-flow.md b/docs/docs/examples/purchase-flow.md
index 5ee8831da..ed6e13ceb 100644
--- a/docs/docs/examples/purchase-flow.md
+++ b/docs/docs/examples/purchase-flow.md
@@ -10,11 +10,11 @@ import AdFitTopFixed from "@site/src/uis/AdFitTopFixed";
 
 <AdFitTopFixed />
 
-This example walks through a clean purchase flow using react-native-iap with the `useIAP` hook and the new platform‑specific request shape. It mirrors the working sample in `example/app/purchase-flow.tsx`.
+This guide demonstrates a clean purchase flow using react-native-iap with the `useIAP` hook and the new platform‑specific request shape.
 
-View the full example source:
-
-- GitHub: [example/app/purchase-flow.tsx](https://github.com/hyochan/react-native-iap/blob/main/example/app/purchase-flow.tsx)
+:::note
+The complete working example can be found at [example/screens/PurchaseFlow.tsx](https://github.com/hyochan/react-native-iap/blob/main/example/screens/PurchaseFlow.tsx). Note that the example code was heavily vibe-coded with Claude and is quite verbose/messy for demonstration purposes - use it as a reference only.
+:::
 
 ## Flow Overview
 
diff --git a/docs/docs/examples/subscription-flow.md b/docs/docs/examples/subscription-flow.md
index 32f84c6d3..6ad02001d 100644
--- a/docs/docs/examples/subscription-flow.md
+++ b/docs/docs/examples/subscription-flow.md
@@ -12,806 +12,618 @@ import AdFitTopFixed from "@site/src/uis/AdFitTopFixed";
 
 <AdFitTopFixed />
 
-This example walks through a practical subscriptions flow with react-native-iap. It mirrors the working sample in `example/app/subscription-flow.tsx`, including status checks, renewal handling, and subscription management UI.
+This guide demonstrates practical subscription scenarios with react-native-iap.
 
-View the full example source:
+:::note
+The complete working example can be found at [example/screens/SubscriptionFlow.tsx](https://github.com/hyochan/react-native-iap/blob/main/example/screens/SubscriptionFlow.tsx). Note that the example code was heavily vibe-coded with Claude and is quite verbose/messy for demonstration purposes - use it as a reference only.
+:::
 
-- GitHub: [example/app/subscription-flow.tsx](https://github.com/hyochan/react-native-iap/blob/main/example/app/subscription-flow.tsx)
+## 1. Purchasing a Subscription with `requestPurchase`
 
-## Important: Platform-Specific Subscription Properties
-
-When checking subscription status, different platforms provide different properties:
-
-### iOS Subscription Properties
-
-- **`expirationDateIos`**: Unix timestamp (milliseconds) indicating when the subscription expires
-- **`originalTransactionDateIos`**: Original purchase date
-- **`environmentIos`**: Can be 'Production' or 'Sandbox' (useful for testing)
-
-### Android Subscription Properties
-
-- **`autoRenewingAndroid`**: Boolean indicating if the subscription will auto-renew
-- **`purchaseStateAndroid`**: Purchase state (0 = purchased, 1 = canceled)
-- **`obfuscatedAccountIdAndroid`**: Account identifier if provided during purchase
-
-### Key Differences
-
-- **iOS**: You must check `expirationDateIos` against current time to determine if active
-- **Android**: You can check `autoRenewingAndroid` - if false, the user has canceled
-
-⚠️ **Note**: Always validate subscription status on your server for production apps. Client-side checks are useful for UI updates but should not be the sole source of truth.
-
-## Complete Subscription Flow
-
-View the full example source:
-
-- GitHub: [example/app/subscription-flow.tsx](https://github.com/hyochan/react-native-iap/blob/main/example/app/subscription-flow.tsx)
+### Basic Subscription Purchase
 
 ```tsx
-import React, {useEffect, useState} from 'react';
-import {
-  View,
-  Text,
-  TouchableOpacity,
-  Alert,
-  StyleSheet,
-  ScrollView,
-  ActivityIndicator,
-  Platform,
-} from 'react-native';
 import {useIAP} from 'react-native-iap';
+import {Platform} from 'react-native';
 
-// Subscription product IDs
-const SUBSCRIPTION_SKUS = [
-  'com.yourapp.premium_monthly',
-  'com.yourapp.premium_yearly',
-];
-
-interface SubscriptionStatus {
-  isActive: boolean;
-  productId?: string;
-  expirationDate?: Date;
-  autoRenewing?: boolean;
-  inGracePeriod?: boolean;
-}
-
-export default function SubscriptionManager() {
+function SubscriptionPurchase() {
   const {
     connected,
     subscriptions,
-    currentPurchase,
-    currentPurchaseError,
-    fetchProducts,
-    getAvailablePurchases,
     requestPurchase,
-    finishTransaction,
+    fetchProducts,
   } = useIAP();
 
-  const [loading, setLoading] = useState(false);
-  const [subscriptionStatus, setSubscriptionStatus] =
-    useState<SubscriptionStatus>({
-      isActive: false,
-    });
-
-  // Initialize and load subscriptions
   useEffect(() => {
+    // Load subscription products
     if (connected) {
-      loadSubscriptions();
-      checkSubscriptionStatus();
+      fetchProducts({
+        skus: ['com.app.premium_monthly', 'com.app.premium_yearly'],
+        type: 'subs',
+      });
     }
   }, [connected]);
 
-  // Handle subscription purchases
-  useEffect(() => {
-    if (currentPurchase) {
-      handleSubscriptionPurchase(currentPurchase);
-    }
-  }, [currentPurchase]);
-
-  // Handle purchase errors
-  useEffect(() => {
-    if (currentPurchaseError) {
-      handlePurchaseError(currentPurchaseError);
+  const purchaseSubscription = async (productId: string) => {
+    if (!connected) {
+      Alert.alert('Error', 'Store not connected');
+      return;
     }
-  }, [currentPurchaseError]);
 
-  const loadSubscriptions = async () => {
     try {
-      setLoading(true);
-      await fetchProducts({skus: SUBSCRIPTION_SKUS, type: 'subs'});
-      console.log('Subscriptions loaded');
-    } catch (error) {
-      console.error('Failed to load subscriptions:', error);
-      Alert.alert('Error', 'Failed to load subscription options');
-    } finally {
-      setLoading(false);
-    }
-  };
+      // Find the subscription product
+      const subscription = subscriptions.find(sub => sub.id === productId);
+      if (!subscription) {
+        throw new Error('Subscription not found');
+      }
 
-  const checkSubscriptionStatus = async () => {
-    try {
-      // In hook: updates state, does not return purchases
-      await getAvailablePurchases();
-      const activeSubscription = findActiveSubscription(availablePurchases);
+      // Platform-specific purchase request
+      await requestPurchase({
+        request: {
+          ios: {
+            sku: productId,
+            andDangerouslyFinishTransactionAutomatically: false,
+          },
+          android: {
+            skus: [productId],
+            // Android requires subscriptionOffers for subscriptions
+            subscriptionOffers: subscription.subscriptionOfferDetailsAndroid
+              ?.map(offer => ({
+                sku: subscription.id,
+                offerToken: offer.offerToken,
+              })) || [],
+          },
+        },
+        type: 'subs',
+      });
+
+      // Success handling is done in onPurchaseSuccess callback
 
-      if (activeSubscription) {
-        const status = await validateSubscriptionStatus(activeSubscription);
-        setSubscriptionStatus(status);
-      } else {
-        setSubscriptionStatus({isActive: false});
-      }
     } catch (error) {
-      console.error('Failed to check subscription status:', error);
+      console.error('Purchase failed:', error);
+      Alert.alert('Error', 'Failed to purchase subscription');
     }
   };
 
-  const findActiveSubscription = (purchases) => {
-    // Find subscriptions and check if they're still active
-    return purchases.find((purchase) => {
-      if (!SUBSCRIPTION_SKUS.includes(purchase.productId)) {
-        return false;
-      }
-      // Check if the subscription is still active
-      return isSubscriptionActive(purchase);
-    });
-  };
+  return (
+    <View>
+      {subscriptions.map(sub => (
+        <TouchableOpacity
+          key={sub.id}
+          onPress={() => purchaseSubscription(sub.id)}
+        >
+          <Text>{sub.title} - {sub.localizedPrice}</Text>
+        </TouchableOpacity>
+      ))}
+    </View>
+  );
+}
+```
 
-  /**
-   * Platform-specific subscription status checking
-   * iOS: Uses expirationDateIos to check if subscription is expired
-   * Android: Uses autoRenewingAndroid to check renewal status
-   */
-  const isSubscriptionActive = (purchase) => {
-    const currentTime = Date.now();
-
-    // Check platform-specific subscription properties
-    if (Platform.OS === 'ios') {
-      // iOS: Check expiration date
-      if (purchase.expirationDateIos) {
-        console.log(
-          'iOS Subscription expiration:',
-          new Date(purchase.expirationDateIos).toISOString(),
-        );
-        return purchase.expirationDateIos > currentTime;
-      }
+### Handling Purchase Success with Hook Callbacks
 
-      // For sandbox/development environment
-      if (purchase.environmentIOS === 'Sandbox') {
-        console.log('iOS Sandbox environment detected');
-        // In sandbox, also check if it's a recent purchase (within 24 hours)
-        const dayInMs = 24 * 60 * 60 * 1000;
-        if (
-          purchase.transactionDate &&
-          currentTime - purchase.transactionDate < dayInMs
-        ) {
-          return true;
-        }
-      }
-    } else if (Platform.OS === 'android') {
-      // Android: Check auto-renewing status
-      if (purchase.autoRenewingAndroid !== undefined) {
-        console.log(
-          'Android auto-renewing status:',
-          purchase.autoRenewingAndroid,
-        );
-        return purchase.autoRenewingAndroid;
-      }
+```tsx
+function SubscriptionManager() {
+  const [activeSubscription, setActiveSubscription] = useState(null);
 
-      // Fallback: Check if purchase is recent (within 30 days for monthly subscriptions)
-      const monthInMs = 30 * 24 * 60 * 60 * 1000;
-      if (
-        purchase.transactionDate &&
-        currentTime - purchase.transactionDate < monthInMs
-      ) {
-        return true;
-      }
-    }
+  const {
+    connected,
+    subscriptions,
+    requestPurchase,
+    finishTransaction,
+  } = useIAP({
+    onPurchaseSuccess: async (purchase) => {
+      console.log('Purchase successful:', purchase.productId);
 
-    // If we can't determine status, assume inactive
-    return false;
-  };
+      // Validate with your server
+      const isValid = await validatePurchaseOnServer(purchase);
 
-  const validateSubscriptionStatus = async (purchase) => {
-    try {
-      // Validate subscription on your server
-      const response = await fetch(
-        'https://your-server.com/validate-subscription',
-        {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify({
-            productId: purchase.productId,
-            purchaseToken: purchase.purchaseToken, // Unified field (iOS: JWS, Android: purchaseToken)
-            packageName: (purchase as PurchaseAndroid)?.packageNameAndroid, // Will be needed in android
-          }),
-        },
-      );
+      if (isValid) {
+        // Update local state
+        setActiveSubscription(purchase.productId);
 
-      const result = await response.json();
+        // Finish the transaction
+        await finishTransaction({purchase});
 
-      return {
-        isActive: result.isActive,
-        productId: purchase.productId,
-        expirationDate: new Date(result.expirationDate),
-        autoRenewing: result.autoRenewing,
-        inGracePeriod: result.inGracePeriod,
-      };
-    } catch (error) {
-      console.error('Subscription validation error:', error);
-      return {isActive: false};
-    }
+        Alert.alert('Success', 'Subscription activated!');
+      }
+    },
+    onPurchaseError: (error) => {
+      if (error.code !== 'E_USER_CANCELLED') {
+        Alert.alert('Error', error.message);
+      }
+    },
+  });
+
+  // Purchase function remains simple
+  const subscribe = async (productId: string) => {
+    const subscription = subscriptions.find(s => s.id === productId);
+    if (!subscription) return;
+
+    await requestPurchase({
+      request: {
+        ios: {
+          sku: productId,
+          andDangerouslyFinishTransactionAutomatically: false,
+        },
+        android: {
+          skus: [productId],
+          subscriptionOffers: subscription.subscriptionOfferDetailsAndroid
+            ?.map(offer => ({
+              sku: subscription.id,
+              offerToken: offer.offerToken,
+            })) || [],
+        },
+      },
+      type: 'subs',
+    });
+    // Don't handle success here - use onPurchaseSuccess callback
   };
+}
+```
 
-  const handleSubscriptionPurchase = async (purchase) => {
-    try {
-      console.log('Processing subscription purchase:', purchase.productId);
-
-      // Validate the subscription purchase
-      const subscriptionInfo = await validateSubscriptionStatus(purchase);
+## 2. Checking Subscription Status with `getActiveSubscriptions`
 
-      if (subscriptionInfo.isActive) {
-        // Grant subscription benefits
-        await grantSubscriptionBenefits(purchase);
+### Basic Status Check After Purchase
 
-        // Update local status
-        setSubscriptionStatus(subscriptionInfo);
+```tsx
+import {useIAP} from 'react-native-iap';
+import {Platform} from 'react-native';
 
-        // Finish the transaction
-        await finishTransaction({purchase});
+function useSubscriptionStatus() {
+  const {getActiveSubscriptions} = useIAP();
+  const [isSubscribed, setIsSubscribed] = useState(false);
+  const [subscriptionDetails, setSubscriptionDetails] = useState(null);
 
-        Alert.alert(
-          'Subscription Activated',
-          `Welcome to Premium! Your subscription is now active.`,
-        );
+  const checkSubscriptionStatus = async () => {
+    try {
+      // Get active subscriptions - returns array of active subscriptions
+      const activeSubscriptions = await getActiveSubscriptions();
+
+      if (activeSubscriptions.length > 0) {
+        // User has at least one active subscription
+        setIsSubscribed(true);
+
+        // Check specific subscription details
+        const subscription = activeSubscriptions[0];
+
+        // Platform-specific status checks
+        if (Platform.OS === 'ios') {
+          // iOS provides expirationDateIos
+          const isExpired = subscription.expirationDateIos < Date.now();
+          setSubscriptionDetails({
+            productId: subscription.productId,
+            isActive: !isExpired,
+            expiresAt: new Date(subscription.expirationDateIos),
+            environment: subscription.environmentIOS, // 'Production' or 'Sandbox'
+          });
+        } else {
+          // Android provides autoRenewingAndroid
+          setSubscriptionDetails({
+            productId: subscription.productId,
+            isActive: subscription.autoRenewingAndroid,
+            willAutoRenew: subscription.autoRenewingAndroid,
+            purchaseState: subscription.purchaseStateAndroid, // 0 = purchased, 1 = canceled
+          });
+        }
       } else {
-        Alert.alert('Error', 'Subscription validation failed');
+        setIsSubscribed(false);
+        setSubscriptionDetails(null);
       }
     } catch (error) {
-      console.error('Error processing subscription:', error);
-      Alert.alert('Error', 'Failed to activate subscription');
+      console.error('Failed to check subscription status:', error);
     }
   };
 
-  const handlePurchaseError = (error) => {
-    console.error('Subscription purchase error:', error);
+  return {isSubscribed, subscriptionDetails, checkSubscriptionStatus};
+}
+```
 
-    switch (error.code) {
-      case 'E_USER_CANCELLED':
-        // User cancelled - no action needed
-        break;
-      case 'E_ALREADY_OWNED':
-        Alert.alert(
-          'Already Subscribed',
-          'You already have an active subscription. Check your subscription status.',
-        );
-        checkSubscriptionStatus(); // Refresh status
-        break;
-      default:
-        Alert.alert(
-          'Subscription Failed',
-          error.message || 'Unknown error occurred',
-        );
-        break;
-    }
-  };
+### Checking Multiple Subscription Tiers
 
-  const grantSubscriptionBenefits = async (purchase) => {
-    try {
-      // Grant subscription benefits on your server
-      await fetch('https://your-server.com/grant-subscription', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({
-          userId: 'current-user-id',
-          productId: purchase.productId,
-          transactionId: purchase.transactionId,
-        }),
-      });
+```tsx
+const SUBSCRIPTION_SKUS = {
+  BASIC: 'com.app.basic_monthly',
+  PREMIUM: 'com.app.premium_monthly',
+  PREMIUM_YEARLY: 'com.app.premium_yearly',
+};
 
-      console.log('Subscription benefits granted');
-    } catch (error) {
-      console.error('Failed to grant subscription benefits:', error);
-      throw error;
-    }
-  };
+async function getUserSubscriptionTier() {
+  const {getActiveSubscriptions} = useIAP();
 
-  /**
-   * Platform-Specific Subscription Purchase Options
-   *
-   * Android: Requires subscriptionOffers array with offer tokens from fetchProducts()
-   * subscriptionOffers: Array of AndroidSubscriptionOfferInput objects containing sku and offerToken
-   * Each offer token corresponds to a specific pricing plan (base plan, introductory offer, etc.)
-   * Without subscriptionOffers, Android purchases will fail with "number of skus (1) must match: the number of offerTokens (0)"
-   *
-   * iOS: Optional withOffer for promotional discounts
-   * withOffer: DiscountOfferInputIOS object for applying promotional offers
-   * Includes offerIdentifier, keyIdentifier, nonce, signature, and timestamp
-   * Only needed when applying specific promotional offers to the purchase
-   */
-  const purchaseSubscription = async (productId) => {
-    if (!connected) {
-      Alert.alert('Error', 'Store is not connected');
-      return;
-    }
+  try {
+    const activeSubscriptions = await getActiveSubscriptions();
 
-    try {
-      console.log('Requesting subscription:', productId);
+    // Check for premium yearly first (highest tier)
+    const yearlyPremium = activeSubscriptions.find(
+      sub => sub.productId === SUBSCRIPTION_SKUS.PREMIUM_YEARLY
+    );
+    if (yearlyPremium) return 'PREMIUM_YEARLY';
 
-      // Find the subscription product to get offer details
-      const subscription = subscriptions.find((sub) => sub.id === productId);
-      if (!subscription) {
-        Alert.alert('Error', 'Subscription product not found');
-        return;
-      }
+    // Then check monthly premium
+    const monthlyPremium = activeSubscriptions.find(
+      sub => sub.productId === SUBSCRIPTION_SKUS.PREMIUM
+    );
+    if (monthlyPremium) return 'PREMIUM';
 
-      // 2) Build subscriptionOffers from the fetched product details
-      const subscriptionOffers = (
-        subscription.subscriptionOfferDetailsAndroid ?? []
-      ).map((offer) => ({
-        sku: subscription.id,
-        offerToken: offer.offerToken,
-      }));
-
-      // Platform-specific subscription purchase requests
-      // For Android: subscriptionOffers are required for subscriptions to specify pricing plans and offer tokens
-      // For iOS: withOffer can be used for promotional offers or discounts
-      await requestPurchase({
-        request: {
-          ios: {
-            sku: productId,
-            andDangerouslyFinishTransactionAutomatically: false,
-            // withOffer: { /* DiscountOfferInputIOS for promotional offers */ }
-          },
-          android: {
-            skus: [productId],
-            subscriptionOffers,
-          },
-        },
-        type: 'subs',
-      });
-    } catch (error) {
-      console.error('Subscription request failed:', error);
-      Alert.alert('Error', 'Failed to start subscription purchase');
-    }
-  };
+    // Finally check basic
+    const basic = activeSubscriptions.find(
+      sub => sub.productId === SUBSCRIPTION_SKUS.BASIC
+    );
+    if (basic) return 'BASIC';
 
-  const openSubscriptionManagement = () => {
-    import('react-native-iap').then(({deepLinkToSubscriptions}) => {
-      deepLinkToSubscriptions({skuAndroid: 'your_subscription_sku'});
-    });
-  };
+    return 'FREE';
+  } catch (error) {
+    console.error('Failed to get subscription tier:', error);
+    return 'FREE';
+  }
+}
+```
 
-  const restoreSubscriptions = async () => {
-    try {
-      setLoading(true);
-      await checkSubscriptionStatus();
-      Alert.alert('Restore Complete', 'Subscription status has been updated');
-    } catch (error) {
-      Alert.alert('Error', 'Failed to restore subscriptions');
-    } finally {
-      setLoading(false);
-    }
-  };
+## 3. Subscription Plan Changes (Upgrade/Downgrade)
 
-  const formatDate = (date: Date) => {
-    return date.toLocaleDateString('en-US', {
-      year: 'numeric',
-      month: 'long',
-      day: 'numeric',
-    });
-  };
+### iOS: Automatic Subscription Group Management
 
-  const renderSubscriptionStatus = () => {
-    if (subscriptionStatus.isActive) {
-      return (
-        <View style={styles.statusCard}>
-          <Text style={styles.statusTitle}>Premium Active</Text>
-          <Text style={styles.statusSubtitle}>
-            Your premium subscription is active
-          </Text>
-
-          {subscriptionStatus.expirationDate && (
-            <Text style={styles.statusDetail}>
-              {subscriptionStatus.autoRenewing ? 'Renews' : 'Expires'} on{' '}
-              {formatDate(subscriptionStatus.expirationDate)}
-            </Text>
-          )}
-
-          {subscriptionStatus.inGracePeriod && (
-            <Text style={styles.warningText}>
-              Your subscription is in grace period. Please update your payment
-              method.
-            </Text>
-          )}
-
-          <TouchableOpacity
-            style={styles.manageButton}
-            onPress={openSubscriptionManagement}
-          >
-            <Text style={styles.manageButtonText}>Manage Subscription</Text>
-          </TouchableOpacity>
-        </View>
-      );
-    }
+On iOS, subscriptions in the same subscription group automatically replace each other when purchased. The App Store handles the proration and timing automatically.
 
-    return (
-      <View style={styles.statusCard}>
-        <Text style={styles.statusTitle}>No Active Subscription</Text>
-        <Text style={styles.statusSubtitle}>
-          Subscribe to unlock premium features
-        </Text>
-      </View>
-    );
-  };
+```tsx
+// iOS Subscription Configuration in App Store Connect:
+// Subscription Group: "Premium Access"
+// - com.app.premium_monthly (Rank 1)
+// - com.app.premium_yearly (Rank 2 - higher rank = better value)
 
-  const renderSubscriptionOption = (subscription) => {
-    const isYearly = subscription.productId.includes('yearly');
-    const savings = isYearly ? '2 months free!' : null;
-
-    return (
-      <View key={subscription.productId} style={styles.subscriptionCard}>
-        <View style={styles.subscriptionInfo}>
-          <Text style={styles.subscriptionTitle}>
-            {isYearly ? 'Yearly Premium' : 'Monthly Premium'}
-          </Text>
-          <Text style={styles.subscriptionPrice}>
-            {subscription.localizedPrice}
-          </Text>
-          {subscription.subscriptionPeriod && (
-            <Text style={styles.subscriptionPeriod}>
-              per {subscription.subscriptionPeriod}
-            </Text>
-          )}
-          {savings && <Text style={styles.savingsText}>{savings}</Text>}
-        </View>
+async function handleIOSSubscriptionChange(newProductId: string) {
+  const {requestPurchase, getActiveSubscriptions} = useIAP();
 
-        <TouchableOpacity
-          style={[styles.subscribeButton, isYearly && styles.yearlyButton]}
-          onPress={() => purchaseSubscription(subscription.productId)}
-          disabled={loading || subscriptionStatus.isActive}
-        >
-          <Text style={styles.subscribeButtonText}>
-            {subscriptionStatus.isActive ? 'Active' : 'Subscribe'}
-          </Text>
-        </TouchableOpacity>
-      </View>
+  try {
+    // Check current subscription
+    const currentSubs = await getActiveSubscriptions();
+    const currentSub = currentSubs.find(sub =>
+      sub.productId === 'com.app.premium_monthly' ||
+      sub.productId === 'com.app.premium_yearly'
     );
-  };
 
-  if (!connected) {
-    return (
-      <View style={styles.centerContainer}>
-        <ActivityIndicator size="large" />
-        <Text style={styles.loadingText}>Connecting to store...</Text>
-      </View>
-    );
-  }
+    if (currentSub) {
+      console.log(`Changing from ${currentSub.productId} to ${newProductId}`);
+      // iOS automatically handles the switch when both products are in the same group
+    }
 
-  return (
-    <ScrollView style={styles.container}>
-      <Text style={styles.title}>Subscription Management</Text>
+    // Simply purchase the new subscription
+    // iOS will automatically:
+    // 1. Cancel the old subscription at the end of the current period
+    // 2. Start the new subscription
+    // 3. Handle any necessary proration
+    await requestPurchase({
+      request: {
+        ios: {
+          sku: newProductId,
+          andDangerouslyFinishTransactionAutomatically: false,
+        },
+        android: {
+          skus: [newProductId],
+        },
+      },
+      type: 'subs',
+    });
 
-      {renderSubscriptionStatus()}
+    Alert.alert(
+      'Subscription Updated',
+      'Your subscription will change at the end of the current billing period.'
+    );
 
-      <Text style={styles.sectionTitle}>Subscription Options</Text>
+  } catch (error) {
+    console.error('Subscription change failed:', error);
+  }
+}
 
-      {loading ? (
-        <View style={styles.centerContainer}>
-          <ActivityIndicator size="large" />
-          <Text style={styles.loadingText}>Loading subscriptions...</Text>
-        </View>
-      ) : (
-        <View>{subscriptions.map(renderSubscriptionOption)}</View>
-      )}
+// Usage example
+function IOSSubscriptionManager() {
+  const handleUpgradeToYearly = () => {
+    handleIOSSubscriptionChange('com.app.premium_yearly');
+  };
 
-      <View style={styles.actionButtons}>
-        <TouchableOpacity
-          style={styles.restoreButton}
-          onPress={restoreSubscriptions}
-          disabled={loading}
-        >
-          <Text style={styles.restoreButtonText}>Restore Purchases</Text>
-        </TouchableOpacity>
-      </View>
-
-      <View style={styles.footer}>
-        <Text style={styles.footerText}>
-          Subscriptions auto-renew unless cancelled. You can manage your
-          subscriptions in your device settings.
-        </Text>
-      </View>
-    </ScrollView>
+  const handleDowngradeToMonthly = () => {
+    handleIOSSubscriptionChange('com.app.premium_monthly');
+  };
+
+  return (
+    <View>
+      <Text>iOS subscriptions in the same group auto-replace each other</Text>
+      <Button title="Upgrade to Yearly" onPress={handleUpgradeToYearly} />
+      <Button title="Switch to Monthly" onPress={handleDowngradeToMonthly} />
+    </View>
   );
 }
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    padding: 16,
-    backgroundColor: '#f5f5f5',
-  },
-  centerContainer: {
-    flex: 1,
-    justifyContent: 'center',
-    alignItems: 'center',
-    padding: 20,
-  },
-  title: {
-    fontSize: 28,
-    fontWeight: 'bold',
-    textAlign: 'center',
-    marginBottom: 24,
-    color: '#333',
-  },
-  loadingText: {
-    marginTop: 16,
-    fontSize: 16,
-    color: '#666',
-  },
-  sectionTitle: {
-    fontSize: 20,
-    fontWeight: 'bold',
-    marginTop: 24,
-    marginBottom: 16,
-    color: '#333',
-  },
-  statusCard: {
-    backgroundColor: 'white',
-    padding: 20,
-    borderRadius: 12,
-    marginBottom: 24,
-    shadowColor: '#000',
-    shadowOffset: {width: 0, height: 2},
-    shadowOpacity: 0.1,
-    shadowRadius: 8,
-    elevation: 4,
-  },
-  statusTitle: {
-    fontSize: 20,
-    fontWeight: 'bold',
-    marginBottom: 8,
-    color: '#333',
-  },
-  statusSubtitle: {
-    fontSize: 16,
-    color: '#666',
-    marginBottom: 12,
-  },
-  statusDetail: {
-    fontSize: 14,
-    color: '#666',
-    marginBottom: 8,
-  },
-  warningText: {
-    fontSize: 14,
-    color: '#ff9800',
-    fontStyle: 'italic',
-    marginBottom: 16,
-  },
-  manageButton: {
-    backgroundColor: '#2196f3',
-    paddingVertical: 12,
-    paddingHorizontal: 24,
-    borderRadius: 8,
-    alignSelf: 'flex-start',
-  },
-  manageButtonText: {
-    color: 'white',
-    fontWeight: 'bold',
-  },
-  subscriptionCard: {
-    backgroundColor: 'white',
-    padding: 20,
-    borderRadius: 12,
-    marginBottom: 16,
-    flexDirection: 'row',
-    alignItems: 'center',
-    shadowColor: '#000',
-    shadowOffset: {width: 0, height: 2},
-    shadowOpacity: 0.1,
-    shadowRadius: 8,
-    elevation: 4,
-  },
-  subscriptionInfo: {
-    flex: 1,
-  },
-  subscriptionTitle: {
-    fontSize: 18,
-    fontWeight: 'bold',
-    marginBottom: 4,
-    color: '#333',
-  },
-  subscriptionPrice: {
-    fontSize: 20,
-    fontWeight: 'bold',
-    color: '#2196f3',
-    marginBottom: 4,
-  },
-  subscriptionPeriod: {
-    fontSize: 14,
-    color: '#666',
-    marginBottom: 4,
-  },
-  savingsText: {
-    fontSize: 14,
-    color: '#4caf50',
-    fontWeight: 'bold',
-  },
-  subscribeButton: {
-    backgroundColor: '#2196f3',
-    paddingVertical: 12,
-    paddingHorizontal: 24,
-    borderRadius: 8,
-    minWidth: 100,
-  },
-  yearlyButton: {
-    backgroundColor: '#ff9800',
-  },
-  subscribeButtonText: {
-    color: 'white',
-    fontWeight: 'bold',
-    textAlign: 'center',
-  },
-  actionButtons: {
-    marginTop: 32,
-    alignItems: 'center',
-  },
-  restoreButton: {
-    backgroundColor: 'transparent',
-    borderWidth: 1,
-    borderColor: '#2196f3',
-    paddingVertical: 12,
-    paddingHorizontal: 24,
-    borderRadius: 8,
-  },
-  restoreButtonText: {
-    color: '#2196f3',
-    fontWeight: 'bold',
-  },
-  footer: {
-    marginTop: 32,
-    paddingTop: 20,
-    borderTopWidth: 1,
-    borderTopColor: '#e0e0e0',
-  },
-  footerText: {
-    fontSize: 12,
-    color: '#666',
-    textAlign: 'center',
-    lineHeight: 18,
-  },
-});
 ```
 
-## Key Features
+### Android: Manual Plan Changes with Purchase Token
 
-### 1. Subscription Status Tracking
+On Android, you need to explicitly handle subscription upgrades/downgrades using the purchase token from the existing subscription.
 
-- Real-time subscription status validation
-- Grace period handling
-- Auto-renewal status
+```tsx
+async function handleAndroidSubscriptionChange(
+  newProductId: string,
+  changeType: 'upgrade' | 'downgrade'
+) {
+  const {requestPurchase, getAvailablePurchases, subscriptions} = useIAP();
 
-### 2. Multiple Subscription Tiers
+  try {
+    // Step 1: Get the current subscription's purchase token
+    await getAvailablePurchases();
+    const currentPurchase = availablePurchases.find(
+      p => p.productId === 'com.app.premium_monthly' ||
+           p.productId === 'com.app.premium_yearly'
+    );
 
-- Monthly and yearly options
-- Pricing display with savings indicators
-- Visual differentiation for different tiers
+    if (!currentPurchase?.purchaseToken) {
+      throw new Error('No active subscription found');
+    }
 
-### 3. Subscription Management
+    // Step 2: Find the new subscription product
+    const newSubscription = subscriptions.find(sub => sub.id === newProductId);
+    if (!newSubscription) {
+      throw new Error('New subscription product not found');
+    }
 
-- Direct links to platform subscription management
-- Purchase restoration
-- Status refresh capabilities
+    // Step 3: Prepare subscription offers
+    const subscriptionOffers = (
+      newSubscription.subscriptionOfferDetailsAndroid ?? []
+    ).map(offer => ({
+      sku: newSubscription.id,
+      offerToken: offer.offerToken,
+    }));
+
+    // Step 4: Request purchase with the old purchase token for replacement
+    await requestPurchase({
+      request: {
+        ios: {
+          sku: newProductId,
+        },
+        android: {
+          skus: [newProductId],
+          subscriptionOffers,
+          // IMPORTANT: Include purchase token for subscription replacement
+          purchaseTokenAndroid: currentPurchase.purchaseToken,
+          // Optional: Specify proration mode
+          replacementModeAndroid: changeType === 'upgrade'
+            ? 'IMMEDIATE_WITH_TIME_PRORATION'
+            : 'DEFERRED', // Downgrade happens at next renewal
+        },
+      },
+      type: 'subs',
+    });
 
-### 4. Server Integration
+    const message = changeType === 'upgrade'
+      ? 'Subscription upgraded immediately!'
+      : 'Subscription will change at the end of current period.';
 
-- Server-side subscription validation
-- Benefit granting system
-- Status synchronization
+    Alert.alert('Success', message);
 
-## Platform Differences
+  } catch (error) {
+    console.error('Android subscription change failed:', error);
+    Alert.alert('Error', 'Failed to change subscription plan');
+  }
+}
 
-### Subscription Purchase Parameters
+// Complete Android Example with UI
+function AndroidSubscriptionManager() {
+  const {subscriptions, getAvailablePurchases, availablePurchases} = useIAP();
+  const [currentPlan, setCurrentPlan] = useState<string | null>(null);
 
-**Important**: iOS and Android have different parameter structures for subscription purchases:
+  useEffect(() => {
+    checkCurrentPlan();
+  }, []);
 
-**Unified Structure (v2.7.0+):**
+  const checkCurrentPlan = async () => {
+    try {
+      await getAvailablePurchases();
+      const activeSub = availablePurchases.find(
+        p => p.productId === 'com.app.premium_monthly' ||
+             p.productId === 'com.app.premium_yearly'
+      );
+      setCurrentPlan(activeSub?.productId || null);
+    } catch (error) {
+      console.error('Failed to check current plan:', error);
+    }
+  };
 
-```tsx
-// New API - no Platform.OS checks needed!
-await requestPurchase({
-  request: {
-    ios: {
-      sku: productId,
-      andDangerouslyFinishTransactionAutomatically: false,
-    },
-    android: {
-      skus: [productId],
-    },
-  },
-  type: 'subs',
-});
-```
+  const handlePlanChange = (targetPlan: string) => {
+    if (!currentPlan) {
+      // New subscription
+      purchaseNewSubscription(targetPlan);
+    } else if (currentPlan === 'com.app.premium_monthly' &&
+               targetPlan === 'com.app.premium_yearly') {
+      // Upgrade to yearly
+      handleAndroidSubscriptionChange(targetPlan, 'upgrade');
+    } else if (currentPlan === 'com.app.premium_yearly' &&
+               targetPlan === 'com.app.premium_monthly') {
+      // Downgrade to monthly
+      handleAndroidSubscriptionChange(targetPlan, 'downgrade');
+    }
+  };
 
-### Receipt Validation Differences
+  return (
+    <View>
+      <Text>Current Plan: {currentPlan || 'None'}</Text>
+
+      {currentPlan === 'com.app.premium_monthly' && (
+        <Button
+          title="⬆️ Upgrade to Yearly (Save 20%)"
+          onPress={() => handlePlanChange('com.app.premium_yearly')}
+        />
+      )}
 
-Subscription validation requires different approaches:
+      {currentPlan === 'com.app.premium_yearly' && (
+        <Button
+          title="⬇️ Switch to Monthly"
+          onPress={() => handlePlanChange('com.app.premium_monthly')}
+        />
+      )}
+    </View>
+  );
+}
+```
 
-- **iOS**: Send `purchaseToken` which was ~~`transactionReceipt`~~ to Apple's validation servers
-- **Android**: Send `purchaseToken` and `packageName` to Google Play validation
+## 4. Platform-Unified Subscription Change Handler
 
-This is handled in the `validateSubscriptionStatus` function with platform-specific logic.
+Here's a complete example that handles both platforms appropriately:
 
-## Server-Side Implementation
+```tsx
+function SubscriptionPlanManager() {
+  const {
+    requestPurchase,
+    getActiveSubscriptions,
+    getAvailablePurchases,
+    subscriptions,
+    availablePurchases,
+  } = useIAP();
 
-### Subscription Validation Endpoint
+  const handleSubscriptionChange = async (newProductId: string) => {
+    try {
+      if (Platform.OS === 'ios') {
+        // iOS: Simple purchase - automatic replacement in same group
+        await requestPurchase({
+          request: {
+            ios: {
+              sku: newProductId,
+              andDangerouslyFinishTransactionAutomatically: false,
+            },
+            android: {
+              skus: [newProductId],
+            },
+          },
+          type: 'subs',
+        });
 
-```javascript
-// Example Node.js/Express endpoint
-app.post('/validate-subscription', async (req, res) => {
-  const {receipt, productId, purchaseToken, transactionId} = req.body;
+        Alert.alert(
+          'Subscription Updated',
+          'Your plan will change at the end of the current period.'
+        );
 
-  try {
-    let validationResult;
+      } else {
+        // Android: Need purchase token for replacement
+        await getAvailablePurchases();
 
-    if (purchaseToken) {
-      // Android - Google Play Billing validation
-      validationResult = await validateGooglePlaySubscription(
-        productId,
-        purchaseToken,
-      );
-    } else {
-      // iOS - App Store validation
-      validationResult = await validateAppStoreReceipt(receipt);
-    }
+        // Find current subscription
+        const currentPurchase = availablePurchases.find(p =>
+          p.productId.includes('premium')
+        );
 
-    res.json({
-      isActive: validationResult.isActive,
-      expirationDate: validationResult.expirationDate,
-      autoRenewing: validationResult.autoRenewing,
-      inGracePeriod: validationResult.inGracePeriod,
-    });
-  } catch (error) {
-    console.error('Validation error:', error);
-    res.status(500).json({error: 'Validation failed'});
-  }
-});
-```
+        // Find new subscription details
+        const newSub = subscriptions.find(s => s.id === newProductId);
+
+        if (currentPurchase?.purchaseToken && newSub) {
+          // Prepare offers
+          const offers = (newSub.subscriptionOfferDetailsAndroid ?? [])
+            .map(offer => ({
+              sku: newSub.id,
+              offerToken: offer.offerToken,
+            }));
+
+          // Purchase with replacement
+          await requestPurchase({
+            request: {
+              ios: {
+                sku: newProductId,
+              },
+              android: {
+                skus: [newProductId],
+                subscriptionOffers: offers,
+                purchaseTokenAndroid: currentPurchase.purchaseToken,
+              },
+            },
+            type: 'subs',
+          });
+
+          Alert.alert('Success', 'Subscription plan changed!');
+        } else {
+          // New subscription (no existing one)
+          const offers = (newSub?.subscriptionOfferDetailsAndroid ?? [])
+            .map(offer => ({
+              sku: newSub.id,
+              offerToken: offer.offerToken,
+            }));
+
+          await requestPurchase({
+            request: {
+              ios: {
+                sku: newProductId,
+              },
+              android: {
+                skus: [newProductId],
+                subscriptionOffers: offers,
+              },
+            },
+            type: 'subs',
+          });
+        }
+      }
 
-## Usage
+      // Refresh subscription status
+      await getActiveSubscriptions();
 
-```tsx
-import React from 'react';
-import {NavigationContainer} from '@react-navigation/native';
-import SubscriptionManager from './SubscriptionManager';
+    } catch (error) {
+      console.error('Subscription change error:', error);
+      Alert.alert('Error', 'Failed to change subscription');
+    }
+  };
 
-export default function App() {
   return (
-    <NavigationContainer>
-      <SubscriptionManager />
-    </NavigationContainer>
+    <View>
+      <Text style={styles.title}>Choose Your Plan</Text>
+
+      <TouchableOpacity
+        style={styles.planCard}
+        onPress={() => handleSubscriptionChange('com.app.premium_monthly')}
+      >
+        <Text>Monthly - $9.99/month</Text>
+      </TouchableOpacity>
+
+      <TouchableOpacity
+        style={[styles.planCard, styles.recommended]}
+        onPress={() => handleSubscriptionChange('com.app.premium_yearly')}
+      >
+        <Text>Yearly - $99.99/year (Save $20!)</Text>
+      </TouchableOpacity>
+
+      <Text style={styles.note}>
+        {Platform.OS === 'ios'
+          ? '✓ Changes take effect at the end of current period'
+          : '✓ Upgrades apply immediately with proration'}
+      </Text>
+    </View>
   );
 }
 ```
 
-## Best Practices Demonstrated
+## Key Points Summary
+
+### Purchase Flow
+1. **Always use hook callbacks** (`onPurchaseSuccess`, `onPurchaseError`) for handling results
+2. **Don't chain `.then()` on `requestPurchase` promise** - it can fire at the wrong time
+3. **Android requires `subscriptionOffers`** array with offer tokens for subscription purchases
+
+### Platform Differences
+
+| Feature | iOS | Android |
+|---------|-----|---------|
+| **Plan Changes** | Automatic within subscription group | Manual with purchaseToken |
+| **Proration** | Handled by App Store | Configurable via replacementModeAndroid |
+| **Status Check** | Check expirationDateIos | Check autoRenewingAndroid |
+| **Cancellation** | User manages in Settings | Check autoRenewingAndroid === false |
+| **Multiple Plans** | Use subscription groups with ranks | Use base plans and offers |
 
-1. **Status Validation**: Always validate subscription status server-side
-2. **Grace Period Handling**: Handle billing issues gracefully
-3. **User Experience**: Provide clear subscription status and management options
-4. **Error Handling**: Comprehensive error handling for various scenarios
-5. **Platform Integration**: Use platform-specific subscription management tools
+## Best Practices
 
-## Customization
+1. **Always validate on server**: Client-side checks are for UI only
+2. **Handle grace periods**: Check for billing issues before removing access
+3. **Use hook callbacks**: Don't rely on promise resolution for state updates
+4. **Clear messaging**: Explain when changes take effect
+5. **Test thoroughly**: Use sandbox/test accounts for both platforms
+6. **Store state properly**: Cache subscription status to reduce API calls
 
-You can extend this example with:
+## Additional Resources
 
-- Multiple subscription tiers
-- Promotional offers and trials
-- Family sharing support
-- Subscription analytics
-- Custom subscription management UI
+- [Complete working example](https://github.com/hyochan/react-native-iap/blob/main/example/screens/SubscriptionFlow.tsx)
+- [iOS Subscription Groups Documentation](https://developer.apple.com/app-store/subscriptions/)
+- [Android Subscription Upgrade/Downgrade](https://developer.android.com/google/play/billing/subscriptions#upgrade-downgrade)
\ No newline at end of file
diff --git a/docs/docs/guides/purchases.md b/docs/docs/guides/purchases.md
index 7d4785a7b..78f778dc6 100644
--- a/docs/docs/guides/purchases.md
+++ b/docs/docs/guides/purchases.md
@@ -158,20 +158,70 @@ const bulbPackSkus = ['dev.hyo.martie.10bulbs', 'dev.hyo.martie.30bulbs'];
 const subscriptionSkus = ['dev.hyo.martie.premium'];
 
 export default function PurchaseScreen() {
+  const [isLoading, setIsLoading] = useState(false);
+  const [isReady, setIsReady] = useState(false);
+
+  const handlePurchaseUpdate = useCallback(async (purchase: any) => {
+    try {
+      setIsLoading(true);
+      console.log('Processing purchase:', purchase);
+
+      const productId = purchase.productId || purchase.id;
+
+      // Validate receipt on your server
+      const validationResult = await handleValidateReceipt(productId, purchase);
+
+      if (validationResult.isValid) {
+        // Determine if this is a consumable product
+        const isConsumable = bulbPackSkus.includes(productId);
+
+        // Complete the transaction
+        await finishTransaction({purchase, isConsumable});
+
+        // Grant the purchase benefits
+        if (isConsumable) {
+          await grantConsumable(productId);
+        } else {
+          await grantNonConsumable(productId);
+        }
+
+        Alert.alert('Purchase Complete', 'Thank you for your purchase!');
+      } else {
+        Alert.alert('Purchase Failed', 'Receipt validation failed');
+      }
+    } catch (error) {
+      console.error('Error processing purchase:', error);
+      Alert.alert('Error', 'Failed to process purchase');
+    } finally {
+      setIsLoading(false);
+    }
+  }, [finishTransaction, handleValidateReceipt]);
+
   const {
     connected,
     products,
     subscriptions,
-    currentPurchase,
-    currentPurchaseError,
     fetchProducts,
     requestPurchase,
     finishTransaction,
     validateReceipt,
-  } = useIAP();
+  } = useIAP({
+    onPurchaseSuccess: handlePurchaseUpdate,
+    onPurchaseError: (error) => {
+      setIsLoading(false);
 
-  const [isLoading, setIsLoading] = useState(false);
-  const [isReady, setIsReady] = useState(false);
+      // Don't show error for user cancellation
+      if (error.code === 'E_USER_CANCELLED') {
+        return;
+      }
+
+      Alert.alert(
+        'Purchase Error',
+        'Failed to complete purchase. Please try again.',
+      );
+      console.error('Purchase error:', error);
+    },
+  });
 
   // Initialize products when IAP connection is established
   useEffect(() => {
@@ -218,72 +268,7 @@ export default function PurchaseScreen() {
     [validateReceipt],
   );
 
-  // Handle successful purchases
-  useEffect(() => {
-    if (currentPurchase) {
-      handlePurchaseUpdate(currentPurchase);
-    }
-  }, [currentPurchase]);
-
-  // Handle purchase errors
-  useEffect(() => {
-    if (currentPurchaseError) {
-      setIsLoading(false);
-
-      // Don't show error for user cancellation
-      if (currentPurchaseError.code === 'E_USER_CANCELLED') {
-        return;
-      }
-
-      Alert.alert(
-        'Purchase Error',
-        'Failed to complete purchase. Please try again.',
-      );
-      console.error('Purchase error:', currentPurchaseError);
-    }
-  }, [currentPurchaseError]);
-
-  const handlePurchaseUpdate = async (purchase: any) => {
-    try {
-      setIsLoading(true);
-      console.log('Processing purchase:', purchase);
-
-      const productId = purchase.id;
-
-      // Validate receipt on your server
-      const validationResult = await handleValidateReceipt(productId, purchase);
-
-      if (validationResult.isValid) {
-        // Determine if this is a consumable product
-        const isConsumable = bulbPackSkus.includes(productId);
-
-        // Finish the transaction
-        await finishTransaction({
-          purchase,
-          isConsumable, // Set to true for consumable products
-        });
-
-        // Record purchase in your database
-        await recordPurchaseInDatabase(purchase, productId);
-
-        // Update local state (e.g., add bulbs, enable premium features)
-        await updateLocalState(productId);
-
-        // Show success message
-        showSuccessMessage(productId);
-      } else {
-        Alert.alert(
-          'Validation Error',
-          'Purchase could not be validated. Please contact support.',
-        );
-      }
-    } catch (error) {
-      console.error('Error handling purchase:', error);
-      Alert.alert('Error', 'Failed to process purchase.');
-    } finally {
-      setIsLoading(false);
-    }
-  };
+  // Purchase handlers are now in the useIAP callbacks above
 
   // Request purchase for products
   const handlePurchaseBulbs = async (productId: string) => {
@@ -889,12 +874,20 @@ const restorePurchases = async () => {
 Some purchases may be in a pending state (e.g., awaiting parental approval):
 
 ```tsx
-useEffect(() => {
-  if (currentPurchase?.purchaseState === 'pending') {
-    // Inform user that purchase is pending
-    showPendingPurchaseMessage();
-  }
-}, [currentPurchase]);
+// In onPurchaseSuccess callback:
+const {
+  // ... other props
+} = useIAP({
+  onPurchaseSuccess: async (purchase) => {
+    if (purchase.purchaseState === 'pending') {
+      // Inform user that purchase is pending
+      showPendingPurchaseMessage();
+      return;
+    }
+    // Handle completed purchase
+    await handlePurchaseUpdate(purchase);
+  },
+});
 ```
 
 ### Subscription Management
diff --git a/docs/docs/guides/troubleshooting.md b/docs/docs/guides/troubleshooting.md
index 01fe0b1c3..220aeb287 100644
--- a/docs/docs/guides/troubleshooting.md
+++ b/docs/docs/guides/troubleshooting.md
@@ -133,33 +133,30 @@ useEffect(() => {
 Always handle purchase updates and finish transactions:
 
 ```tsx
-const {currentPurchase, finishTransaction} = useIAP();
-
-useEffect(() => {
-  if (currentPurchase) {
-    handlePurchase(currentPurchase);
-  }
-}, [currentPurchase]);
-
-const handlePurchase = async (purchase) => {
-  try {
-    // Validate receipt
-    const isValid = await validateOnServer(purchase);
+const {finishTransaction} = useIAP({
+  onPurchaseSuccess: async (purchase) => {
+    try {
+      // Validate receipt
+      const isValid = await validateOnServer(purchase);
 
-    if (isValid) {
-      // Grant purchase to user
-      await grantPurchase(purchase);
+      if (isValid) {
+        // Grant purchase to user
+        await grantPurchase(purchase);
 
-      // ✅ Always finish the transaction
-      await finishTransaction({
-        purchase,
-        isConsumable: false, // default is false
-      });
+        // ✅ Always finish the transaction
+        await finishTransaction({
+          purchase,
+          isConsumable: false, // default is false
+        });
+      }
+    } catch (error) {
+      console.error('Purchase handling failed:', error);
     }
-  } catch (error) {
-    console.error('Purchase handling failed:', error);
-  }
-};
+  },
+  onPurchaseError: (error) => {
+    console.error('Purchase error:', error);
+  },
+});
 ```
 
 **Important - Transaction Acknowledgment Requirements**:
@@ -394,22 +391,18 @@ if (__DEV__) {
 ### 2. Log purchase events
 
 ```tsx
-const {currentPurchase, currentPurchaseError} = useIAP();
-
-useEffect(() => {
-  if (currentPurchase) {
-    console.log('Purchase received:', JSON.stringify(currentPurchase, null, 2));
-  }
-}, [currentPurchase]);
-
-useEffect(() => {
-  if (currentPurchaseError) {
+const {/* other props */} = useIAP({
+  onPurchaseSuccess: async (purchase) => {
+    console.log('Purchase received:', JSON.stringify(purchase, null, 2));
+    // Handle purchase...
+  },
+  onPurchaseError: (error) => {
     console.error(
       'Purchase error:',
-      JSON.stringify(currentPurchaseError, null, 2),
+      JSON.stringify(error, null, 2),
     );
-  }
-}, [currentPurchaseError]);
+  },
+});
 ```
 
 ### 3. Monitor connection state
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
index 113322be9..5c860c351 100644
--- a/docs/docs/intro.md
+++ b/docs/docs/intro.md
@@ -51,7 +51,6 @@ function MyStore() {
     products,
     fetchProducts,
     requestPurchase,
-    currentPurchase,
     finishTransaction,
   } = useIAP();
 
@@ -117,31 +116,43 @@ const handlePurchase = async (productId: string) => {
 
 **No more Platform.OS checks!** The new API automatically handles platform differences. iOS can only purchase one product at a time, while Android supports purchasing multiple products in a single transaction.
 
-### 5. Complete Transactions
+### 5. Handle Purchase Callbacks
 
-Finish purchases when they complete:
+Use the `onPurchaseSuccess` and `onPurchaseError` callbacks to handle purchase results:
 
 ```tsx
-useEffect(() => {
-  if (currentPurchase) {
-    const completePurchase = async () => {
-      try {
-        // Grant the purchase to user here
-        console.log('Purchase completed:', currentPurchase.id);
-
-        // Finish the transaction
-        await finishTransaction({
-          purchase: currentPurchase,
-          isConsumable: true, // Set based on your product type
-        });
-      } catch (error) {
-        console.error('Failed to complete purchase:', error);
-      }
-    };
-
-    completePurchase();
-  }
-}, [currentPurchase]);
+const {
+  connected,
+  products,
+  fetchProducts,
+  requestPurchase,
+  finishTransaction,
+} = useIAP({
+  onPurchaseSuccess: async (purchase) => {
+    try {
+      console.log('Purchase successful:', purchase.productId);
+
+      // TODO: Verify the receipt on your backend before granting access
+      // const isValid = await verifyReceiptOnBackend(purchase);
+      // if (!isValid) {
+      //   throw new Error('Invalid receipt');
+      // }
+
+      // Finish the transaction after verification
+      await finishTransaction({
+        purchase,
+        isConsumable: true, // Set based on your product type
+      });
+    } catch (error) {
+      console.error('Failed to complete purchase:', error);
+    }
+  },
+  onPurchaseError: (error) => {
+    if (error.code !== 'E_USER_CANCELLED') {
+      console.error('Purchase error:', error);
+    }
+  },
+});
 ```
 
 ### Complete Basic Example
@@ -159,9 +170,32 @@ export default function SimpleStore() {
     products,
     fetchProducts,
     requestPurchase,
-    currentPurchase,
     finishTransaction,
-  } = useIAP();
+  } = useIAP({
+    onPurchaseSuccess: async (purchase) => {
+      try {
+        console.log('Purchase successful:', purchase.productId);
+
+        // TODO: Verify the receipt on your backend before granting access
+        // const isValid = await verifyReceiptOnBackend(purchase);
+        // if (!isValid) {
+        //   throw new Error('Invalid receipt');
+        // }
+
+        await finishTransaction({
+          purchase,
+          isConsumable: true,
+        });
+      } catch (error) {
+        console.error('Failed to complete purchase:', error);
+      }
+    },
+    onPurchaseError: (error) => {
+      if (error.code !== 'E_USER_CANCELLED') {
+        console.error('Purchase error:', error.message);
+      }
+    },
+  });
 
   const productIds = ['com.example.coins.pack1', 'com.example.premium'];
 
@@ -171,23 +205,6 @@ export default function SimpleStore() {
     }
   }, [connected]);
 
-  useEffect(() => {
-    if (currentPurchase) {
-      const completePurchase = async () => {
-        try {
-          console.log('Purchase completed:', currentPurchase.id);
-          await finishTransaction({
-            purchase: currentPurchase,
-            isConsumable: true,
-          });
-        } catch (error) {
-          console.error('Failed to complete purchase:', error);
-        }
-      };
-      completePurchase();
-    }
-  }, [currentPurchase]);
-
   const handlePurchase = async (productId: string) => {
     try {
       await requestPurchase({
diff --git a/example/__tests__/screens/SubscriptionFlow.test.tsx b/example/__tests__/screens/SubscriptionFlow.test.tsx
index fe2bb3912..8561e9c5d 100644
--- a/example/__tests__/screens/SubscriptionFlow.test.tsx
+++ b/example/__tests__/screens/SubscriptionFlow.test.tsx
@@ -1,5 +1,5 @@
 import {render, fireEvent, waitFor, act} from '@testing-library/react-native';
-import {Alert} from 'react-native';
+import {Alert, Platform} from 'react-native';
 import SubscriptionFlow from '../../screens/SubscriptionFlow';
 import * as RNIap from 'react-native-iap';
 import {SUBSCRIPTION_PRODUCT_IDS} from '../../src/utils/constants';
@@ -8,14 +8,16 @@ const requestPurchaseMock = RNIap.requestPurchase as jest.Mock;
 const deepLinkToSubscriptionsMock = RNIap.deepLinkToSubscriptions as jest.Mock;
 
 const sampleSubscription = {
-  type: 'subs',
+  type: 'subs' as const,
   id: 'dev.hyo.martie.premium',
   title: 'Premium Subscription',
   description: 'Access all premium features',
   displayPrice: '$9.99/month',
   price: 9.99,
   currency: 'USD',
-};
+  platform: 'android' as const,
+  nameAndroid: 'Premium Subscription',
+} as any; // Mock object, actual types vary by platform
 
 describe('SubscriptionFlow Screen', () => {
   let onPurchaseSuccess: ((purchase: any) => Promise<void> | void) | undefined;
@@ -27,15 +29,19 @@ describe('SubscriptionFlow Screen', () => {
     } = {},
   ) => {
     const fetchProducts = jest.fn(() => Promise.resolve());
-    const getAvailablePurchases = jest.fn(() => Promise.resolve());
+    const defaultGetAvailablePurchases = jest.fn(() => Promise.resolve([]));
     const getActiveSubscriptions = jest.fn(() => Promise.resolve([]));
     const finishTransaction = jest.fn(() => Promise.resolve());
 
+    // Use the override if provided, otherwise use default
+    const getAvailablePurchases =
+      overrides.getAvailablePurchases || defaultGetAvailablePurchases;
+
     (RNIap.useIAP as jest.Mock).mockImplementation((options) => {
       onPurchaseSuccess = options?.onPurchaseSuccess;
       onPurchaseError = options?.onPurchaseError;
 
-      return {
+      const result = {
         connected: true,
         subscriptions: [sampleSubscription],
         availablePurchases: [],
@@ -46,6 +52,9 @@ describe('SubscriptionFlow Screen', () => {
         getActiveSubscriptions,
         ...overrides,
       };
+      // Ensure getAvailablePurchases uses our mock
+      result.getAvailablePurchases = getAvailablePurchases;
+      return result;
     });
 
     return {
@@ -61,6 +70,11 @@ describe('SubscriptionFlow Screen', () => {
     mockIapState();
   });
 
+  afterEach(() => {
+    // Reset Platform.OS to its default after each test
+    Platform.OS = 'ios';
+  });
+
   it('renders loading state when not connected', () => {
     mockIapState({connected: false, subscriptions: []});
 
@@ -175,4 +189,340 @@ describe('SubscriptionFlow Screen', () => {
       ).toBeTruthy();
     });
   });
+
+  it('handles upgrade/downgrade plan change for premium subscription (Android only)', async () => {
+    // Mock Platform to be Android since iOS doesn't show upgrade/downgrade UI
+    Platform.OS = 'android';
+    const alertSpy = jest.spyOn(Alert, 'alert');
+    requestPurchaseMock.mockResolvedValueOnce(undefined);
+
+    mockIapState({
+      activeSubscriptions: [
+        {
+          productId: 'dev.hyo.martie.premium',
+          transactionId: 'trans-1',
+          transactionDate: Date.now(),
+          isActive: true,
+        } as any,
+      ],
+      subscriptions: [
+        {
+          ...sampleSubscription,
+          subscriptionOfferDetailsAndroid: [
+            {
+              basePlanId: 'premium',
+              offerToken: 'offer-token-monthly',
+              offerTags: [],
+              pricingPhases: {
+                pricingPhaseList: [
+                  {
+                    formattedPrice: '$9.99',
+                    priceAmountMicros: '9990000',
+                    priceCurrencyCode: 'USD',
+                    billingPeriod: 'P1M',
+                    billingCycleCount: 0,
+                    recurrenceMode: 1,
+                  },
+                ],
+              },
+            },
+            {
+              basePlanId: 'premium-year',
+              offerToken: 'offer-token-yearly',
+              offerTags: [],
+              pricingPhases: {
+                pricingPhaseList: [
+                  {
+                    formattedPrice: '$99.99',
+                    priceAmountMicros: '99990000',
+                    priceCurrencyCode: 'USD',
+                    billingPeriod: 'P1Y',
+                    billingCycleCount: 0,
+                    recurrenceMode: 1,
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+    });
+
+    const {getByText} = render(<SubscriptionFlow />);
+
+    // Should show upgrade button for monthly plan (Android only)
+    await waitFor(() => {
+      expect(getByText('⬆️ Upgrade to Yearly Plan')).toBeTruthy();
+    });
+
+    // Press upgrade button
+    fireEvent.press(getByText('⬆️ Upgrade to Yearly Plan'));
+
+    // Should show confirmation alert
+    expect(alertSpy).toHaveBeenCalledWith(
+      'Change Subscription Plan',
+      expect.stringContaining('upgrade to Yearly'),
+      expect.any(Array),
+    );
+  });
+
+  it('displays empty state when no subscriptions available', () => {
+    mockIapState({
+      subscriptions: [],
+    });
+
+    const {getByText} = render(<SubscriptionFlow />);
+
+    expect(
+      getByText('No subscriptions found. Configure products in the console.'),
+    ).toBeTruthy();
+    expect(
+      getByText('No subscriptions found. Please configure your products.'),
+    ).toBeTruthy();
+  });
+
+  it('shows already subscribed for owned products', () => {
+    mockIapState({
+      activeSubscriptions: [
+        {
+          productId: 'dev.hyo.martie.premium',
+        } as any,
+      ],
+    });
+
+    const {getByText} = render(<SubscriptionFlow />);
+
+    // Button should show 'Already Subscribed' and be disabled
+    const button = getByText('Already Subscribed');
+    expect(button).toBeTruthy();
+  });
+
+  it('retries loading subscriptions when retry button pressed', async () => {
+    const {fetchProducts} = mockIapState({
+      subscriptions: [],
+    });
+
+    const {getByText} = render(<SubscriptionFlow />);
+
+    fireEvent.press(getByText('Retry'));
+
+    await waitFor(() => {
+      expect(fetchProducts).toHaveBeenCalledWith({
+        skus: SUBSCRIPTION_PRODUCT_IDS,
+        type: 'subs',
+      });
+    });
+  });
+
+  it('handles connection state changes', () => {
+    mockIapState({
+      connected: false,
+    });
+
+    const {getByText, rerender} = render(<SubscriptionFlow />);
+
+    expect(getByText('Connecting to Store...')).toBeTruthy();
+
+    // Simulate connection established
+    mockIapState({
+      connected: true,
+    });
+
+    rerender(<SubscriptionFlow />);
+
+    expect(getByText('Available Subscriptions')).toBeTruthy();
+  });
+
+  it('opens subscription details modal', async () => {
+    const {getByText} = render(<SubscriptionFlow />);
+
+    // Open subscription details modal
+    fireEvent.press(getByText('ℹ️'));
+
+    await waitFor(() => {
+      expect(getByText('Subscription Details')).toBeTruthy();
+    });
+
+    // Modal content should be displayed
+    expect(getByText('📋 Copy')).toBeTruthy();
+    expect(getByText('🖥️ Console')).toBeTruthy();
+  });
+
+  it('logs subscription data to console', async () => {
+    const consoleSpy = jest.spyOn(console, 'log');
+
+    const {getByText} = render(<SubscriptionFlow />);
+
+    // Open subscription details modal
+    fireEvent.press(getByText('ℹ️'));
+
+    await waitFor(() => {
+      expect(getByText('Subscription Details')).toBeTruthy();
+    });
+
+    // Log to console
+    fireEvent.press(getByText('🖥️ Console'));
+
+    expect(consoleSpy).toHaveBeenCalledWith('=== SUBSCRIPTION DATA ===');
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: 'dev.hyo.martie.premium',
+      }),
+    );
+  });
+
+  it('closes subscription details modal', async () => {
+    const {getByText, queryByText} = render(<SubscriptionFlow />);
+
+    // Open modal
+    fireEvent.press(getByText('ℹ️'));
+
+    await waitFor(() => {
+      expect(getByText('Subscription Details')).toBeTruthy();
+    });
+
+    // Close modal
+    fireEvent.press(getByText('✕'));
+
+    await waitFor(() => {
+      expect(queryByText('Subscription Details')).toBeNull();
+    });
+  });
+
+  it.skip('excludes obfuscatedProfileIdAndroid for subscription upgrades/downgrades (Android)', async () => {
+    // Mock Platform to be Android
+    Platform.OS = 'android';
+    // Mock getAvailablePurchases to return purchase with token
+    jest.fn(() => {
+      console.log('Test: getAvailablePurchases called');
+      return Promise.resolve([
+        {
+          productId: 'dev.hyo.martie.premium',
+          purchaseToken: 'mock-purchase-token-123',
+          purchaseTokenAndroid: 'mock-purchase-token-123',
+          purchaseState: 1,
+        },
+      ]);
+    });
+
+    // For upgrade/downgrade, purchaseTokenAndroid should be included but obfuscatedProfileIdAndroid should not
+    mockIapState({
+      activeSubscriptions: [
+        {
+          productId: 'dev.hyo.martie.premium',
+          transactionId: 'trans-1',
+          transactionDate: Date.now(),
+          isActive: true,
+        } as any,
+      ],
+      subscriptions: [
+        {
+          ...sampleSubscription,
+          subscriptionOfferDetailsAndroid: [
+            {
+              basePlanId: 'premium',
+              offerToken: 'offer-token-monthly',
+              offerTags: [],
+              pricingPhases: {
+                pricingPhaseList: [
+                  {
+                    formattedPrice: '$9.99',
+                    priceAmountMicros: '9990000',
+                    priceCurrencyCode: 'USD',
+                    billingPeriod: 'P1M',
+                    billingCycleCount: 0,
+                    recurrenceMode: 1,
+                  },
+                ],
+              },
+            },
+            {
+              basePlanId: 'premium-year',
+              offerToken: 'offer-token-yearly',
+              offerTags: [],
+              pricingPhases: {
+                pricingPhaseList: [
+                  {
+                    formattedPrice: '$99.99',
+                    priceAmountMicros: '99990000',
+                    priceCurrencyCode: 'USD',
+                    billingPeriod: 'P1Y',
+                    billingCycleCount: 0,
+                    recurrenceMode: 1,
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+    });
+
+    const alertSpy = jest.spyOn(Alert, 'alert');
+    const {getByText} = render(<SubscriptionFlow />);
+
+    // Wait for upgrade button to appear
+    await waitFor(() => {
+      expect(getByText('⬆️ Upgrade to Yearly Plan')).toBeTruthy();
+    });
+
+    // Mock alert to immediately simulate user confirmation
+    alertSpy.mockImplementation((_title, _message, buttons) => {
+      // Simulate user clicking "Confirm" button (second button)
+      if (buttons && buttons[1] && buttons[1].onPress) {
+        const onPress = buttons[1].onPress;
+        // Execute the onPress callback asynchronously to simulate real behavior
+        setImmediate(() => onPress());
+      }
+    });
+
+    // Press upgrade button
+    fireEvent.press(getByText('⬆️ Upgrade to Yearly Plan'));
+
+    // Wait for requestPurchase to be called with proper parameters
+    await waitFor(
+      () => {
+        expect(requestPurchaseMock).toHaveBeenCalled();
+        const lastCall =
+          requestPurchaseMock.mock.calls[
+            requestPurchaseMock.mock.calls.length - 1
+          ];
+        expect(lastCall).toBeDefined();
+        expect(lastCall[0]).toBeDefined();
+
+        const androidRequest = lastCall[0].request?.android;
+        // Should have purchaseTokenAndroid for upgrade
+        expect(androidRequest?.purchaseTokenAndroid).toBe(
+          'mock-purchase-token-123',
+        );
+        // Should NOT have obfuscatedProfileIdAndroid for upgrade
+        expect(androidRequest?.obfuscatedProfileIdAndroid).toBeUndefined();
+      },
+      {timeout: 3000},
+    );
+  });
+
+  it('includes obfuscatedProfileIdAndroid for new subscriptions', () => {
+    mockIapState({
+      subscriptions: [sampleSubscription],
+      activeSubscriptions: [], // No active subscriptions
+    });
+
+    const {getByText} = render(<SubscriptionFlow />);
+
+    // Press subscribe for a new subscription
+    fireEvent.press(getByText('Subscribe'));
+
+    // Verify that requestPurchase was called
+    expect(requestPurchaseMock).toHaveBeenCalled();
+
+    const lastCall =
+      requestPurchaseMock.mock.calls[requestPurchaseMock.mock.calls.length - 1];
+    if (lastCall && lastCall[0]) {
+      const androidRequest = lastCall[0].request?.android;
+      // Should NOT have purchaseTokenAndroid for new purchase
+      expect(androidRequest?.purchaseTokenAndroid).toBeUndefined();
+      // obfuscatedProfileIdAndroid can be included for new purchases (but is optional)
+    }
+  });
 });
diff --git a/example/ios/Podfile.lock b/example/ios/Podfile.lock
index b4579ae89..651313aab 100644
--- a/example/ios/Podfile.lock
+++ b/example/ios/Podfile.lock
@@ -8,7 +8,7 @@ PODS:
   - hermes-engine (0.81.1):
     - hermes-engine/Pre-built (= 0.81.1)
   - hermes-engine/Pre-built (0.81.1)
-  - NitroIap (14.4.7):
+  - NitroIap (14.4.8):
     - boost
     - DoubleConversion
     - fast_float
@@ -2747,8 +2747,8 @@ SPEC CHECKSUMS:
   fmt: a40bb5bd0294ea969aaaba240a927bd33d878cdd
   glog: 5683914934d5b6e4240e497e0f4a3b42d1854183
   hermes-engine: 4f8246b1f6d79f625e0d99472d1f3a71da4d28ca
-  NitroIap: 5b47dc58f50387cadb18bce9d284ba8ff346031b
-  NitroModules: d9c969e83c30ec1e7efc95e0ae58c21db1585c14
+  NitroIap: 4ff64b96fa367e07eb3d2d5b3eb0d64cd2c16b7c
+  NitroModules: 7d693306799405ca141ef5c24efc0936f20a09c0
   openiap: bd45c90b44a0fb4bebaa9c2501598d76c253eb0f
   RCT-Folly: 846fda9475e61ec7bcbf8a3fe81edfcaeb090669
   RCTDeprecation: c4b9e2fd0ab200e3af72b013ed6113187c607077
@@ -2756,69 +2756,69 @@ SPEC CHECKSUMS:
   RCTTypeSafety: 720403058b7c1380c6a3ae5706981d6362962c89
   React: f1486d005993b0af01943af1850d3d4f3b597545
   React-callinvoker: 133f69368c8559e744efa345223625d412f5dfbe
-  React-Core: d6d8c1fd33697cec596d33b820456505ee305686
-  React-CoreModules: 81ab751a7668ba161440f9623b994e1a6a3019fe
-  React-cxxreact: 16f2a2751d0dce8b569f23c1914edc90f655b01b
+  React-Core: 559823921b4f294c2840fa8238ca958a29ddc211
+  React-CoreModules: c41e7bbfabbc420783bb926f45837a0d5e53341e
+  React-cxxreact: 9cb9fa738274a1b36b97ede09c8a6717dec1a20b
   React-debug: e01581e1589f329e61c95b332bf7f4969b10564b
-  React-defaultsnativemodule: e956b1d8fe15cc79d23061db229bf88170565f2f
-  React-domnativemodule: a18b0f7a31b9c75f12fa369baece5542d1265b36
-  React-Fabric: c0237a32c3c0dbea2d2b294c8e95605e1dfe2f57
-  React-FabricComponents: 65b03884bd5d9f24c79a631d7d26f0fa079bc4aa
-  React-FabricImage: de1ea2f2a0b32ad02e5cbb64827d1eec0439cf0d
-  React-featureflags: 02de9c35256cc624269b01d670d99e1fd706ea8d
-  React-featureflagsnativemodule: 8b84e67edbaa7b9318390c5bd3ae19790a74f356
-  React-graphics: 004b40c1b236ea3bb8de6693439bef9797922ba9
-  React-hermes: 2179a018b2f86652f6f33ef23efd9e5ac284b247
-  React-idlecallbacksnativemodule: f54ea68f984b12e42feed1e7110623b2c38df4d1
-  React-ImageManager: 9dd04b7b62bc5397f876ca5fb1b712e700ce390c
-  React-jserrorhandler: 2f90bf50fffea1d012e7f3d717c6adf748b1813d
-  React-jsi: b27208f8866e53238534f65f304903e4eff25e05
-  React-jsiexecutor: 1d3e827797f592c393860dea91aaa6d53c7715e7
-  React-jsinspector: bda319277ae779bc476b736fe3a497c6aed304cd
-  React-jsinspectorcdp: 69e1736edfd5420037680b7b4557fa748c3c8216
-  React-jsinspectornetwork: 7aa707b057c6129b4af59e0c9160436bbab25022
-  React-jsinspectortracing: b4a8a328ad2697f9638daa4b7cc054e0303fa47f
-  React-jsitooling: a6c7e2829437b28665e97a398b3374d443125e24
-  React-jsitracing: d87ae17dd0eef7844e605945da926c5433fe2b51
-  React-logger: d27dd2000f520bf891d24f6e141cde34df41f0ee
-  React-Mapbuffer: 0746ffab5ac0f49b7c9347338e3d0c1d9dd634c8
-  React-microtasksnativemodule: b0fb3f97372df39bda3e657536039f1af227cc29
-  react-native-safe-area-context: 6d8a7b750e496e37bda47c938320bf2c734d441f
-  React-NativeModulesApple: 9ec9240159974c94886ebbe4caec18e3395f6aef
+  React-defaultsnativemodule: bbb39447caa6b6cf9405fa0099f828c083640faa
+  React-domnativemodule: 03744d12b6d56d098531a933730bf1d4cb79bdfb
+  React-Fabric: 530b3993a12a96e8a7cdb9f0ef48e605277b572e
+  React-FabricComponents: 271ec2a9b2c00ac66fd6d1fd24e9e964d907751d
+  React-FabricImage: d0af66e976dbab7f8b81e36dd369fc70727d2695
+  React-featureflags: 269704c8eff86e0485c9d384e286350fcda6eb70
+  React-featureflagsnativemodule: db1e5d88a912fb08a5ece33fcf64e1b732da8467
+  React-graphics: b19d03a01b0722b4dc82f47acb56dc3ed41937e7
+  React-hermes: 811606c0aca5a3f9c6fa8e4994e02ca8f677e68e
+  React-idlecallbacksnativemodule: 3a3df629cd50046c7e4354f9025aefe8f2c84601
+  React-ImageManager: 0d53866c63132791e37bb2373f93044fdef14aa3
+  React-jserrorhandler: d5700d6ab7162fd575287502a3c5d601d98e7f09
+  React-jsi: ece95417fedbed0e7153a855cb8342b7c72ab75e
+  React-jsiexecutor: 2b0bb644b533df2f5c0cd6ade9a4560d0bf1dd84
+  React-jsinspector: 0c160f8510a8852bdf2dac12f0b1949efc18200b
+  React-jsinspectorcdp: f4b84409f453f61ddd8614ad45139bc594ec6bb5
+  React-jsinspectornetwork: 8f2f0ca8c871ca19b571f426002c0012e7fb2aee
+  React-jsinspectortracing: 33f6b977eb8a4bc1e3d1a4b948809aca083143f9
+  React-jsitooling: 2c61529b589e17229a9f0a4a4fc35aa7ad495850
+  React-jsitracing: 838a7b0c013c4aff7d382d7fdc78cf442013ba1d
+  React-logger: 7aef4d74123e5e3d267e5af1fbf5135b5a0d8381
+  React-Mapbuffer: 91e0eab42a6ae7f3e34091a126d70fc53bd3823e
+  React-microtasksnativemodule: 1ead4fe154df3b1ba34b5a9e35ef3c4bdfa72ccb
+  react-native-safe-area-context: c6e2edd1c1da07bdce287fa9d9e60c5f7b514616
+  React-NativeModulesApple: eff2eba56030eb0d107b1642b8f853bc36a833ac
   React-oscompat: b12c633e9c00f1f99467b1e0e0b8038895dae436
-  React-perflogger: ccf4fd2664b00818645e588623c7531a8b32d114
-  React-performancetimeline: a866ba759d8e06e9ba174b4421677edcae487baf
+  React-perflogger: 58d12c4e5df1403030c97b9c621375c312cca454
+  React-performancetimeline: 0ee0a3236c77a4ee6d8a6189089e41e4003d292e
   React-RCTActionSheet: 3f741a3712653611a6bfc5abceb8260af9d0b218
-  React-RCTAnimation: 2edeebfba175cc2e937e2752209ab605d3c48f21
-  React-RCTAppDelegate: e292321e83ee966897244a032216a70930b758d6
-  React-RCTBlob: 8dfb24b6dd4a5af45e1e59e2fd925b2df1e44d08
-  React-RCTFabric: b25b02a2016f5cb15926a60c77a8d75865aa3558
-  React-RCTFBReactNativeSpec: 20338571a1ed853d01da6c68576aa6e8e107b6f6
-  React-RCTImage: c7fe8c2f2ae8bad98ab4d944d5d50a889da4b652
-  React-RCTLinking: 9ac21ce9f1af914bb01c06af3752db2ec840d0ee
-  React-RCTNetwork: 09a5de71d757dbad4b3fe3615839290200b932aa
-  React-RCTRuntime: da3f1e0ce088c20350044cdf1efcd7f8d9b9b40c
-  React-RCTSettings: fee112652ac7569ea9abe910206e1685f5f9adba
-  React-RCTText: 7ee9d0bc16b3a8149f8df6d70c48e724d0db1d89
-  React-RCTVibration: 619d613abaeb05f6fbc2b2e5e33f724f05df8eb8
+  React-RCTAnimation: 408ad69ea136e99a463dd33eadecc29e586b3d72
+  React-RCTAppDelegate: f03b46e80b8a3dbfa84b35abfe123e02f3ceef83
+  React-RCTBlob: bd42e92a00ad22eaab92ffe5c137e7a2f725887a
+  React-RCTFabric: b99ab638c73cf2d57b886eafdbfb2e4909b0eb9a
+  React-RCTFBReactNativeSpec: 7ad9aba0e0655e3f29be0a1c3fd4a888fab04dcf
+  React-RCTImage: 0f1c74f7cd20027f8c34976a211b35d4263a0add
+  React-RCTLinking: 6d7dfc3a74110df56c3a73cc7626bf4415656542
+  React-RCTNetwork: 6a25d8645a80d5b86098675ca39bf8fcf1afa08b
+  React-RCTRuntime: 38bfe9766565ae3293ca230bc51c9c020a8bc98a
+  React-RCTSettings: 651d9ae2cdd32f547ad0d225a2c13886d6ad2358
+  React-RCTText: 9bc66cd288478e23195e01f5cb45eba79986b2b4
+  React-RCTVibration: 371226f5667a00c76d792dcdb5c2e0fcbcde0c3b
   React-rendererconsistency: a05f6c37f9389c53213d1e28798e441fa6fbdbcd
-  React-renderercss: 3decb27a81648fcdee837c59994b51fff5be5a67
-  React-rendererdebug: 3b9a92d36932af52e1b473f2a89ea4b05dbdecdf
-  React-RuntimeApple: 4e35fb74be4b721c2e1fd6d54ec66456fa7043e9
-  React-RuntimeCore: 0fd7ac6e3e9dd20cb47e87c6b9f35832dd445d5e
-  React-runtimeexecutor: 7680156c9f3a5a49c688bc33f9ec5ea1b00527f5
-  React-RuntimeHermes: 435b7104a3c749af6251353dcb7317a8e53cbd73
-  React-runtimescheduler: 8056b916168e446ea44531883928034e62e76a81
-  React-timing: 36da85e32e53008ce73f87528818191e7f2508ba
-  React-utils: 71e53d55ce778c6e7c7c9db4b1b9d63ef8f55289
-  ReactAppDependencyProvider: 448b422f8af1dedf81374eacc90a15439a0ed7f5
-  ReactCodegen: 3baedb0c33f963250c866151b825a3c5194b12f1
-  ReactCommon: e897f9a1b4afab370cfefaaf5fb3c80371bc3937
-  RNCClipboard: 962296f7af77f6c039b683e21c2e2255af9c05df
-  RNScreens: 74985ca8e102294a60cec7513fa84c936fa0b20b
+  React-renderercss: 6e4febfa014b0f53bc171a62b0f713ddbdbb9860
+  React-rendererdebug: e94bf27b9d55ef2795caa8e43aa92abc4a373b8b
+  React-RuntimeApple: 723be5159519eba1cd92449acb29436d21571b82
+  React-RuntimeCore: f58eb0f01065c9d27d91de10b2e4ab4c76d83b0e
+  React-runtimeexecutor: f615ec8742d0b5820170f7c8b4d2c7cb75d93ac9
+  React-RuntimeHermes: fddb258e03d330d1132bb19e78fe51ac2f3f41ac
+  React-runtimescheduler: e92a31460e654ced8587debeec37553315e1b6a5
+  React-timing: 97ada2c47b4c5932e7f773c7d239c52b90d6ca68
+  React-utils: f0949d247a46b4c09f03e5a3cb1167602d0b729a
+  ReactAppDependencyProvider: 3eb9096cb139eb433965693bbe541d96eb3d3ec9
+  ReactCodegen: 4d203eddf6f977caa324640a20f92e70408d648b
+  ReactCommon: ce5d4226dfaf9d5dacbef57b4528819e39d3a120
+  RNCClipboard: 4b58c780f63676367640f23c8e114e9bd0cf86ac
+  RNScreens: 0bbf16c074ae6bb1058a7bf2d1ae017f4306797c
   SocketRocket: d4aabe649be1e368d1318fdf28a022d714d65748
-  Yoga: fa23995c18b65978347b096d0836f4f5093df545
+  Yoga: 11c9686a21e2cd82a094a723649d9f4507200fb0
 
 PODFILE CHECKSUM: f03bb7813aed3d3c0b30414d3d99a1a8d5d800c5
 
-COCOAPODS: 1.15.2
+COCOAPODS: 1.16.2
diff --git a/example/screens/SubscriptionFlow.tsx b/example/screens/SubscriptionFlow.tsx
index 4dfc3930d..b46501e2f 100644
--- a/example/screens/SubscriptionFlow.tsx
+++ b/example/screens/SubscriptionFlow.tsx
@@ -1,4 +1,4 @@
-import {useCallback, useEffect, useMemo, useRef, useState} from 'react';
+import React, {useCallback, useEffect, useMemo, useRef, useState} from 'react';
 import {
   View,
   Text,
@@ -15,6 +15,7 @@ import {
   requestPurchase,
   useIAP,
   deepLinkToSubscriptions,
+  getAvailablePurchases,
   type ActiveSubscription,
   type ProductSubscription,
   type Purchase,
@@ -25,6 +26,185 @@ import Loading from '../src/components/Loading';
 import {SUBSCRIPTION_PRODUCT_IDS} from '../src/utils/constants';
 import PurchaseSummaryRow from '../src/components/PurchaseSummaryRow';
 
+// Extended types for Android-specific properties
+type AndroidSubscriptionDetails = ProductSubscription & {
+  subscriptionOfferDetailsAndroid?: Array<{
+    basePlanId: string;
+    offerToken: string;
+    offerId?: string;
+    offerTags: string[];
+    pricingPhases: {
+      pricingPhaseList: Array<{
+        formattedPrice: string;
+        priceAmountMicros: string;
+        priceCurrencyCode: string;
+        billingPeriod: string;
+        billingCycleCount: number;
+        recurrenceMode: number;
+      }>;
+    };
+  }>;
+};
+
+type ExtendedPurchase = Purchase & {
+  purchaseTokenAndroid?: string;
+  dataAndroid?: {
+    purchaseToken?: string;
+  };
+  purchaseState?: string;
+  offerToken?: string;
+};
+
+type ExtendedActiveSubscription = ActiveSubscription & {
+  basePlanId?: string;
+  purchaseTokenAndroid?: string;
+  _detectedBasePlanId?: string;
+};
+
+// Component for plan change controls
+interface PlanChangeControlsProps {
+  activeSubscriptions: ActiveSubscription[];
+  handlePlanChange: (
+    productId: string,
+    changeType: 'upgrade' | 'downgrade' | 'yearly' | 'monthly',
+    currentBasePlanId: string,
+  ) => void;
+  isProcessing: boolean;
+  lastPurchasedPlan: string | null;
+}
+
+const PlanChangeControls = React.memo(
+  ({
+    activeSubscriptions,
+    handlePlanChange,
+    isProcessing,
+    lastPurchasedPlan,
+  }: PlanChangeControlsProps) => {
+    // Find all premium subscriptions (both monthly and yearly)
+    const premiumSubs = activeSubscriptions.filter(
+      (sub) =>
+        sub.productId === 'dev.hyo.martie.premium' ||
+        sub.productId === 'dev.hyo.martie.premium_year',
+    );
+
+    if (premiumSubs.length === 0) return null;
+
+    // Detect the current plan based on product ID for iOS
+    let currentBasePlan = 'unknown';
+    let activeSub: ActiveSubscription | undefined = undefined;
+
+    if (Platform.OS === 'ios') {
+      // On iOS, find the most recent subscription (in case both exist during transition)
+      // Sort by transaction date to get the most recent one
+      const sortedSubs = [...premiumSubs].sort((a, b) => {
+        const dateA = (a as any).transactionDate || 0;
+        const dateB = (b as any).transactionDate || 0;
+        return dateB - dateA;
+      });
+
+      activeSub = sortedSubs[0];
+
+      // Check for the most recent purchase to determine actual plan
+      // First, check if both products exist (transition state)
+      const hasYearly = premiumSubs.some(
+        (s) => s.productId === 'dev.hyo.martie.premium_year',
+      );
+      const hasMonthly = premiumSubs.some(
+        (s) => s.productId === 'dev.hyo.martie.premium',
+      );
+
+      if (lastPurchasedPlan) {
+        // If we have a recently purchased plan, use that
+        currentBasePlan = lastPurchasedPlan;
+        console.log('Using last purchased plan:', lastPurchasedPlan);
+      } else if (hasYearly && !hasMonthly) {
+        // Only yearly exists - user has yearly
+        currentBasePlan = 'premium-year';
+      } else if (!hasYearly && hasMonthly) {
+        // Only monthly exists - user has monthly
+        currentBasePlan = 'premium';
+      } else if (activeSub) {
+        // Both exist or transition state - use the most recent one
+        if (activeSub.productId === 'dev.hyo.martie.premium_year') {
+          currentBasePlan = 'premium-year';
+        } else if (activeSub.productId === 'dev.hyo.martie.premium') {
+          currentBasePlan = 'premium';
+        }
+      }
+    } else {
+      // Android uses base plans within the same product
+      activeSub = premiumSubs[0];
+      const extendedSub = activeSub as ExtendedActiveSubscription;
+      if (extendedSub.basePlanId) {
+        currentBasePlan = extendedSub.basePlanId;
+      } else if (lastPurchasedPlan) {
+        currentBasePlan = lastPurchasedPlan;
+      } else {
+        // Default to monthly if we can't detect
+        currentBasePlan = 'premium';
+      }
+    }
+
+    console.log(
+      'Button section - current base plan:',
+      currentBasePlan,
+      'Active sub:',
+      activeSub?.productId,
+    );
+
+    // iOS doesn't need upgrade/downgrade buttons as it's handled automatically by the App Store
+    if (Platform.OS === 'ios') {
+      return null;
+    }
+
+    return (
+      <View style={styles.planChangeSection}>
+        {currentBasePlan === 'premium' && (
+          <TouchableOpacity
+            style={[styles.changePlanButton, styles.upgradeButton]}
+            onPress={() =>
+              handlePlanChange(
+                activeSub?.productId || 'dev.hyo.martie.premium',
+                'upgrade',
+                'premium',
+              )
+            }
+            disabled={isProcessing}
+          >
+            <Text style={styles.changePlanButtonText}>
+              ⬆️ Upgrade to Yearly Plan
+            </Text>
+            <Text style={styles.changePlanButtonSubtext}>
+              Save with annual billing
+            </Text>
+          </TouchableOpacity>
+        )}
+
+        {currentBasePlan === 'premium-year' && (
+          <TouchableOpacity
+            style={[styles.changePlanButton, styles.downgradeButton]}
+            onPress={() =>
+              handlePlanChange(
+                activeSub?.productId || 'dev.hyo.martie.premium_year',
+                'downgrade',
+                'premium-year',
+              )
+            }
+            disabled={isProcessing}
+          >
+            <Text style={styles.changePlanButtonText}>
+              ⬇️ Downgrade to Monthly Plan
+            </Text>
+            <Text style={styles.changePlanButtonSubtext}>
+              More flexibility with monthly billing
+            </Text>
+          </TouchableOpacity>
+        )}
+      </View>
+    );
+  },
+);
+
 /**
  * Subscription Flow Example - Subscription Products
  *
@@ -49,6 +229,12 @@ type SubscriptionFlowProps = {
   isProcessing: boolean;
   isCheckingStatus: boolean;
   lastPurchase: Purchase | null;
+  lastPurchasedPlan: string | null;
+  cachedAvailablePurchases: Purchase[];
+  setCachedAvailablePurchases: (purchases: Purchase[]) => void;
+  setIsProcessing: (value: boolean) => void;
+  setPurchaseResult: (value: string) => void;
+  setLastPurchasedPlan: (value: string | null) => void;
   onSubscribe: (productId: string) => void;
   onRetryLoadSubscriptions: () => void;
   onRefreshStatus: () => void;
@@ -63,6 +249,11 @@ function SubscriptionFlow({
   isProcessing,
   isCheckingStatus,
   lastPurchase,
+  lastPurchasedPlan,
+  cachedAvailablePurchases,
+  setCachedAvailablePurchases,
+  setIsProcessing,
+  setPurchaseResult,
   onSubscribe,
   onRetryLoadSubscriptions,
   onRefreshStatus,
@@ -98,6 +289,240 @@ function SubscriptionFlow({
     setModalVisible(true);
   };
 
+  const handlePlanChange = useCallback(
+    (
+      currentProductId: string,
+      changeType: 'upgrade' | 'downgrade' | 'yearly' | 'monthly',
+      currentBasePlanId: string,
+    ) => {
+      // iOS doesn't use this function anymore as upgrade/downgrade is handled by App Store
+      if (Platform.OS === 'ios') {
+        return;
+      }
+
+      // Android uses the same product with different base plans
+      const targetProductId = 'dev.hyo.martie.premium';
+
+      // Find the subscription with the target base plan
+      const targetSubscription = subscriptions.find(
+        (s) => s.id === targetProductId,
+      );
+
+      if (!targetSubscription) {
+        Alert.alert('Error', 'Target subscription plan not found');
+        return;
+      }
+
+      // Determine target base plan based on current plan and change type
+      let targetBasePlanId = '';
+      let actionDescription = '';
+
+      if (currentBasePlanId === 'premium') {
+        // Currently on monthly, can only upgrade
+        if (changeType === 'upgrade' || changeType === 'yearly') {
+          targetBasePlanId = 'premium-year';
+          actionDescription = 'upgrade to Yearly';
+        } else {
+          Alert.alert('Info', 'You are already on the Monthly plan');
+          return;
+        }
+      } else if (currentBasePlanId === 'premium-year') {
+        // Currently on yearly, can only downgrade
+        if (changeType === 'downgrade' || changeType === 'monthly') {
+          targetBasePlanId = 'premium';
+          actionDescription = 'downgrade to Monthly';
+        } else {
+          Alert.alert('Info', 'You are already on the Yearly plan');
+          return;
+        }
+      } else {
+        // Can't detect current plan, allow switching to either
+        if (changeType === 'upgrade' || changeType === 'yearly') {
+          targetBasePlanId = 'premium-year';
+          actionDescription = 'switch to Yearly';
+        } else if (changeType === 'downgrade' || changeType === 'monthly') {
+          targetBasePlanId = 'premium';
+          actionDescription = 'switch to Monthly';
+        }
+      }
+
+      console.log('Plan change:', {
+        currentBasePlanId,
+        targetBasePlanId,
+        changeType,
+      });
+
+      Alert.alert(
+        'Change Subscription Plan',
+        `Do you want to ${actionDescription} plan?`,
+        [
+          {
+            text: 'Cancel',
+            style: 'cancel',
+          },
+          {
+            text: 'Confirm',
+            onPress: async () => {
+              setIsProcessing(true);
+              setPurchaseResult('Processing plan change...');
+
+              // Get the current subscription to find purchase token
+              const currentSub = activeSubscriptions.find(
+                (s) => s.productId === currentProductId,
+              );
+
+              if (Platform.OS === 'android') {
+                // Android subscription replacement
+                const targetSubWithDetails =
+                  targetSubscription as AndroidSubscriptionDetails;
+                const androidOffers =
+                  targetSubWithDetails.subscriptionOfferDetailsAndroid;
+                const targetOffer = androidOffers?.find(
+                  (offer) => offer.basePlanId === targetBasePlanId,
+                );
+
+                if (!targetOffer) {
+                  Alert.alert('Error', 'Target plan not available');
+                  setIsProcessing(false);
+                  return;
+                }
+
+                // For Android, we need to get the purchase token from available purchases
+                // The activeSubscriptions might not have the purchase token
+                const getPurchaseToken = async () => {
+                  try {
+                    // Use cached purchases if available, otherwise fetch once
+                    let availablePurchases = cachedAvailablePurchases;
+                    if (availablePurchases.length === 0) {
+                      console.log('No cached purchases, fetching...');
+                      availablePurchases = await getAvailablePurchases();
+                      setCachedAvailablePurchases(availablePurchases);
+                    }
+
+                    const currentPurchase = availablePurchases.find(
+                      (p: Purchase) => p.productId === currentProductId,
+                    ) as ExtendedPurchase | undefined;
+
+                    // Check multiple possible token fields
+                    const extendedPurchase = currentPurchase as
+                      | ExtendedPurchase
+                      | undefined;
+                    const token =
+                      extendedPurchase?.purchaseToken ||
+                      extendedPurchase?.purchaseTokenAndroid ||
+                      extendedPurchase?.dataAndroid?.purchaseToken;
+
+                    console.log('Found purchase with token:', {
+                      productId: currentPurchase?.productId,
+                      hasToken: !!token,
+                      tokenLength: token?.length,
+                      purchaseState: currentPurchase?.purchaseState,
+                    });
+
+                    return token;
+                  } catch (e) {
+                    console.error('Failed to get purchase token:', e);
+                    const extendedSub = currentSub as
+                      | ExtendedActiveSubscription
+                      | undefined;
+                    return (
+                      extendedSub?.purchaseToken ||
+                      extendedSub?.purchaseTokenAndroid
+                    );
+                  }
+                };
+
+                const purchaseToken = await getPurchaseToken();
+
+                if (!purchaseToken) {
+                  Alert.alert(
+                    'Error',
+                    'Unable to find current subscription purchase token. Please try refreshing your subscription status.',
+                  );
+                  setIsProcessing(false);
+                  return;
+                }
+
+                // Make sure purchase token is a string
+                const tokenString =
+                  typeof purchaseToken === 'string'
+                    ? purchaseToken
+                    : String(purchaseToken);
+
+                // Use replacement mode for Android
+                // ProrationMode constants from Google Play Billing:
+                // 1 = IMMEDIATE_WITH_TIME_PRORATION
+                // 2 = IMMEDIATE_AND_CHARGE_PRORATED_PRICE
+                // 3 = IMMEDIATE_AND_CHARGE_FULL_PRICE
+                // 4 = DEFERRED
+                // 5 = IMMEDIATE_WITHOUT_PRORATION
+                // For same product with different offers, OpenIAP uses CHARGE_FULL_PRICE (5)
+                const replacementMode = 5; // IMMEDIATE_WITHOUT_PRORATION as per OpenIAP example
+
+                console.log('Plan change params:', {
+                  skus: [targetProductId],
+                  currentBasePlanId,
+                  targetBasePlanId,
+                  offerToken: targetOffer.offerToken,
+                  replacementMode,
+                  purchaseToken: tokenString
+                    ? `<${tokenString.substring(0, 10)}...>`
+                    : 'missing',
+                  allOffers: androidOffers?.map((o) => ({
+                    basePlanId: o.basePlanId,
+                    offerId: o.offerId,
+                    offerToken: o.offerToken?.substring(0, 20) + '...',
+                  })),
+                });
+
+                // Make the request with proper token
+                void requestPurchase({
+                  request: {
+                    android: {
+                      skus: [targetProductId],
+                      subscriptionOffers: [
+                        {
+                          sku: targetProductId,
+                          offerToken: targetOffer.offerToken,
+                        },
+                      ],
+                      replacementModeAndroid: replacementMode,
+                      purchaseTokenAndroid: tokenString,
+                    },
+                  },
+                  type: 'subs',
+                }).catch((err: PurchaseError) => {
+                  console.error('Plan change failed:', err);
+                  console.error('Full error:', JSON.stringify(err));
+
+                  // More helpful error messages
+                  let errorMessage = err.message;
+                  if (
+                    err.message?.includes('DEVELOPER_ERROR') ||
+                    err.message?.includes('Invalid arguments')
+                  ) {
+                    errorMessage =
+                      'Unable to change subscription plan. This may be due to:\n' +
+                      '• Subscriptions not being in the same group in Play Console\n' +
+                      '• Invalid offer configuration\n' +
+                      '• Missing purchase token\n\n' +
+                      'Original error: ' +
+                      err.message;
+                  }
+
+                  setIsProcessing(false);
+                  setPurchaseResult(`❌ Plan change failed: ${err.message}`);
+                  Alert.alert('Plan Change Failed', errorMessage);
+                });
+              }
+            },
+          },
+        ],
+      );
+    },
+    [subscriptions, activeSubscriptions, setIsProcessing, setPurchaseResult],
+  );
+
   const copyToClipboard = (subscription: ProductSubscription) => {
     const jsonString = JSON.stringify(subscription, null, 2);
     Clipboard.setString(jsonString);
@@ -239,44 +664,184 @@ function SubscriptionFlow({
               </Text>
             </View>
 
-            {activeSubscriptions.map((sub: any, index: number) => (
-              <View
-                key={sub.productId + index}
-                style={styles.subscriptionStatusItem}
-              >
-                <View style={styles.statusRow}>
-                  <Text style={styles.statusLabel}>Product:</Text>
-                  <Text style={styles.statusValue}>{sub.productId}</Text>
-                </View>
+            {(() => {
+              // For iOS, filter to show only the most recent subscription in the group
+              let subsToShow = [...activeSubscriptions];
 
-                {sub.expirationDateIOS && (
-                  <View style={styles.statusRow}>
-                    <Text style={styles.statusLabel}>Expires:</Text>
-                    <Text style={styles.statusValue}>
-                      {sub.expirationDateIOS?.toLocaleDateString()}
-                    </Text>
-                  </View>
-                )}
-
-                {Platform.OS === 'android' && sub.isActive !== undefined && (
-                  <View style={styles.statusRow}>
-                    <Text style={styles.statusLabel}>Auto-Renew:</Text>
-                    <Text
-                      style={[
-                        styles.statusValue,
-                        sub.isActive
-                          ? styles.activeStatus
-                          : styles.cancelledStatus,
-                      ]}
-                    >
-                      {sub.isActive ? '✅ Enabled' : '⚠️ Cancelled'}
-                    </Text>
+              if (Platform.OS === 'ios') {
+                // Filter out duplicates for iOS subscription group
+                const premiumSubs = activeSubscriptions.filter(
+                  (sub) =>
+                    sub.productId === 'dev.hyo.martie.premium' ||
+                    sub.productId === 'dev.hyo.martie.premium_year',
+                );
+
+                if (premiumSubs.length > 1) {
+                  // Sort by transaction date and keep only the most recent
+                  const sortedPremiumSubs = [...premiumSubs].sort((a, b) => {
+                    const dateA = (a as any).transactionDate || 0;
+                    const dateB = (b as any).transactionDate || 0;
+                    return dateB - dateA;
+                  });
+
+                  const mostRecentPremium = sortedPremiumSubs[0];
+
+                  // Filter out old premium subscriptions, keep only the most recent
+                  subsToShow = activeSubscriptions.filter((sub) => {
+                    if (
+                      sub.productId === 'dev.hyo.martie.premium' ||
+                      sub.productId === 'dev.hyo.martie.premium_year'
+                    ) {
+                      return sub === mostRecentPremium;
+                    }
+                    return true; // Keep all non-premium subscriptions
+                  });
+                }
+              }
+
+              return subsToShow.map((sub: any, index: number) => {
+                // Find the matching subscription to get offer details
+                const matchingSubscription = subscriptions.find(
+                  (s) => s.id === sub.productId,
+                );
+
+                // Plan detection for dev.hyo.martie.premium
+                let activeOfferLabel = '';
+                let detectedBasePlanId = '';
+
+                if (
+                  (sub.productId === 'dev.hyo.martie.premium' ||
+                    sub.productId === 'dev.hyo.martie.premium_year') &&
+                  matchingSubscription
+                ) {
+                  // Log the full data to understand what's available
+                  console.log(
+                    'ActiveSubscription data:',
+                    JSON.stringify(sub, null, 2),
+                  );
+                  console.log(
+                    'Product ID:',
+                    sub.productId,
+                    'Is Upgraded?:',
+                    (sub as any).isUpgradedIOS,
+                  );
+
+                  if (Platform.OS === 'ios') {
+                    // iOS: Detect based on product ID
+                    if (sub.productId === 'dev.hyo.martie.premium_year') {
+                      detectedBasePlanId = 'premium-year';
+                      activeOfferLabel = '📅 Yearly Plan';
+                    } else {
+                      detectedBasePlanId = 'premium';
+                      activeOfferLabel = '📆 Monthly Plan';
+                    }
+                  } else {
+                    // Android: Try to detect the base plan from various sources
+                    // Method 1: Check if basePlanId is directly available from native
+                    if ((sub as any).basePlanId) {
+                      detectedBasePlanId = (sub as any).basePlanId;
+                      activeOfferLabel =
+                        detectedBasePlanId === 'premium-year'
+                          ? '📅 Yearly Plan'
+                          : '📆 Monthly Plan';
+                    }
+                    // Method 2: Check localStorage for last purchased plan
+                    else {
+                      // Try to get from state
+                      const storedPlan = lastPurchasedPlan;
+
+                      if (storedPlan === 'premium-year') {
+                        detectedBasePlanId = 'premium-year';
+                        activeOfferLabel = '📅 Yearly Plan';
+                      } else {
+                        // Default to monthly
+                        detectedBasePlanId = 'premium';
+                        activeOfferLabel = '📆 Monthly Plan';
+                      }
+
+                      console.log(
+                        'Detected plan from state:',
+                        storedPlan || 'none (defaulting to monthly)',
+                      );
+                    }
+                  }
+
+                  // We'll use this detectedBasePlanId in the button section below
+                }
+
+                // No need for separate handling since we already check both products above
+
+                return (
+                  <View
+                    key={sub.productId + index}
+                    style={styles.subscriptionStatusItem}
+                  >
+                    <View style={styles.statusRow}>
+                      <Text style={styles.statusLabel}>Product:</Text>
+                      <Text style={styles.statusValue}>{sub.productId}</Text>
+                    </View>
+
+                    {activeOfferLabel &&
+                      (sub.productId === 'dev.hyo.martie.premium' ||
+                        sub.productId === 'dev.hyo.martie.premium_year') && (
+                        <View style={styles.statusRow}>
+                          <Text style={styles.statusLabel}>Current Plan:</Text>
+                          <Text style={[styles.statusValue, styles.offerLabel]}>
+                            {activeOfferLabel}
+                          </Text>
+                        </View>
+                      )}
+
+                    {sub.expirationDateIOS && (
+                      <View style={styles.statusRow}>
+                        <Text style={styles.statusLabel}>Expires:</Text>
+                        <Text style={styles.statusValue}>
+                          {new Date(sub.expirationDateIOS).toLocaleDateString()}
+                        </Text>
+                      </View>
+                    )}
+
+                    {Platform.OS === 'android' &&
+                      sub.isActive !== undefined && (
+                        <View style={styles.statusRow}>
+                          <Text style={styles.statusLabel}>Auto-Renew:</Text>
+                          <Text
+                            style={[
+                              styles.statusValue,
+                              sub.isActive
+                                ? styles.activeStatus
+                                : styles.cancelledStatus,
+                            ]}
+                          >
+                            {sub.isActive ? '✅ Enabled' : '⚠️ Cancelled'}
+                          </Text>
+                        </View>
+                      )}
+
+                    {sub.transactionId && (
+                      <View style={styles.statusRow}>
+                        <Text style={styles.statusLabel}>Transaction ID:</Text>
+                        <Text
+                          style={[styles.statusValue, styles.transactionId]}
+                        >
+                          {sub.transactionId.substring(0, 10)}...
+                        </Text>
+                      </View>
+                    )}
                   </View>
-                )}
-              </View>
-            ))}
+                );
+              });
+            })()}
           </View>
 
+          {/* Upgrade/Downgrade button for Android only */}
+          <PlanChangeControls
+            activeSubscriptions={activeSubscriptions}
+            handlePlanChange={handlePlanChange}
+            isProcessing={isProcessing}
+            lastPurchasedPlan={lastPurchasedPlan}
+          />
+
           <TouchableOpacity
             style={styles.refreshButton}
             onPress={onRefreshStatus}
@@ -446,10 +1011,17 @@ function SubscriptionFlowContainer() {
   const [isCheckingStatus, setIsCheckingStatus] = useState(false);
   const [purchaseResult, setPurchaseResult] = useState('');
   const [lastPurchase, setLastPurchase] = useState<Purchase | null>(null);
+  const [lastPurchasedPlan, setLastPurchasedPlan] = useState<string | null>(
+    null,
+  );
+  const [cachedAvailablePurchases, setCachedAvailablePurchases] = useState<
+    Purchase[]
+  >([]);
   const lastSuccessAtRef = useRef(0);
   const connectedRef = useRef(false);
   const fetchedProductsOnceRef = useRef(false);
   const statusAutoCheckedRef = useRef(false);
+  const fetchedAvailablePurchasesRef = useRef(false);
 
   const {
     connected,
@@ -462,6 +1034,52 @@ function SubscriptionFlowContainer() {
     onPurchaseSuccess: async (purchase: Purchase) => {
       const {purchaseToken, ...safePurchase} = purchase || {};
       console.log('Purchase successful (redacted):', safePurchase);
+
+      // Try to detect which plan was purchased
+      if (Platform.OS === 'ios') {
+        // iOS uses separate products
+        if (purchase.productId === 'dev.hyo.martie.premium_year') {
+          setLastPurchasedPlan('premium-year');
+          console.log('Detected yearly plan from purchase (iOS)');
+        } else if (purchase.productId === 'dev.hyo.martie.premium') {
+          setLastPurchasedPlan('premium');
+          console.log('Detected monthly plan from purchase (iOS)');
+        }
+      } else if (purchase.productId === 'dev.hyo.martie.premium') {
+        // Android: Check if we have offerToken or other data to identify the plan
+        const purchaseData = purchase as any;
+
+        // Log full purchase data to understand what's available
+        console.log(
+          'Full purchase data for plan detection:',
+          JSON.stringify(purchaseData, null, 2),
+        );
+
+        // Map offerToken to basePlanId using fetched subscription data
+        if (purchaseData.offerToken) {
+          const premiumSub = subscriptions.find(
+            (s) => s.id === 'dev.hyo.martie.premium',
+          ) as any;
+          const matchingOffer =
+            premiumSub?.subscriptionOfferDetailsAndroid?.find(
+              (offer: any) => offer.offerToken === purchaseData.offerToken,
+            );
+          if (matchingOffer?.basePlanId) {
+            setLastPurchasedPlan(matchingOffer.basePlanId);
+            console.log(
+              'Detected plan from offerToken (Android):',
+              matchingOffer.basePlanId,
+            );
+          } else {
+            // Fallback if we can't find the matching offer
+            console.log(
+              'Could not map offerToken to basePlanId:',
+              purchaseData.offerToken,
+            );
+          }
+        }
+      }
+
       lastSuccessAtRef.current = Date.now();
       setLastPurchase(purchase);
       setIsProcessing(false);
@@ -499,9 +1117,14 @@ function SubscriptionFlowContainer() {
       }
 
       try {
-        await getActiveSubscriptions(SUBSCRIPTION_PRODUCT_IDS);
+        // Refresh both active subscriptions and available purchases after successful purchase
+        const [, purchases] = await Promise.all([
+          getActiveSubscriptions(SUBSCRIPTION_PRODUCT_IDS),
+          getAvailablePurchases(),
+        ]);
+        setCachedAvailablePurchases(purchases);
       } catch (e) {
-        console.warn('Failed to refresh active subscriptions:', e);
+        console.warn('Failed to refresh subscriptions:', e);
       }
 
       setPurchaseResult(
@@ -539,6 +1162,19 @@ function SubscriptionFlowContainer() {
         });
         fetchedProductsOnceRef.current = true;
       }
+
+      // Fetch available purchases once when connected
+      if (!fetchedAvailablePurchasesRef.current) {
+        getAvailablePurchases()
+          .then((purchases) => {
+            setCachedAvailablePurchases(purchases);
+            fetchedAvailablePurchasesRef.current = true;
+            console.log('Cached available purchases:', purchases.length);
+          })
+          .catch((error) => {
+            console.error('Failed to fetch available purchases:', error);
+          });
+      }
     }
   }, [connected, fetchProducts]);
 
@@ -547,7 +1183,31 @@ function SubscriptionFlowContainer() {
 
     setIsCheckingStatus(true);
     try {
-      await getActiveSubscriptions();
+      // Refresh both active subscriptions and available purchases
+      const [activeSubs, purchases] = await Promise.all([
+        getActiveSubscriptions(),
+        getAvailablePurchases(),
+      ]);
+      setCachedAvailablePurchases(purchases);
+      console.log('Refreshed active subscriptions:', activeSubs);
+      console.log('Refreshed available purchases:', purchases);
+
+      // For iOS, check if there's a pending change
+      if (Platform.OS === 'ios') {
+        const premiumPurchases = purchases.filter(
+          (p) =>
+            p.productId === 'dev.hyo.martie.premium' ||
+            p.productId === 'dev.hyo.martie.premium_year',
+        );
+        console.log(
+          'Premium purchases found:',
+          premiumPurchases.map((p) => ({
+            productId: p.productId,
+            transactionDate: new Date(p.transactionDate).toISOString(),
+            isAutoRenewing: p.isAutoRenewing,
+          })),
+        );
+      }
     } catch (error) {
       console.error('Error checking subscription status:', error);
     } finally {
@@ -585,8 +1245,11 @@ function SubscriptionFlowContainer() {
             subscriptionOffers:
               subscription &&
               'subscriptionOfferDetailsAndroid' in subscription &&
-              subscription.subscriptionOfferDetailsAndroid
-                ? subscription.subscriptionOfferDetailsAndroid.map((offer) => ({
+              (subscription as AndroidSubscriptionDetails)
+                .subscriptionOfferDetailsAndroid
+                ? (
+                    subscription as AndroidSubscriptionDetails
+                  ).subscriptionOfferDetailsAndroid!.map((offer) => ({
                     sku: itemId,
                     offerToken: offer.offerToken,
                   }))
@@ -632,6 +1295,12 @@ function SubscriptionFlowContainer() {
       isProcessing={isProcessing}
       isCheckingStatus={isCheckingStatus}
       lastPurchase={lastPurchase}
+      lastPurchasedPlan={lastPurchasedPlan}
+      cachedAvailablePurchases={cachedAvailablePurchases}
+      setCachedAvailablePurchases={setCachedAvailablePurchases}
+      setIsProcessing={setIsProcessing}
+      setPurchaseResult={setPurchaseResult}
+      setLastPurchasedPlan={setLastPurchasedPlan}
       onSubscribe={handleSubscription}
       onRetryLoadSubscriptions={handleRetryLoadSubscriptions}
       onRefreshStatus={handleRefreshStatus}
@@ -993,4 +1662,64 @@ const styles = StyleSheet.create({
     color: '#1a1f36',
     marginBottom: 6,
   },
+  offerLabel: {
+    fontWeight: '600',
+    color: '#1f3c88',
+  },
+  transactionId: {
+    fontFamily: Platform.OS === 'ios' ? 'Courier New' : 'monospace',
+    fontSize: 12,
+    color: '#5f6470',
+  },
+  planChangeSection: {
+    marginTop: 16,
+    marginBottom: 8,
+  },
+  planChangeOptions: {
+    gap: 8,
+  },
+  changePlanButton: {
+    paddingVertical: 14,
+    paddingHorizontal: 16,
+    borderRadius: 12,
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginBottom: 8,
+  },
+  changePlanButtonText: {
+    color: 'white',
+    fontWeight: '600',
+    fontSize: 15,
+  },
+  changePlanButtonSubtext: {
+    color: 'rgba(255, 255, 255, 0.8)',
+    fontSize: 12,
+    marginTop: 4,
+  },
+  upgradeButton: {
+    backgroundColor: '#4CAF50',
+  },
+  downgradeButton: {
+    backgroundColor: '#FF9800',
+  },
+  switchButton: {
+    backgroundColor: '#2196F3',
+  },
+  selectButton: {
+    backgroundColor: '#9C27B0',
+  },
+  warningText: {
+    fontSize: 13,
+    color: '#FF9800',
+    textAlign: 'center',
+    marginBottom: 12,
+    lineHeight: 18,
+  },
+  questionText: {
+    fontSize: 14,
+    fontWeight: '600',
+    textAlign: 'center',
+    marginBottom: 12,
+    color: '#1a1f36',
+  },
 });
diff --git a/example/src/utils/constants.ts b/example/src/utils/constants.ts
index ce6b00a5a..2f27b995b 100644
--- a/example/src/utils/constants.ts
+++ b/example/src/utils/constants.ts
@@ -14,5 +14,8 @@ export const PRODUCT_IDS: string[] = [
   ...NON_CONSUMABLE_PRODUCT_IDS,
 ];
 
-export const SUBSCRIPTION_PRODUCT_IDS: string[] = ['dev.hyo.martie.premium'];
+export const SUBSCRIPTION_PRODUCT_IDS: string[] = [
+  'dev.hyo.martie.premium',
+  'dev.hyo.martie.premium_year',
+];
 export const DEFAULT_SUBSCRIPTION_PRODUCT_ID = SUBSCRIPTION_PRODUCT_IDS[0];
diff --git a/openiap-versions.json b/openiap-versions.json
index 624345efe..89c907527 100644
--- a/openiap-versions.json
+++ b/openiap-versions.json
@@ -1,5 +1,5 @@
 {
   "apple": "1.2.4",
-  "google": "1.2.9",
+  "google": "1.2.10",
   "gql": "1.0.9"
 }