Use this page with AI

Copy this into your coding assistant and add your request.

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

Events

Complete listener reference for OpenIAP. Every event listener is listed below with a one-line description and a link to its full signature. The IAP library uses an event-driven architecture to handle purchase flows asynchronously — set up listeners before initiating any purchase to properly handle the results.

Event System Overview#

The IAP library uses an event-driven architecture to handle purchase flows asynchronously. You must set up event listeners before initiating any purchase to properly handle the results.

Event Types

swift

enum IapEvent {
    case purchaseUpdated
    case purchaseError
    case subscriptionBillingIssue
    case promotedProductIOS
}

Kotlin example

enum class IapEvent {
    PurchaseUpdated,
    PurchaseError,
    SubscriptionBillingIssue,
    UserChoiceBillingAndroid,
    DeveloperProvidedBillingAndroid // 8.3.0+
}

TypeScript example

enum IapEvent {
  PurchaseUpdated = 'purchaseUpdated',
  PurchaseError = 'purchaseError',
  SubscriptionBillingIssue = 'subscriptionBillingIssue',
  PromotedProductIOS = 'promotedProductIOS',
  UserChoiceBillingAndroid = 'userChoiceBillingAndroid',
  DeveloperProvidedBillingAndroid = 'developerProvidedBillingAndroid', // 8.3.0+
}

Dart example

dart

enum IapEvent {
  purchaseUpdated,
  purchaseError,
  subscriptionBillingIssue,
  promotedProductIOS,
  userChoiceBillingAndroid,
  developerProvidedBillingAndroid, // 8.3.0+
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

public enum IapEvent
{
    PurchaseUpdated,
    PurchaseError,
    SubscriptionBillingIssue,
    UserChoiceBillingAndroid,
    DeveloperProvidedBillingAndroid // 8.3.0+
}

Kotlin (KMP) example

enum class IapEvent {
    PurchaseUpdated,
    PurchaseError,
    SubscriptionBillingIssue,
    UserChoiceBillingAndroid,
    DeveloperProvidedBillingAndroid // 8.3.0+
}

GDScript example

enum IapEvent {
    PURCHASE_UPDATED = 0,
    PURCHASE_ERROR = 1,
    SUBSCRIPTION_BILLING_ISSUE = 2,
    PROMOTED_PRODUCT_IOS = 3,
    USER_CHOICE_BILLING_ANDROID = 4,
    DEVELOPER_PROVIDED_BILLING_ANDROID = 5, # 8.3.0+
}

Listeners#

Listener	Description
`purchaseUpdatedListener`	Fires when a purchase is successful or a pending purchase is completed.
`purchaseErrorListener`	Fires when a purchase fails or is cancelled by the user.
`subscriptionBillingIssueListener`	Fires when a subscription enters a billing issue state (iOS/iPadOS/Mac Catalyst 16.4+, visionOS 1.0+, or Play Billing 8.1+; not emitted on Horizon).

iOS Listeners#

Listener	Description
`promotedProductListenerIOS`	Fires when a user clicks on a promoted in-app purchase in the App Store.

Android Listeners#

Listener	Description
`userChoiceBillingListenerAndroid`	Fires when a user selects alternative billing in the User Choice Billing dialog.
`developerProvidedBillingListenerAndroid`	Fires when a user selects developer-provided billing in the External Payments flow (8.3.0+) or Google-rendered Billing Choice flow (9.1.0+).

Event Listener Management

Listener Lifecycle

Register listeners before initiating purchases
Keep listeners active throughout purchase flow
Remove listeners when no longer needed (cleanup)

Each listener returns a Subscription object with a remove() method for cleanup.

Event Manager Pattern

Consider implementing a centralized event manager that:

Initializes all IAP event listeners
Routes events to appropriate handlers
Integrates with analytics and logging
Manages listener lifecycle
Provides cleanup methods

Best Practices

Always set up listeners before making purchases - Events may be lost if listeners aren't registered
Handle all error cases - Provide appropriate user feedback for each error type
Clean up listeners - Remove listeners when components unmount to prevent memory leaks
Process purchases idempotently - Same purchase may be delivered multiple times
Validate receipts server-side - Never trust client-side validation alone
Finish/acknowledge purchases promptly - Unfinished transactions may cause issues
Log events for debugging - Track purchase flow for troubleshooting