Use this page with AI

Copy this into your coding assistant and add your request.

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

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

Subscription Upgrade & Downgrade

Understanding how each platform handles subscription tier changes is crucial for correctly detecting and displaying upgrade/downgrade states in your app. Both iOS and Android support subscription changes, but they handle them differently.

Overview#

When users change their subscription tier (e.g., from monthly to yearly, or from basic to premium), both platforms support upgrades and downgrades:

Upgrades: Moving to a higher-tier or longer-duration subscription
Downgrades: Moving to a lower-tier or shorter-duration subscription

⚠️ Important: Same Subscription Group Required

Subscription upgrades and downgrades only work within the same subscription group. You cannot upgrade or downgrade between subscriptions in different groups.

Platform-specific setup:

iOS (App Store Connect): All tiers (e.g., Basic, Premium, Ultimate) must be in the same Subscription Group
Android (Google Play Console): All tiers must be in the same Subscription Product with different Base Plans

💡 iOS Tip: Row Order Matters

In App Store Connect, the row order in your Subscription Group determines the tier hierarchy:

Position 1 (Top): Automatically recognized as the highest tier
Position 2, 3, ...: Lower tiers in descending order

Example order:

Ultimate (yearly) - Highest tier
Premium (yearly)
Ultimate (monthly)
Premium (monthly)
Basic (yearly)
Basic (monthly) - Lowest tier

StoreKit uses this order to automatically determine whether a subscription change is an upgrade or downgrade.

The key difference is in how and when these changes take effect. Select your platform below to see specific implementation details:

Key Fields to Understand#

📚 transaction.productID vs autoRenewPreference

This is not a bug — it's intentional StoreKit behavior. According to Apple's official documentation and forums:

transaction.productID: The currently active subscription product ID
autoRenewPreference: The product ID that will be used on the next renewal

Key insight from Apple Developer Forums:

Upgrade Behavior (Charged Immediately)#

When a user upgrades to a higher-tier subscription (e.g., monthly → yearly, basic → premium):

User is charged immediately for the new subscription tier
A new transaction is created (though Transaction.updates may initially show the old product - this is a known StoreKit issue)
autoRenewPreference immediately reflects the new product
transaction.productID updates within a few minutes

💡 iOS Tip: Subscription Group Order

Use pendingUpgradeProductId to detect when an upgrade is in progress, especially during the brief period when productId hasn't updated yet.

📝 Code Example: Detecting Upgrades

swift

// Detecting upgrades with pendingUpgradeProductId
let subscriptions = try await getActiveSubscriptions()

for sub in subscriptions {
    if let renewalInfo = sub.renewalInfoIOS,
       let pendingUpgrade = renewalInfo.pendingUpgradeProductId,
       pendingUpgrade != sub.productId {
        print("⚠️ UPGRADE IN PROGRESS")
        print("  Current: \(sub.productId)")
        print("  Upgrading to: \(pendingUpgrade)")

        // Show UI: "Upgrade processing..."
    }
}

Kotlin example

// Detecting upgrades with pendingUpgradeProductId (KMP)
val subscriptions = kmpIapInstance.getActiveSubscriptions()

for (sub in subscriptions) {
    val renewalInfo = sub.renewalInfoIOS
    val pendingUpgrade = renewalInfo?.pendingUpgradeProductId

    if (pendingUpgrade != null && pendingUpgrade != sub.productId) {
        println("⚠️ UPGRADE IN PROGRESS")
        println("  Current: ${sub.productId}")
        println("  Upgrading to: $pendingUpgrade")

        // Show UI: "Upgrade processing..."
    }
}

TypeScript example

// Detecting upgrades with pendingUpgradeProductId
const subscriptions = await getActiveSubscriptions();

for (const sub of subscriptions) {
  const renewalInfo = sub.renewalInfoIOS;
  const pendingUpgrade = renewalInfo?.pendingUpgradeProductId;

  if (pendingUpgrade && pendingUpgrade !== sub.productId) {
    console.log('⚠️ UPGRADE IN PROGRESS');
    console.log(`  Current: ${sub.productId}`);
    console.log(`  Upgrading to: ${pendingUpgrade}`);

    // Show UI: "Upgrade processing..."
  }
}

Dart example

dart

// Detecting upgrades with pendingUpgradeProductId
final subscriptions = await FlutterInappPurchase.instance.getActiveSubscriptions();

for (final sub in subscriptions) {
  final renewalInfo = sub.renewalInfoIOS;
  final pendingUpgrade = renewalInfo?.pendingUpgradeProductId;

  if (pendingUpgrade != null && pendingUpgrade != sub.productId) {
    print('⚠️ UPGRADE IN PROGRESS');
    print('  Current: ${sub.productId}');
    print('  Upgrading to: $pendingUpgrade');

    // Show UI: "Upgrade processing..."
  }
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

// Detecting upgrades with pendingUpgradeProductId.
var subscriptions = await ((QueryResolver)OpenIapClient.Instance).GetActiveSubscriptionsAsync();

foreach (var subscription in subscriptions)
{
    var renewalInfo = subscription.RenewalInfoIOS;
    var pendingUpgrade = renewalInfo?.PendingUpgradeProductId;

    if (pendingUpgrade is not null && pendingUpgrade != subscription.ProductId)
    {
        Console.WriteLine("Upgrade in progress");
        Console.WriteLine(quot;Current: {subscription.ProductId}");
        Console.WriteLine(quot;Upgrading to: {pendingUpgrade}");

        // Show UI: "Upgrade processing..."
    }
}

Kotlin (KMP) example

// Detecting upgrades with pendingUpgradeProductId (KMP)
val subscriptions = kmpIAP.getActiveSubscriptions()

for (sub in subscriptions) {
    val renewalInfo = sub.renewalInfoIOS
    val pendingUpgrade = renewalInfo?.pendingUpgradeProductId

    if (pendingUpgrade != null && pendingUpgrade != sub.productId) {
        println("⚠️ UPGRADE IN PROGRESS")
        println("  Current: ${sub.productId}")
        println("  Upgrading to: $pendingUpgrade")

        // Show UI: "Upgrade processing..."
    }
}

GDScript example

# Detecting upgrades with pending_upgrade_product_id
var subscriptions = await iap.get_active_subscriptions()

for sub in subscriptions:
    var renewal_info = sub.renewal_info_ios
    var pending_upgrade = renewal_info.pending_upgrade_product_id if renewal_info else ""

    if pending_upgrade != "" and pending_upgrade != sub.product_id:
        print("UPGRADE IN PROGRESS")
        print("  Current: %s" % sub.product_id)
        print("  Upgrading to: %s" % pending_upgrade)

        # Show UI: "Upgrade processing..."

Downgrade Behavior (Applied at Next Renewal)#

When a user downgrades to a lower-tier subscription (e.g., yearly → monthly, premium → basic):

No new transaction is created
Change is reflected in the renewalInfo object only
autoRenewPreference indicates the new (downgraded) product (Stack Overflow - autoRenewalPreference usage)
transaction.productID remains unchanged until the renewal date
User retains access to current tier until expiration

Check autoRenewPreference against productId to detect scheduled downgrades and inform users when the change will take effect.

📝 Code Example: Detecting Downgrades

swift

// Detecting downgrades
let subscriptions = try await getActiveSubscriptions()

for sub in subscriptions {
    if let renewalInfo = sub.renewalInfoIOS,
       let autoRenewPref = renewalInfo.autoRenewPreference,
       autoRenewPref != sub.productId,
       renewalInfo.willAutoRenew {
        print("⚠️ DOWNGRADE SCHEDULED")
        print("  Current (until \(sub.expirationDateIOS ?? 0)): \(sub.productId)")
        print("  Next: \(autoRenewPref)")

        // Show UI: "Your plan will change to [tier] on [date]"
    }
}

Kotlin example

// Detecting downgrades (KMP)
val subscriptions = kmpIapInstance.getActiveSubscriptions()

for (sub in subscriptions) {
    val renewalInfo = sub.renewalInfoIOS
    val autoRenewPref = renewalInfo?.autoRenewPreference

    if (autoRenewPref != null && autoRenewPref != sub.productId && renewalInfo?.willAutoRenew == true) {
        println("⚠️ DOWNGRADE SCHEDULED")
        println("  Current (until ${sub.expirationDateIOS}): ${sub.productId}")
        println("  Next: $autoRenewPref")

        // Show UI: "Your plan will change to [tier] on [date]"
    }
}

TypeScript example

// Detecting downgrades
const subscriptions = await getActiveSubscriptions();

for (const sub of subscriptions) {
  const renewalInfo = sub.renewalInfoIOS;
  const autoRenewPref = renewalInfo?.autoRenewPreference;

  if (autoRenewPref && autoRenewPref !== sub.productId && renewalInfo?.willAutoRenew) {
    console.log('⚠️ DOWNGRADE SCHEDULED');
    console.log(`  Current (until ${sub.expirationDateIOS}): ${sub.productId}`);
    console.log(`  Next: ${autoRenewPref}`);

    // Show UI: "Your plan will change to [tier] on [date]"
  }
}

Dart example

dart

// Detecting downgrades
final subscriptions = await FlutterInappPurchase.instance.getActiveSubscriptions();

for (final sub in subscriptions) {
  final renewalInfo = sub.renewalInfoIOS;
  final autoRenewPref = renewalInfo?.autoRenewPreference;

  if (autoRenewPref != null && autoRenewPref != sub.productId && renewalInfo?.willAutoRenew == true) {
    print('⚠️ DOWNGRADE SCHEDULED');
    print('  Current (until ${sub.expirationDateIOS}): ${sub.productId}');
    print('  Next: $autoRenewPref');

    // Show UI: "Your plan will change to [tier] on [date]"
  }
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

// Detecting downgrades.
var subscriptions = await ((QueryResolver)OpenIapClient.Instance).GetActiveSubscriptionsAsync();

foreach (var subscription in subscriptions)
{
    var renewalInfo = subscription.RenewalInfoIOS;
    var autoRenewPref = renewalInfo?.AutoRenewPreference;

    if (autoRenewPref is not null &&
        autoRenewPref != subscription.ProductId &&
        renewalInfo?.WillAutoRenew == true)
    {
        Console.WriteLine("Downgrade scheduled");
        Console.WriteLine(quot;Current until {subscription.ExpirationDateIOS}: {subscription.ProductId}");
        Console.WriteLine(quot;Next: {autoRenewPref}");

        // Show UI: "Your plan will change to [tier] on [date]"
    }
}

Kotlin (KMP) example

// Detecting downgrades (KMP)
val subscriptions = kmpIAP.getActiveSubscriptions()

for (sub in subscriptions) {
    val renewalInfo = sub.renewalInfoIOS
    val autoRenewPref = renewalInfo?.autoRenewPreference

    if (autoRenewPref != null && autoRenewPref != sub.productId && renewalInfo?.willAutoRenew == true) {
        println("⚠️ DOWNGRADE SCHEDULED")
        println("  Current (until ${sub.expirationDateIOS}): ${sub.productId}")
        println("  Next: $autoRenewPref")

        // Show UI: "Your plan will change to [tier] on [date]"
    }
}

GDScript example

# Detecting downgrades
var subscriptions = await iap.get_active_subscriptions()

for sub in subscriptions:
    var renewal_info = sub.renewal_info_ios
    var auto_renew_pref = renewal_info.auto_renew_preference if renewal_info else ""

    if auto_renew_pref != "" and auto_renew_pref != sub.product_id and renewal_info.will_auto_renew:
        print("DOWNGRADE SCHEDULED")
        print("  Current (until %s): %s" % [sub.expiration_date_ios, sub.product_id])
        print("  Next: %s" % auto_renew_pref)

        # Show UI: "Your plan will change to [tier] on [date]"

Using pendingUpgradeProductId#

The pendingUpgradeProductId field is specifically designed to detect subscription tier changes. It is automatically calculated by comparing productID and autoRenewPreference.

How it works

The field is automatically calculated by comparing autoRenewPreference and productId:

📝 Internal Logic

Usage in your app

Simply check if pendingUpgradeProductId exists to detect tier changes in progress:

📝 Code Example: Using pendingUpgradeProductId

swift

import OpenIAP

let subscriptions = try await OpenIapModule.shared.getActiveSubscriptions(nil)

for sub in subscriptions {
    if let pending = sub.renewalInfoIOS?.pendingUpgradeProductId {
        let current = sub.productId

        print("Upgrading from \(current) to \(pending)")

        // Show upgrade-in-progress UI
        showUpgradeInProgressUI(current: current, pending: pending)
    }
}

Kotlin example

import io.github.hyochan.kmpiap.kmpIapInstance
import io.github.hyochan.kmpiap.requestPurchase

val subscriptions = kmpIapInstance.getActiveSubscriptions()

for (sub in subscriptions) {
    sub.renewalInfoIOS?.pendingUpgradeProductId?.let { pending ->
        val current = sub.productId

        println("Upgrading from $current to $pending")

        // Show upgrade-in-progress UI
        showUpgradeInProgressUI(current, pending)
    }
}

TypeScript example

import { getActiveSubscriptions } from 'expo-iap';

const subscriptions = await getActiveSubscriptions();

for (const sub of subscriptions) {
  if (sub.renewalInfoIOS?.pendingUpgradeProductId) {
    const current = sub.productId;
    const pending = sub.renewalInfoIOS.pendingUpgradeProductId;

    console.log(`Upgrading from ${current} to ${pending}`);

    // Show upgrade-in-progress UI
    showUpgradeInProgressUI(current, pending);
  }
}

Dart example

dart

import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

final subscriptions = await FlutterInappPurchase.instance.getActiveSubscriptions();

for (final sub in subscriptions) {
  final pending = sub.renewalInfoIOS?.pendingUpgradeProductId;
  if (pending != null) {
    final current = sub.productId;

    print('Upgrading from $current to $pending');

    // Show upgrade-in-progress UI
    showUpgradeInProgressUI(current, pending);
  }
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

var subscriptions = await ((QueryResolver)OpenIapClient.Instance).GetActiveSubscriptionsAsync();

foreach (var subscription in subscriptions)
{
    if (subscription.RenewalInfoIOS?.PendingUpgradeProductId is string pending)
    {
        var current = subscription.ProductId;

        Console.WriteLine(quot;Upgrading from {current} to {pending}");

        // Show upgrade-in-progress UI
        ShowUpgradeInProgressUI(current, pending);
    }
}

Kotlin (KMP) example

import io.github.hyochan.kmpiap.kmpIapInstance

val subscriptions = kmpIapInstance.getActiveSubscriptions()

for (sub in subscriptions) {
    sub.renewalInfoIOS?.pendingUpgradeProductId?.let { pending ->
        val current = sub.productId

        println("Upgrading from $current to $pending")

        // Show upgrade-in-progress UI
        showUpgradeInProgressUI(current, pending)
    }
}

GDScript example

var subscriptions = await iap.get_active_subscriptions()

for sub in subscriptions:
    var pending = ""
    if sub.renewal_info_ios:
        pending = sub.renewal_info_ios.pending_upgrade_product_id

    if pending != "":
        var current = sub.product_id

        print("Upgrading from %s to %s" % [current, pending])

        # Show upgrade-in-progress UI
        show_upgrade_in_progress_ui(current, pending)

⚠️ Important: Don't rely on productId alone

After an upgrade, don't rely on productId to be immediately updated. There can be a delay of several minutes. Instead:

Use pendingUpgradeProductId to detect ongoing tier changes
Check autoRenewPreference to see what the next renewal will be
Only use productId for the current active subscription

swift

// ✅ Correct approach
let effectiveTier = renewalInfo.pendingUpgradeProductId ?? subscription.productId

// ❌ Wrong - may show outdated tier immediately after upgrade
let currentTier = subscription.productId

Kotlin example

// ✅ Correct approach
val effectiveTier = renewalInfo?.pendingUpgradeProductId ?: subscription.productId

// ❌ Wrong - may show outdated tier immediately after upgrade
val currentTier = subscription.productId

TypeScript example

// ✅ Correct approach
const effectiveTier = renewalInfo?.pendingUpgradeProductId ?? subscription.productId;

// ❌ Wrong - may show outdated tier immediately after upgrade
const currentTier = subscription.productId;

Dart example

dart

// ✅ Correct approach
final effectiveTier = renewalInfo?.pendingUpgradeProductId ?? subscription.productId;

// ❌ Wrong - may show outdated tier immediately after upgrade
final currentTier = subscription.productId;

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

// ✅ Correct approach
var effectiveTier = renewalInfo?.PendingUpgradeProductId ?? subscription.ProductId;

// ❌ Wrong - may show outdated tier immediately after upgrade
var currentTier = subscription.ProductId;

Kotlin (KMP) example

// ✅ Correct approach
val effectiveTier = renewalInfo?.pendingUpgradeProductId ?: subscription.productId

// ❌ Wrong - may show outdated tier immediately after upgrade
val currentTier = subscription.productId

GDScript example

# Correct approach
var effective_tier = ""
if renewal_info and renewal_info.pending_upgrade_product_id != "":
    effective_tier = renewal_info.pending_upgrade_product_id
else:
    effective_tier = subscription.product_id

# Wrong - may show outdated tier immediately after upgrade
var current_tier = subscription.product_id

Best Practices#

Always check pendingUpgradeProductId when displaying subscription status
Show upgrade-in-progress UI when pendingUpgradeProductId is present
For downgrades, inform users when the change will take effect (at renewal)
Listen to purchase events to update UI when productId finally updates
Test both scenarios in sandbox environment to understand the timing

Here's a complete React component that demonstrates all best practices for handling subscription tier changes:

📝 Complete Example: Subscription Status Component

swift

// Complete example: Subscription status view (SwiftUI)
struct SubscriptionStatusView: View {
    @State private var subscription: ActiveSubscription?

    var body: some View {
        Group {
            if let sub = subscription {
                subscriptionContent(sub)
            } else {
                Text("Loading...")
            }
        }
        .task {
            await loadSubscription()
        }
    }

    @ViewBuilder
    func subscriptionContent(_ sub: ActiveSubscription) -> some View {
        let renewalInfo = sub.renewalInfoIOS
        let pending = renewalInfo?.pendingUpgradeProductId

        if let pending = pending, pending != sub.productId {
            // Upgrade in progress
            VStack {
                Text("⏳ Upgrading to \(pending)...")
                Text("Current: \(sub.productId)")
            }
        } else if let autoRenewPref = renewalInfo?.autoRenewPreference,
                  autoRenewPref != sub.productId,
                  renewalInfo?.willAutoRenew == true {
            // Downgrade scheduled
            VStack {
                Text("Current: \(sub.productId)")
                Text("Will change to \(autoRenewPref) on \(formattedDate(sub.expirationDateIOS))")
            }
        } else {
            // Normal active subscription
            VStack {
                Text("Active: \(sub.productId)")
                Text("Renews: \(formattedDate(renewalInfo?.renewalDate))")
            }
        }
    }

    func loadSubscription() async {
        let subs = try? await OpenIapModule.shared.getActiveSubscriptions(nil)
        subscription = subs?.first
    }
}

Kotlin example

// Complete example: Subscription status (Compose Multiplatform)
@Composable
fun SubscriptionStatus() {
    var subscription by remember { mutableStateOf<ActiveSubscription?>(null) }

    LaunchedEffect(Unit) {
        val subs = kmpIapInstance.getActiveSubscriptions()
        subscription = subs.firstOrNull()
    }

    subscription?.let { sub ->
        val renewalInfo = sub.renewalInfoIOS
        val pending = renewalInfo?.pendingUpgradeProductId

        when {
            pending != null && pending != sub.productId -> {
                // Upgrade in progress
                Column {
                    Text("⏳ Upgrading to $pending...")
                    Text("Current: ${sub.productId}")
                }
            }
            renewalInfo?.autoRenewPreference != sub.productId &&
            renewalInfo?.willAutoRenew == true -> {
                // Downgrade scheduled
                Column {
                    Text("Current: ${sub.productId}")
                    Text("Will change to ${renewalInfo.autoRenewPreference} on ${formatDate(sub.expirationDateIOS)}")
                }
            }
            else -> {
                // Normal active subscription
                Column {
                    Text("Active: ${sub.productId}")
                    Text("Renews: ${formatDate(renewalInfo?.renewalDate)}")
                }
            }
        }
    } ?: Text("Loading...")
}

TypeScript example

// Complete example: Subscription status component (React)
function SubscriptionStatus() {
  const [subscription, setSubscription] = useState(null);

  useEffect(() => {
    async function loadSubscription() {
      const subs = await getActiveSubscriptions();
      setSubscription(subs[0]);
    }

    loadSubscription();

    // Listen for updates
    const unsubscribe = addPurchaseListener((purchase) => {
      loadSubscription(); // Refresh when productId updates
    });

    return unsubscribe;
  }, []);

  if (!subscription) return null;

  const renewalInfo = subscription.renewalInfoIOS;
  const pending = renewalInfo?.pendingUpgradeProductId;

  // Upgrade in progress
  if (pending && pending !== subscription.productId) {
    return (
      <View>
        <Text>⏳ Upgrading to {pending}...</Text>
        <Text>Current: {subscription.productId}</Text>
      </View>
    );
  }

  // Downgrade scheduled
  if (renewalInfo?.autoRenewPreference !== subscription.productId &&
      renewalInfo?.willAutoRenew) {
    return (
      <View>
        <Text>Current: {subscription.productId}</Text>
        <Text>
          Will change to {renewalInfo.autoRenewPreference} on{' '}
          {new Date(subscription.expirationDateIOS).toLocaleDateString()}
        </Text>
      </View>
    );
  }

  // Normal active subscription
  return (
    <View>
      <Text>Active: {subscription.productId}</Text>
      <Text>Renews: {new Date(renewalInfo?.renewalDate).toLocaleDateString()}</Text>
    </View>
  );
}

Dart example

dart

// Complete example: Subscription status widget (Flutter)
class SubscriptionStatus extends StatefulWidget {
  @override
  State<SubscriptionStatus> createState() => _SubscriptionStatusState();
}

class _SubscriptionStatusState extends State<SubscriptionStatus> {
  ActiveSubscription? subscription;

  @override
  void initState() {
    super.initState();
    _loadSubscription();
  }

  Future<void> _loadSubscription() async {
    final subs = await FlutterInappPurchase.instance.getActiveSubscriptions();
    setState(() => subscription = subs.firstOrNull);
  }

  @override
  Widget build(BuildContext context) {
    final sub = subscription;
    if (sub == null) return Text('Loading...');

    final renewalInfo = sub.renewalInfoIOS;
    final pending = renewalInfo?.pendingUpgradeProductId;

    // Upgrade in progress
    if (pending != null && pending != sub.productId) {
      return Column(children: [
        Text('⏳ Upgrading to $pending...'),
        Text('Current: ${sub.productId}'),
      ]);
    }

    // Downgrade scheduled
    if (renewalInfo?.autoRenewPreference != sub.productId &&
        renewalInfo?.willAutoRenew == true) {
      return Column(children: [
        Text('Current: ${sub.productId}'),
        Text('Will change to ${renewalInfo!.autoRenewPreference} on ${_formatDate(sub.expirationDateIOS)}'),
      ]);
    }

    // Normal active subscription
    return Column(children: [
      Text('Active: ${sub.productId}'),
      Text('Renews: ${_formatDate(renewalInfo?.renewalDate)}'),
    ]);
  }

  String _formatDate(int? timestamp) => timestamp != null
      ? DateTime.fromMillisecondsSinceEpoch(timestamp).toLocal().toString()
      : 'N/A';
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

// Complete example: build a subscription status message.
async Task<string> GetSubscriptionStatusMessageAsync()
{
    var subscriptions = await ((QueryResolver)OpenIapClient.Instance).GetActiveSubscriptionsAsync();
    var subscription = subscriptions.FirstOrDefault();

    if (subscription is null)
    {
        return "Loading...";
    }

    var renewalInfo = subscription.RenewalInfoIOS;
    var pending = renewalInfo?.PendingUpgradeProductId;

    if (pending is not null && pending != subscription.ProductId)
    {
        return quot;Upgrading to {pending}. Current: {subscription.ProductId}";
    }

    if (renewalInfo?.AutoRenewPreference != subscription.ProductId &&
        renewalInfo?.WillAutoRenew == true)
    {
        return quot;Current: {subscription.ProductId}. " +
            quot;Will change to {renewalInfo.AutoRenewPreference} on " +
            quot;{FormatDate(subscription.ExpirationDateIOS)}";
    }

    return quot;Active: {subscription.ProductId}. " +
        quot;Renews: {FormatDate(renewalInfo?.RenewalDate)}";
}

static string FormatDate(double? timestamp) =>
    timestamp is null
        ? "N/A"
        : DateTimeOffset.FromUnixTimeMilliseconds((long)timestamp.Value)
            .ToLocalTime()
            .ToString("d");

Kotlin (KMP) example

// Complete example: Subscription status (Compose Multiplatform)
@Composable
fun SubscriptionStatus() {
    var subscription by remember { mutableStateOf<ActiveSubscription?>(null) }

    LaunchedEffect(Unit) {
        val subs = kmpIAP.getActiveSubscriptions()
        subscription = subs.firstOrNull()
    }

    subscription?.let { sub ->
        val renewalInfo = sub.renewalInfoIOS
        val pending = renewalInfo?.pendingUpgradeProductId

        when {
            pending != null && pending != sub.productId -> {
                // Upgrade in progress
                Column {
                    Text("⏳ Upgrading to $pending...")
                    Text("Current: ${sub.productId}")
                }
            }
            renewalInfo?.autoRenewPreference != sub.productId &&
            renewalInfo?.willAutoRenew == true -> {
                // Downgrade scheduled
                Column {
                    Text("Current: ${sub.productId}")
                    Text("Will change to ${renewalInfo.autoRenewPreference} on ${formatDate(sub.expirationDateIOS)}")
                }
            }
            else -> {
                // Normal active subscription
                Column {
                    Text("Active: ${sub.productId}")
                    Text("Renews: ${formatDate(renewalInfo?.renewalDate)}")
                }
            }
        }
    } ?: Text("Loading...")
}

GDScript example

# Complete example: Subscription status (Godot)
extends Control

var subscription: ActiveSubscription = null

func _ready() -> void:
    load_subscription()

func load_subscription() -> void:
    var subs = await iap.get_active_subscriptions()
    if subs.size() > 0:
        subscription = subs[0]
    update_ui()

func update_ui() -> void:
    if not subscription:
        $Label.text = "Loading..."
        return

    var renewal_info = subscription.renewal_info_ios
    var pending = renewal_info.pending_upgrade_product_id if renewal_info else ""

    # Upgrade in progress
    if pending != "" and pending != subscription.product_id:
        $Label.text = "Upgrading to %s...\nCurrent: %s" % [pending, subscription.product_id]
        return

    # Downgrade scheduled
    if renewal_info:
        var auto_renew_pref = renewal_info.auto_renew_preference
        if auto_renew_pref != subscription.product_id and renewal_info.will_auto_renew:
            $Label.text = "Current: %s\nWill change to %s on %s" % [
                subscription.product_id,
                auto_renew_pref,
                format_date(subscription.expiration_date_ios)
            ]
            return

    # Normal active subscription
    var renewal_date = renewal_info.renewal_date if renewal_info else 0
    $Label.text = "Active: %s\nRenews: %s" % [
        subscription.product_id,
        format_date(renewal_date)
    ]

func format_date(timestamp: int) -> String:
    if timestamp == 0:
        return "N/A"
    var datetime = Time.get_datetime_dict_from_unix_time(timestamp / 1000)
    return "%04d-%02d-%02d" % [datetime.year, datetime.month, datetime.day]

Official References#

Apple · App Store Subscriptions
Subscription groups, upgrade/downgrade hierarchy, and tier order
Apple · Product.SubscriptionInfo.RenewalInfo
autoRenewPreference is the source of truth for the next-renewed product ID
Apple Developer Forums: Auto-renewing Subscription Updates
Explains why Transaction.updates may show old product after upgrade
Apple Developer Forums: How to know when user upgrades/downgrades
Official guidance on using autoRenewPreference vs productID
Stack Overflow: autoRenewalPreference usage in StoreKit 2
Community discussion on upgrade vs downgrade transaction behavior

Android example

Key Fields to Understand#

📚 Replacement Modes & Proration

Android uses replacement modes to control how subscription changes are handled:

prorationMode: Determines when the change takes effect and how billing is handled
purchaseToken: Required to identify which subscription to replace

Available replacement modes:

Mode	Legacy API	8.1.0+ API	Description
`WITH_TIME_PRORATION`	1	1	Immediate change with prorated credit
`CHARGE_PRORATED_PRICE`	2	2	Immediate change, charge difference (upgrade only)
`WITHOUT_PRORATION`	3	3	Immediate change, no proration
`CHARGE_FULL_PRICE`	5	4	Immediate change, charge full price
`DEFERRED`	6	5	Change at next billing cycle
`KEEP_EXISTING`	—	6	Keep existing payment schedule (8.1.0+ only)

Note: Legacy API refers to SubscriptionUpdateParams.ReplacementMode, 8.1.0+ API refers to SubscriptionProductReplacementParams.ReplacementMode. The integer values differ for CHARGE_FULL_PRICE and DEFERRED between APIs.

Note: If you don't specify a replacement mode, the system uses the default configured in your Google Play Console subscription settings.

🆕 Billing Library 8.1.0+: Per-Product Replacement Params

Starting with Google Play Billing Library 8.1.0, you can use subscriptionProductReplacementParams for more granular control over subscription replacements at the product level:

oldProductId: The product ID being replaced
replacementMode: The replacement mode enum value

This API is useful when you need different replacement behaviors for different products in a multi-product purchase scenario. The new KEEP_EXISTING mode is only available through this API.

Upgrade Behavior (Immediate with Proration)#

When a user upgrades to a higher-tier subscription on Android (e.g., basic → premium):

User is charged based on the replacement mode (prorated or full amount)
New subscription becomes active immediately
Old subscription is replaced in getAvailablePurchases()

💡 Android Tip: Choose the Right Proration Mode

Specify the prorationModeAndroid parameter when calling requestPurchase() to control upgrade behavior.

📝 Code Example: Upgrading Subscription

Kotlin example

// Android upgrade with proration
import io.github.hyochan.kmpiap.kmpIapInstance
import io.github.hyochan.kmpiap.requestPurchase
import io.github.hyochan.kmpiap.openiap.*
import io.github.hyochan.kmpiap.openiap.*

// Get current subscription
val purchases = kmpIapInstance.getAvailablePurchases()
val currentSub = purchases.find { it.productId == "basic_monthly" }

currentSub?.let { sub ->
    // Upgrade to premium with time proration
    kmpIapInstance.requestPurchase {
        type = ProductType.Subs
        google {
            skus = listOf("premium_monthly")
            purchaseToken = sub.purchaseToken
            subscriptionProductReplacementParams =
                SubscriptionProductReplacementParamsAndroid(
                    oldProductId = sub.productId,
                    replacementMode = SubscriptionReplacementModeAndroid.WithTimeProration
                )
        }
    }

    println("✅ Upgrade initiated")
}

TypeScript example

// Android upgrade with proration
import { requestPurchase, getAvailablePurchases } from 'expo-iap';

// Get current subscription
const purchases = await getAvailablePurchases();
const currentSub = purchases.find(p => p.productId === 'basic_monthly');

if (currentSub) {
  // Upgrade to premium with time proration
  await requestPurchase({
    request: {
      google: {
        skus: ['premium_monthly'],
        purchaseToken: currentSub.purchaseToken,
        subscriptionProductReplacementParams: {
          oldProductId: currentSub.productId,
          replacementMode: 'with-time-proration',
        },
      },
    },
    type: 'subs',
  });

  console.log('✅ Upgrade initiated');
}

Dart example

dart

// Android upgrade with proration
import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

// Get current subscription
final purchases = await FlutterInappPurchase.instance.getAvailablePurchases();
final currentSub = purchases.firstWhere((p) => p.productId == 'basic_monthly');

if (currentSub != null) {
  // Upgrade to premium with time proration
  await FlutterInappPurchase.instance.requestPurchase(
    RequestPurchaseProps.subs((
      apple: null,
      google: RequestSubscriptionAndroidProps(
          skus: ['premium_monthly'],
          purchaseToken: currentSub.purchaseToken,
          subscriptionProductReplacementParams:
              SubscriptionProductReplacementParamsAndroid(
            oldProductId: currentSub.productId,
            replacementMode:
                SubscriptionReplacementModeAndroid.WithTimeProration,
          ),
      ),
    )),
  );

  print('✅ Upgrade initiated');
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;
using System.Linq;

// Android upgrade with proration

// Get current subscription
var purchases = await ((QueryResolver)OpenIapClient.Instance).GetAvailablePurchasesAsync();
var currentSub = purchases
    .OfType<PurchaseCommon>()
    .FirstOrDefault(purchase => purchase.ProductId == "basic_monthly");

if (currentSub is not null)
{
    // Upgrade to premium with time proration
    await ((MutationResolver)OpenIapClient.Instance).RequestPurchaseAsync(new RequestPurchaseProps
    {
        Type = ProductQueryType.Subs,
        RequestSubscription = new RequestSubscriptionPropsByPlatforms
        {
            Google = new RequestSubscriptionAndroidProps
            {
                Skus = new[] { "premium_monthly" },
                PurchaseToken = currentSub.PurchaseToken,
                SubscriptionProductReplacementParams = new SubscriptionProductReplacementParamsAndroid
                {
                    OldProductId = currentSub.ProductId,
                    ReplacementMode = SubscriptionReplacementModeAndroid.WithTimeProration,
                },
            },
        },
    });

    Console.WriteLine("Upgrade initiated");
}

Kotlin (KMP) example

// Android upgrade with proration
import io.github.hyochan.kmpiap.kmpIapInstance
import io.github.hyochan.kmpiap.requestPurchase
import io.github.hyochan.kmpiap.openiap.*

// Get current subscription
val purchases = kmpIapInstance.getAvailablePurchases()
val currentSub = purchases.find { it.productId == "basic_monthly" }

currentSub?.let { sub ->
    // Upgrade to premium with time proration
    kmpIapInstance.requestPurchase {
        type = ProductType.Subs
        google {
            skus = listOf("premium_monthly")
            purchaseToken = sub.purchaseToken
            subscriptionProductReplacementParams =
                SubscriptionProductReplacementParamsAndroid(
                    oldProductId = sub.productId,
                    replacementMode = SubscriptionReplacementModeAndroid.WithTimeProration
                )
        }
    }

    println("✅ Upgrade initiated")
}

GDScript example

# Android upgrade with proration

# Get current subscription
var purchases = await iap.get_available_purchases()
var current_sub = null
for p in purchases:
    if p.product_id == "basic_monthly":
        current_sub = p
        break

if current_sub:
    # Upgrade to premium with time proration
    var props = RequestPurchaseProps.new()
    props.request_subscription = RequestSubscriptionPropsByPlatforms.new()
    props.request_subscription.google = RequestSubscriptionAndroidProps.new()
    props.request_subscription.google.skus = ["premium_monthly"]
    props.request_subscription.google.purchase_token = current_sub.purchase_token
    var replacement = SubscriptionProductReplacementParamsAndroid.new()
    replacement.old_product_id = current_sub.product_id
    replacement.replacement_mode = SubscriptionReplacementModeAndroid.WITH_TIME_PRORATION
    props.request_subscription.google.subscription_product_replacement_params = replacement
    props.type = ProductQueryType.SUBS

    await iap.request_purchase(props)

    print("Upgrade initiated")

Downgrade Behavior (Deferred to Next Billing)#

When a user downgrades to a lower-tier subscription on Android (e.g., premium → basic):

Use DEFERRED replacement mode (Legacy API: 6, 8.1.0+ API: 5)
No immediate charge to the user
User keeps premium access until current period ends
Basic subscription starts at next billing date

The DEFERRED mode ensures users retain their premium features until the end of their paid period.

⚠️ Important: DEFERRED Mode Behavior

When using DEFERRED replacement mode, the purchase callback completes successfully with an empty purchase list. This is expected behavior, not an error:

The subscription change request succeeds immediately (status: OK)
But onPurchaseUpdated receives an empty/null purchases list
The actual subscription change won't take effect until the next renewal period
Your app should treat this as a successful operation, not an error

Why this happens: Since the subscription change is deferred to the future, Google Play Billing doesn't create a new purchase transaction immediately. The change will be reflected when the subscription renews.

📝 Code Example: Downgrading Subscription

Kotlin example

// Android downgrade with deferred replacement
import io.github.hyochan.kmpiap.kmpIapInstance
import io.github.hyochan.kmpiap.requestPurchase

// Get current subscription
val purchases = kmpIapInstance.getAvailablePurchases()
val premiumPurchase = purchases.find { it.productId == "premium_monthly" }

premiumPurchase?.let { purchase ->
    // Downgrade - takes effect at next billing cycle
    kmpIapInstance.requestPurchase {
        type = ProductType.Subs
        google {
            skus = listOf("basic_monthly")
            purchaseToken = purchase.purchaseToken
            subscriptionProductReplacementParams =
                SubscriptionProductReplacementParamsAndroid(
                    oldProductId = purchase.productId,
                    replacementMode = SubscriptionReplacementModeAndroid.Deferred
                )
        }
    }

    println("✅ Downgrade scheduled for next billing cycle")
    // Track the scheduled change on your backend until it takes effect.
}

TypeScript example

// Android downgrade with deferred replacement
import { requestPurchase, getAvailablePurchases } from 'expo-iap';

// Get current subscription
const purchases = await getAvailablePurchases();
const premiumPurchase = purchases.find(p => p.productId === 'premium_monthly');

if (premiumPurchase) {
  // Downgrade - takes effect at next billing cycle
  await requestPurchase({
    request: {
      google: {
        skus: ['basic_monthly'],
        purchaseToken: premiumPurchase.purchaseToken,
        subscriptionProductReplacementParams: {
          oldProductId: premiumPurchase.productId,
          replacementMode: 'deferred',
        },
      },
    },
    type: 'subs',
  });

  console.log('✅ Downgrade scheduled for next billing cycle');
  // Track the scheduled change on your backend until it takes effect.
}

Dart example

dart

// Android downgrade with deferred replacement
import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

// Get current subscription
final purchases = await FlutterInappPurchase.instance.getAvailablePurchases();
final premiumPurchase = purchases.firstWhere((p) => p.productId == 'premium_monthly');

if (premiumPurchase != null) {
  // Downgrade - takes effect at next billing cycle
  await FlutterInappPurchase.instance.requestPurchase(
    RequestPurchaseProps.subs((
      apple: null,
      google: RequestSubscriptionAndroidProps(
          skus: ['basic_monthly'],
          purchaseToken: premiumPurchase.purchaseToken,
          subscriptionProductReplacementParams:
              SubscriptionProductReplacementParamsAndroid(
            oldProductId: premiumPurchase.productId,
            replacementMode: SubscriptionReplacementModeAndroid.Deferred,
          ),
      ),
    )),
  );

  print('✅ Downgrade scheduled for next billing cycle');
  // Track the scheduled change on your backend until it takes effect.
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;
using System.Linq;

// Android downgrade with deferred replacement

// Get current subscription
var purchases = await ((QueryResolver)OpenIapClient.Instance).GetAvailablePurchasesAsync();
var premiumPurchase = purchases
    .OfType<PurchaseCommon>()
    .FirstOrDefault(purchase => purchase.ProductId == "premium_monthly");

if (premiumPurchase is not null)
{
    // Downgrade - takes effect at next billing cycle
    await ((MutationResolver)OpenIapClient.Instance).RequestPurchaseAsync(new RequestPurchaseProps
    {
        Type = ProductQueryType.Subs,
        RequestSubscription = new RequestSubscriptionPropsByPlatforms
        {
            Google = new RequestSubscriptionAndroidProps
            {
                Skus = new[] { "basic_monthly" },
                PurchaseToken = premiumPurchase.PurchaseToken,
                SubscriptionProductReplacementParams = new SubscriptionProductReplacementParamsAndroid
                {
                    OldProductId = premiumPurchase.ProductId,
                    ReplacementMode = SubscriptionReplacementModeAndroid.Deferred,
                },
            },
        },
    });

    Console.WriteLine("Downgrade scheduled for next billing cycle");
    // Track the scheduled change on your backend until it takes effect.
}

Kotlin (KMP) example

// Android downgrade with deferred replacement
import io.github.hyochan.kmpiap.kmpIapInstance
import io.github.hyochan.kmpiap.requestPurchase
import io.github.hyochan.kmpiap.openiap.*

// Get current subscription
val purchases = kmpIapInstance.getAvailablePurchases()
val premiumPurchase = purchases.find { it.productId == "premium_monthly" }

premiumPurchase?.let { purchase ->
    // Downgrade - takes effect at next billing cycle
    kmpIapInstance.requestPurchase {
        type = ProductType.Subs
        google {
            skus = listOf("basic_monthly")
            purchaseToken = purchase.purchaseToken
            subscriptionProductReplacementParams =
                SubscriptionProductReplacementParamsAndroid(
                    oldProductId = purchase.productId,
                    replacementMode = SubscriptionReplacementModeAndroid.Deferred
                )
        }
    }

    println("✅ Downgrade scheduled for next billing cycle")
    // Track the scheduled change on your backend until it takes effect.
}

GDScript example

# Android downgrade with deferred replacement

# Get current subscription
var purchases = await iap.get_available_purchases()
var premium_purchase = null
for p in purchases:
    if p.product_id == "premium_monthly":
        premium_purchase = p
        break

if premium_purchase:
    # Downgrade - takes effect at next billing cycle
    var props = RequestPurchaseProps.new()
    props.request_subscription = RequestSubscriptionPropsByPlatforms.new()
    props.request_subscription.google = RequestSubscriptionAndroidProps.new()
    props.request_subscription.google.skus = ["basic_monthly"]
    props.request_subscription.google.purchase_token = premium_purchase.purchase_token
    var replacement = SubscriptionProductReplacementParamsAndroid.new()
    replacement.old_product_id = premium_purchase.product_id
    replacement.replacement_mode = SubscriptionReplacementModeAndroid.DEFERRED
    props.request_subscription.google.subscription_product_replacement_params = replacement
    props.type = ProductQueryType.SUBS

    await iap.request_purchase(props)

    print("Downgrade scheduled for next billing cycle")
    # Track the scheduled change on your backend until it takes effect.

📝 Code Example: Using subscriptionProductReplacementParams (8.1.0+)

For more granular control, use the new per-product replacement params API:

Kotlin example

// Android subscription replacement with 8.1.0+ API
import dev.hyo.openiap.*
import dev.hyo.openiap.store.OpenIapStore

// Get current subscription
val iapStore = OpenIapStore(context)
val purchases = iapStore.getAvailablePurchases(null)
val currentSub = purchases.find { it.productId == "premium_monthly" }

currentSub?.let { sub ->
    // Upgrade using the new per-product replacement params
    iapStore.requestPurchase(
        RequestPurchaseProps(
            type = ProductQueryType.Subs,
            request = RequestPurchaseProps.Request.Subscription(
                RequestSubscriptionPropsByPlatforms(
                    google = RequestSubscriptionAndroidProps(
                        skus = listOf("premium_yearly"),
                        subscriptionProductReplacementParams = SubscriptionProductReplacementParamsAndroid(
                            oldProductId = sub.productId,
                            replacementMode = SubscriptionReplacementModeAndroid.WithTimeProration
                            // or SubscriptionReplacementModeAndroid.KeepExisting (8.1.0+ only)
                        )
                    )
                )
            )
        )
    )

    println("✅ Upgrade initiated with per-product replacement")
}

TypeScript example

// Android subscription replacement with 8.1.0+ API
import { requestPurchase, getAvailablePurchases } from 'expo-iap';

// Get current subscription
const purchases = await getAvailablePurchases();
const currentSub = purchases.find(p => p.productId === 'premium_monthly');

if (currentSub) {
  // Upgrade using the new per-product replacement params
  await requestPurchase({
    request: {
      google: {
        skus: ['premium_yearly'],
        subscriptionProductReplacementParams: {
          oldProductId: currentSub.productId,
          replacementMode: 'with-time-proration',
        },
      },
    },
    type: 'subs',
  });

  console.log('✅ Upgrade initiated with per-product replacement');
}

Dart example

dart

// Android subscription replacement with 8.1.0+ API
import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

// Get current subscription
final purchases = await FlutterInappPurchase.instance.getAvailablePurchases();
final currentSub = purchases.firstWhere((p) => p.productId == 'premium_monthly');

if (currentSub != null) {
  // Upgrade using the new per-product replacement params
  await FlutterInappPurchase.instance.requestPurchase(
    RequestPurchaseProps.subs((
      apple: null,
      google: RequestSubscriptionAndroidProps(
          skus: ['premium_yearly'],
          subscriptionProductReplacementParams: SubscriptionProductReplacementParamsAndroid(
            oldProductId: currentSub.productId,
            replacementMode: SubscriptionReplacementModeAndroid.WithTimeProration,
          ),
      ),
    )),
  );

  print('✅ Upgrade initiated with per-product replacement');
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;
using System.Linq;

// Android subscription replacement with 8.1.0+ API

// Get current subscription
var purchases = await ((QueryResolver)OpenIapClient.Instance).GetAvailablePurchasesAsync();
var currentSub = purchases
    .OfType<PurchaseCommon>()
    .FirstOrDefault(purchase => purchase.ProductId == "premium_monthly");

if (currentSub is not null)
{
    // Upgrade using the new per-product replacement params
    await ((MutationResolver)OpenIapClient.Instance).RequestPurchaseAsync(new RequestPurchaseProps
    {
        Type = ProductQueryType.Subs,
        RequestSubscription = new RequestSubscriptionPropsByPlatforms
        {
            Google = new RequestSubscriptionAndroidProps
            {
                Skus = new[] { "premium_yearly" },
                SubscriptionProductReplacementParams =
                    new SubscriptionProductReplacementParamsAndroid
                    {
                        OldProductId = currentSub.ProductId,
                        ReplacementMode = SubscriptionReplacementModeAndroid.WithTimeProration,
                        // or SubscriptionReplacementModeAndroid.KeepExisting (8.1.0+ only)
                    },
            },
        },
    });

    Console.WriteLine("Upgrade initiated with per-product replacement");
}

Kotlin (KMP) example

// Android subscription replacement with 8.1.0+ API
import io.github.hyochan.kmpiap.KmpIAP
import io.github.hyochan.kmpiap.openiap.*

// Get current subscription
val purchases = kmpIAP.getAvailablePurchases()
val currentSub = purchases.find { it.productId == "premium_monthly" }

currentSub?.let { sub ->
    // Upgrade using the new per-product replacement params
    kmpIAP.requestPurchase(
        RequestPurchaseProps(
            type = ProductQueryType.Subs,
            request = RequestPurchaseProps.Request.Subscription(
                RequestSubscriptionPropsByPlatforms(
                    google = RequestSubscriptionAndroidProps(
                        skus = listOf("premium_yearly"),
                        subscriptionProductReplacementParams = SubscriptionProductReplacementParamsAndroid(
                            oldProductId = sub.productId,
                            replacementMode = SubscriptionReplacementModeAndroid.WithTimeProration
                            // or SubscriptionReplacementModeAndroid.KeepExisting (8.1.0+ only)
                        )
                    )
                )
            )
        )
    )

    println("✅ Upgrade initiated with per-product replacement")
}

GDScript example

# Android subscription replacement with 8.1.0+ API

# Get current subscription
var purchases = await iap.get_available_purchases()
var current_sub = null
for p in purchases:
    if p.product_id == "premium_monthly":
        current_sub = p
        break

if current_sub:
    # Upgrade using the new per-product replacement params
    var props = RequestPurchaseProps.new()
    props.request_subscription = RequestSubscriptionPropsByPlatforms.new()
    props.request_subscription.google = RequestSubscriptionAndroidProps.new()
    props.request_subscription.google.skus = ["premium_yearly"]
    props.request_subscription.google.subscription_product_replacement_params = SubscriptionProductReplacementParamsAndroid.new()
    props.request_subscription.google.subscription_product_replacement_params.old_product_id = current_sub.product_id
    props.request_subscription.google.subscription_product_replacement_params.replacement_mode = SubscriptionReplacementModeAndroid.WITH_TIME_PRORATION
    # or SubscriptionReplacementModeAndroid.KEEP_EXISTING (8.1.0+ only)
    props.type = ProductQueryType.SUBS

    await iap.request_purchase(props)

    print("Upgrade initiated with per-product replacement")

Tracking Subscription Changes#

On Android, detecting subscription changes is more straightforward since the Play Billing API immediately reflects the current active subscription.

Checking for pending changes

📝 Code Example: Checking Active Subscription

Kotlin example

// Android - check if subscription will change
import io.github.hyochan.kmpiap.kmpIapInstance

val purchases = kmpIapInstance.getAvailablePurchases()

for (purchase in purchases) {
    // On Android, the current purchase reflects the active subscription
    println("Active subscription: ${purchase.productId}")

    // If using DEFERRED mode, the change is scheduled but not yet reflected
    // You'll need to track this in your backend or check purchase history
}

TypeScript example

// Android - check if subscription will change
import { getAvailablePurchases } from 'expo-iap';

const purchases = await getAvailablePurchases();

for (const purchase of purchases) {
  // On Android, the current purchase reflects the active subscription
  console.log('Active subscription:', purchase.productId);

  // If using DEFERRED mode, the change is scheduled but not yet reflected
  // You'll need to track this in your backend or check purchase history
}

Dart example

dart

// Android - check if subscription will change
import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

final purchases = await FlutterInappPurchase.instance.getAvailablePurchases();

for (final purchase in purchases) {
  // On Android, the current purchase reflects the active subscription
  print('Active subscription: ${purchase.productId}');

  // If using DEFERRED mode, the change is scheduled but not yet reflected
  // You'll need to track this in your backend or check purchase history
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;
using System.Linq;

// Android - check if subscription will change

var purchases = await ((QueryResolver)OpenIapClient.Instance).GetAvailablePurchasesAsync();

foreach (var purchase in purchases.OfType<PurchaseCommon>())
{
    // On Android, the current purchase reflects the active subscription
    Console.WriteLine(quot;Active subscription: {purchase.ProductId}");

    // If using DEFERRED mode, the change is scheduled but not yet reflected
    // You'll need to track this in your backend or check purchase history
}

Kotlin (KMP) example

// Android - check if subscription will change
import io.github.hyochan.kmpiap.kmpIapInstance

val purchases = kmpIapInstance.getAvailablePurchases()

for (purchase in purchases) {
    // On Android, the current purchase reflects the active subscription
    println("Active subscription: ${purchase.productId}")

    // If using DEFERRED mode, the change is scheduled but not yet reflected
    // You'll need to track this in your backend or check purchase history
}

GDScript example

# Android - check if subscription will change
var purchases = await iap.get_available_purchases()

for purchase in purchases:
    # On Android, the current purchase reflects the active subscription
    print("Active subscription: %s" % purchase.product_id)

    # If using DEFERRED mode, the change is scheduled but not yet reflected
    # You'll need to track this in your backend or check purchase history

⚠️ Android: Track deferred changes in your backend

Best Practices#

Specify replacement mode when needed: Pass subscriptionProductReplacementParams.replacementMode when you want to override the default configured in Google Play Console
Use WITH_TIME_PRORATION for upgrades to give users credit for unused time
Use DEFERRED for downgrades to let users keep premium features until period ends
Handle DEFERRED mode correctly: When using DEFERRED, expect an empty purchase list - this is success, not an error
Track pending changes in your backend since Android doesn't expose deferred changes in the API
Implement RTDN webhooks to receive real-time updates about subscription changes

Here's a complete example showing how to handle subscription changes with backend tracking:

📝 Complete Example: Subscription Change Handler

Kotlin example

// Complete native Android example: Subscription change
import dev.hyo.openiap.*
import dev.hyo.openiap.store.OpenIapStore

suspend fun changeSubscription(
    newSku: String,
    isUpgrade: Boolean
) {
    // Get current subscription
    val iapStore = OpenIapStore(context)
    val purchases = iapStore.getAvailablePurchases(null)
    val currentSub = purchases.find { it.productId.contains("subscription") }

    if (currentSub == null) {
        println("No active subscription found")
        return
    }

    // Choose appropriate replacement mode
    val replacementMode = if (isUpgrade)
        SubscriptionReplacementModeAndroid.WithTimeProration
    else
        SubscriptionReplacementModeAndroid.Deferred

    try {
        iapStore.requestPurchase(RequestPurchaseProps(
            request = RequestPurchaseProps.Request.Subscription(
                RequestSubscriptionPropsByPlatforms(
                    google = RequestSubscriptionAndroidProps(
                        skus = listOf(newSku),
                        purchaseToken = currentSub.purchaseToken,
                        subscriptionProductReplacementParams =
                            SubscriptionProductReplacementParamsAndroid(
                                oldProductId = currentSub.productId,
                                replacementMode = replacementMode
                            )
                    )
                )
            ),
            type = ProductQueryType.Subs
        ))

        // If DEFERRED, store pending change in your backend
        if (!isUpgrade) {
            sendPendingChangeToBackend(
                userId = "user123",
                currentSku = currentSub.productId,
                newSku = newSku
            )
        }
    } catch (e: Exception) {
        println("Subscription change failed: ${e.message}")
    }
}

TypeScript example

// Complete Android example: Subscription change
import { requestPurchase, getAvailablePurchases } from 'expo-iap';

async function changeSubscription(
  newSku: string,
  isUpgrade: boolean
) {
  // Get current subscription
  const purchases = await getAvailablePurchases();
  const currentSub = purchases.find(p => p.productId.includes('subscription'));

  if (!currentSub) {
    console.error('No active subscription found');
    return;
  }

  // Choose appropriate replacement mode
  const replacementMode = isUpgrade
    ? 'with-time-proration'
    : 'deferred';

  try {
    await requestPurchase({
      request: {
        google: {
          skus: [newSku],
          purchaseToken: currentSub.purchaseToken,
          subscriptionProductReplacementParams: {
            oldProductId: currentSub.productId,
            replacementMode,
          },
        },
      },
      type: 'subs',
    });

    // If DEFERRED, store pending change in your backend
    if (!isUpgrade) {
      await fetch('/api/subscriptions/pending-change', {
        method: 'POST',
        body: JSON.stringify({
          userId: 'user123',
          currentSku: currentSub.productId,
          newSku,
        }),
      });
    }
  } catch (error) {
    console.error('Subscription change failed:', error);
  }
}

Dart example

dart

// Complete Android example: Subscription change
import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';
import 'package:http/http.dart' as http;
import 'dart:convert';

Future<void> changeSubscription(
  String newSku,
  bool isUpgrade,
) async {
  // Get current subscription
  final purchases = await FlutterInappPurchase.instance.getAvailablePurchases();
  Purchase? currentSub;
  for (final purchase in purchases) {
    if (purchase.productId.contains('subscription')) {
      currentSub = purchase;
      break;
    }
  }

  if (currentSub == null) {
    print('No active subscription found');
    return;
  }

  // Choose appropriate replacement mode
  final replacementMode = isUpgrade
      ? SubscriptionReplacementModeAndroid.WithTimeProration
      : SubscriptionReplacementModeAndroid.Deferred;

  try {
    await FlutterInappPurchase.instance.requestPurchase(
      RequestPurchaseProps.subs((
        apple: null,
        google: RequestSubscriptionAndroidProps(
            skus: [newSku],
            purchaseToken: currentSub.purchaseToken,
            subscriptionProductReplacementParams:
                SubscriptionProductReplacementParamsAndroid(
              oldProductId: currentSub.productId,
              replacementMode: replacementMode,
            ),
        ),
      )),
    );

    // If DEFERRED, store pending change in your backend
    if (!isUpgrade) {
      await http.post(
        Uri.parse('/api/subscriptions/pending-change'),
        body: jsonEncode({
          'userId': 'user123',
          'currentSku': currentSub.productId,
          'newSku': newSku,
        }),
      );
    }
  } catch (e) {
    print('Subscription change failed: $e');
  }
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;
using System.Linq;

// Complete Android example: Subscription change.
async Task ChangeSubscriptionAsync(string newSku, bool isUpgrade)
{
    // Get current subscription
    var purchases = await ((QueryResolver)OpenIapClient.Instance).GetAvailablePurchasesAsync();
    var currentSub = purchases
        .OfType<PurchaseCommon>()
        .FirstOrDefault(purchase =>
            purchase.ProductId.Contains("subscription", StringComparison.OrdinalIgnoreCase));

    if (currentSub is null)
    {
        Console.WriteLine("No active subscription found");
        return;
    }

    // Choose appropriate replacement mode
    var replacementMode = isUpgrade
        ? SubscriptionReplacementModeAndroid.WithTimeProration
        : SubscriptionReplacementModeAndroid.Deferred;

    try
    {
        await ((MutationResolver)OpenIapClient.Instance).RequestPurchaseAsync(new RequestPurchaseProps
        {
            Type = ProductQueryType.Subs,
            RequestSubscription = new RequestSubscriptionPropsByPlatforms
            {
                Google = new RequestSubscriptionAndroidProps
                {
                    Skus = new[] { newSku },
                    PurchaseToken = currentSub.PurchaseToken,
                    SubscriptionProductReplacementParams = new SubscriptionProductReplacementParamsAndroid
                    {
                        OldProductId = currentSub.ProductId,
                        ReplacementMode = replacementMode,
                    },
                },
            },
        });

        // If DEFERRED, store pending change in your backend.
        if (!isUpgrade)
        {
            await SendPendingChangeToBackendAsync(
                userId: "user123",
                currentSku: currentSub.ProductId,
                newSku: newSku);
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(quot;Subscription change failed: {ex.Message}");
    }
}

Kotlin (KMP) example

// Complete Android example: Subscription change
import io.github.hyochan.kmpiap.kmpIapInstance
import io.github.hyochan.kmpiap.PurchaseException
import io.github.hyochan.kmpiap.openiap.*

suspend fun changeSubscription(
    newSku: String,
    isUpgrade: Boolean
) {
    // Get current subscription
    val purchases = kmpIapInstance.getAvailablePurchases()
    val currentSub = purchases.find { it.productId.contains("subscription") }

    if (currentSub == null) {
        println("No active subscription found")
        return
    }

    // Choose appropriate replacement mode
    val replacementMode = if (isUpgrade)
        SubscriptionReplacementModeAndroid.WithTimeProration
    else
        SubscriptionReplacementModeAndroid.Deferred

    try {
        kmpIapInstance.requestPurchase {
            type = ProductType.Subs
            google {
                skus = listOf(newSku)
                purchaseToken = currentSub.purchaseToken
                subscriptionProductReplacementParams =
                    SubscriptionProductReplacementParamsAndroid(
                        oldProductId = currentSub.productId,
                        replacementMode = replacementMode
                    )
            }
        }

        // If DEFERRED, store pending change in your backend
        if (!isUpgrade) {
            sendPendingChangeToBackend(
                userId = "user123",
                currentSku = currentSub.productId,
                newSku = newSku
            )
        }
    } catch (e: PurchaseException) {
        println("Subscription change failed: ${e.message}")
    }
}

GDScript example

# Complete Android example: Subscription change
func change_subscription(new_sku: String, is_upgrade: bool) -> void:
    # Get current subscription
    var purchases = await iap.get_available_purchases()
    var current_sub = null
    for p in purchases:
        if "subscription" in p.product_id:
            current_sub = p
            break

    if not current_sub:
        print("No active subscription found")
        return

    # Choose appropriate replacement mode.
    var replacement_mode = (
        SubscriptionReplacementModeAndroid.WITH_TIME_PRORATION
        if is_upgrade
        else SubscriptionReplacementModeAndroid.DEFERRED
    )

    var props = RequestPurchaseProps.new()
    props.request_subscription = RequestSubscriptionPropsByPlatforms.new()
    props.request_subscription.google = RequestSubscriptionAndroidProps.new()
    props.request_subscription.google.skus = [new_sku]
    props.request_subscription.google.purchase_token = current_sub.purchase_token
    var replacement = SubscriptionProductReplacementParamsAndroid.new()
    replacement.old_product_id = current_sub.product_id
    replacement.replacement_mode = replacement_mode
    props.request_subscription.google.subscription_product_replacement_params = replacement
    props.type = ProductQueryType.SUBS

    await iap.request_purchase(props)

    # If DEFERRED, store pending change in your backend
    if not is_upgrade:
        var http_request = HTTPRequest.new()
        add_child(http_request)
        http_request.request(
            "/api/subscriptions/pending-change",
            ["Content-Type: application/json"],
            HTTPClient.METHOD_POST,
            JSON.stringify({
                "userId": "user123",
                "currentSku": current_sub.product_id,
                "newSku": new_sku
            })
        )

Official References#

Google Play Billing: Upgrade or downgrade a subscription
Replacement modes, proration, and base-plan switching
Google Play Billing: Replace a subscription
Official documentation on subscription replacement modes and proration
Real-time Developer Notifications (RTDN)
Set up webhooks to receive subscription change events
Subscription lifecycle
Understanding how subscriptions work on Google Play