Use this page with AI

Copy this into your coding assistant and add your request.

Read https://openiap.dev/docs/events/subscription-billing-issue-listener 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]

See an example request →

subscriptionBillingIssueListener

Fired when a subscription enters a state that needs user attention because of a payment problem — card declined, expired payment method, billing retry, or grace period. Unifies StoreKit 2 Message.billingIssue (iOS/iPadOS/Mac Catalyst 16.4+ and visionOS 1.0+) and Play Billing Purchase.isSuspended (Play Billing Library 8.1+) under a single cross-platform stream. Silent no-op on platforms that cannot emit (tvOS, watchOS, macOS, Meta Horizon, Amazon Appstore).

Listener Setup#

swift

// iOS/iPadOS/Mac Catalyst 16.4+; visionOS 1.0+
func subscriptionBillingIssueListener(
    _ listener: @escaping @Sendable (Purchase) -> Void
) -> Subscription

Kotlin example

kt

// Callback approach (Play Billing 8.1+)
fun addSubscriptionBillingIssueListener(
    listener: OpenIapSubscriptionBillingIssueListener
)

TypeScript example

ts

subscriptionBillingIssueListener(
  listener: (purchase: Purchase) => void
): Subscription

Dart example

dart

Stream<Purchase> get subscriptionBillingIssueListener;

C# (MAUI) example

cs

using OpenIap;
using OpenIap.Maui;

// Apple 16.4+ (visionOS 1.0+) / Play Billing 8.1+.
IDisposable subscription = OpenIapClient.Instance.SubscriptionBillingIssue.Subscribe(purchase =>
{
    Console.WriteLine("Subscription billing issue received");
});

Kotlin (KMP) example

kt

// Flow approach
val subscriptionBillingIssueListener: Flow<Purchase>

GDScript example

gd

signal subscription_billing_issue(purchase: Purchase)

The emitted Purchase is a regular subscription payload — use productId, purchaseToken, and platform fields to prompt the user to update payment. Play deduplicates by purchaseToken per session; iOS fires per Message delivery.

On Apple platforms, StoreKit's system billing message is still presented through Message.display(in:). This listener is an additional notification for your app; it does not replace or suppress the default StoreKit UI.

Example#

swift

import OpenIap

// iOS/iPadOS/Mac Catalyst 16.4+; visionOS 1.0+
let subscription = OpenIapModule.shared.subscriptionBillingIssueListener { purchase in
    print("Billing issue on \(purchase.productId)")
    Task { await showBillingIssueBanner(purchase) }
}

// Cleanup when the view disappears
OpenIapModule.shared.removeListener(subscription)

Kotlin example

kt

import dev.hyo.openiap.listener.OpenIapSubscriptionBillingIssueListener
import dev.hyo.openiap.store.OpenIapStore

val openIapStore = OpenIapStore(context)

// Play Billing Library 8.1+
val listener = OpenIapSubscriptionBillingIssueListener { purchase ->
    println("Billing issue on ${purchase.productId}")
    showBillingIssueBanner(purchase)
}
openIapStore.addSubscriptionBillingIssueListener(listener)

// Cleanup when the view disappears
openIapStore.removeSubscriptionBillingIssueListener(listener)

TypeScript example

ts

// expo-iap
import { subscriptionBillingIssueListener } from 'expo-iap';
// Same API in react-native-iap:
// import { subscriptionBillingIssueListener } from 'react-native-iap';

const subscription = subscriptionBillingIssueListener((purchase) => {
  console.log('Billing issue on', purchase.productId);
  // Surface a "Update payment method" prompt and link the user to
  // the platform's subscription management UI.
  showBillingIssueBanner(purchase);
});

// Cleanup when the screen unmounts
subscription.remove();

// --- Or via the useIAP() hook (also exported from react-native-iap) ---
import { useIAP } from 'expo-iap';

function BillingIssueGate() {
  useIAP({
    onSubscriptionBillingIssue: (purchase) => {
      showBillingIssueBanner(purchase);
    },
  });
  return null;
}

Dart example

dart

import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

final subscription = FlutterInappPurchase.instance
  .subscriptionBillingIssueListener.listen((purchase) {
    debugPrint('Billing issue on ${purchase.productId}');
    showBillingIssueBanner(purchase);
  });

// Cleanup when the widget disposes
subscription.cancel();

C# (MAUI) example

cs

using OpenIap;
using OpenIap.Maui;

// Apple 16.4+ (visionOS 1.0+) / Play Billing Library 8.1+
var subscription = OpenIapClient.Instance.SubscriptionBillingIssue.Subscribe(purchase =>
{
    if (purchase is PurchaseCommon purchaseInfo)
    {
        Console.WriteLine(quot;Billing issue on {purchaseInfo.ProductId}");
    }

    ShowBillingIssueBanner(purchase);
});

// Cleanup when the view disappears.
subscription.Dispose();

Kotlin (KMP) example

kt

import io.github.hyochan.kmpiap.KmpIAP

val kmpIAP = KmpIAP()

// Play Billing 8.1+ on Android; Apple 16.4+ (visionOS 1.0+)
lifecycleScope.launch {
    kmpIAP.subscriptionBillingIssueListener.collect { purchase ->
        println("Billing issue on ${purchase.productId}")
        showBillingIssueBanner(purchase)
    }
}

GDScript example

gd

iap.subscription_billing_issue.connect(_on_billing_issue)

func _on_billing_issue(purchase: Purchase):
    print("Billing issue on %s" % purchase.product_id)
    show_billing_issue_banner(purchase)

# Cleanup when leaving the scene
func _exit_tree():
    iap.subscription_billing_issue.disconnect(_on_billing_issue)

See Subscription Billing Issue feature guide for platform coverage, signal sources, and UX recommendations.