flutter_inapp_purchase

The plugin supports the following platforms:

• iOS: 11.0+ using StoreKit
• Android: API 21+ (Android 5.0) using Google Play Billing Library v5+
• macOS: 10.15+ using StoreKit (limited support)

Note: Windows, Linux, and Web are not supported.

This repository is archived and read-only. The project has moved to the OpenIAP monorepo.

• Source code: hyodotdev/openiap → libraries/flutter_inapp_purchase
• Monorepo: hyodotdev/openiap
• Documentation: openiap.dev/docs/setup/flutter
• Issues: hyodotdev/openiap/issues

Note: The pub.dev package name remains flutter_inapp_purchase and is still the correct way to install it via flutter pub add flutter_inapp_purchase.

The library uses union types for products. When you fetch products, the returned objects are platform-specific classes (ProductIOS or ProductAndroid). You must check the type of the product at runtime to access platform-specific properties.

Product Classes

iOS Products

• ProductIOS: Extends Product. Includes id, displayName, description, price, displayPrice, and type (ProductTypeIOS).
• ProductSubscriptionIOS: Extends ProductSubscription. Includes id, displayName, description, price, displayPrice, and subscription (SubscriptionInfoIOS).

Android Products

• ProductAndroid: Extends Product. Includes productId, productType, title, name, and description.
• ProductSubscriptionAndroid: Extends ProductSubscription. Includes productId, title, name, and description.

The FlutterInappPurchase class is a singleton used to manage in-app purchases on iOS and Android. It handles the connection to platform-specific billing services (App Store and Google Play), product queries, purchase flows, and transaction management.

Access the singleton via FlutterInappPurchase.instance.

final iap = FlutterInappPurchase.instance;

You can manage the FlutterInappPurchase instance in two ways depending on your state management needs:

1. Manual Instance (Recommended): Create a new instance for better control and testability.
2. Singleton: Use the built-in singleton for global state management across your application.

// Option 1: Create your own instance (recommended for most cases)
final iap = FlutterInappPurchase();

// Option 2: Use singleton for global state management
final iap = FlutterInappPurchase.instance;

When exposing In-App Purchase (IAP) APIs, always prefer the generated handler typedefs and helper classes found in lib/types.dart. These types are synchronized with the OpenIAP schema, ensuring that parameter and return shapes remain consistent across the codebase. Using these generated signatures automatically handles nullability, optional flags, and platform-specific fields without requiring manual boilerplate.

final queryHandlers = QueryHandlers(
  fetchProducts: ({required ProductRequest params}) async {
    return _platform.fetchProducts(params: params);
  },
);

final mutationHandlers = MutationHandlers(
  finishTransaction: ({
    required PurchaseInput purchase,
    bool? isConsumable,
  }) async {
    return _platform.finishTransaction(
      purchase: purchase,
      isConsumable: isConsumable,
    );
  },
);

Purchases may enter a PurchaseState.Pending state when using payment methods that require additional verification.

Best Practices:

• Implement proper handling for PurchaseState.Pending in your logic.
• Inform users that their purchase is being processed.
• Store pending purchases and check their status again later.

The flutter_inapp_purchase package conforms to the OpenIAP specification, which is an open, vendor-neutral interoperability standard for in-app purchases.

Instead of using framework-specific types or error models, OpenIAP provides a shared specification layer. This ensures that purchase behavior, error codes, and verification flows remain consistent across different platforms and frameworks. The specification is defined via a single GraphQL schema, which is then used to generate type-safe bindings for various platforms, including Dart (used by flutter_inapp_purchase).

The purchase process in flutter_inapp_purchase follows six distinct phases. Implementing these in order ensures a reliable user experience and prevents lost revenue from unfinalized transactions.

1. Connection Phase: Establish a connection to the app store.
2. Product Discovery Phase: Fetch available products (SKUs) from the store.
3. Purchase Initiation Phase: Trigger the platform's native purchase dialog.
4. Transaction Processing Phase: Listen to streams for successful purchases or errors.
5. Content Delivery Phase: Validate the purchase (ideally on a server) and grant the user their content.
6. Transaction Finalization Phase: Acknowledge or consume the transaction to tell the store the process is complete.

iOS

• Use onlyIncludeActiveItemsIOS: true to filter for active subscriptions only.
• Use onlyIncludeActiveItemsIOS: false to include the full purchase history.
• Use alsoPublishToEventListenerIOS to trigger the event stream for retrieved items.

Android

• Returns all verified purchases from Google Play.
• Includes purchase tokens for server-side verification.
• Does not have a separate API for purchase history; it returns verified purchases directly.

The plugin has updated how it handles transaction references to ensure consistency across stores:

• transactionId: This is the primary store reference. It maps to orderId on Android and the StoreKit transaction ID on iOS.
• Handling null transactionId: On Android, if Google Play omits an orderId (common for consumables), transactionId will be null.
• Canonical Receipt: For server-side validation, do not rely solely on transactionId. Instead, use the unified purchaseToken exposed on every purchase record. This maps to the Android purchase token or the iOS JWS.

The library uses event streams to communicate purchase results. You must listen to these streams to handle successful purchases and errors.

Important: Always cancel your StreamSubscription in the dispose() method of your widget to prevent memory leaks.

StreamSubscription? _purchaseUpdatedSubscription;
StreamSubscription? _purchaseErrorSubscription;

// In your initialization logic:
_purchaseUpdatedSubscription = iap.purchaseUpdatedListener.listen((purchase) {
  _handlePurchase(purchase);
});

_purchaseErrorSubscription = iap.purchaseErrorListener.listen((error) {
  _handleError(error);
});

@override
void dispose() {
  _purchaseUpdatedSubscription?.cancel();
  _purchaseErrorSubscription?.cancel();
  super.dispose();
}