flutter_orca #

Cross-platform in-app purchase plugin for Flutter. Supports Android, iOS, macOS, Web, Windows, and Linux by Maxint Inc.

Features #

• Unified API - one interface for all platforms, regardless of the underlying store
• Entitlement-based model - define products once on the Orca backend, map them to App Store, Google Play, Stripe, and GoCardless or Create from the Orca dashboard across all platforms
• Consumables, non-consumables, and subscriptions - full support for all product types
• Upgrade/downgrade (proration) - change subscriptions with prorated billing
• Real-time purchase events - listen to a stream of purchase successes, cancellations, and failures
• Active entitlement tracking - query the user's current subscriptions and owned products

Platform Support #

Installation #

Run following in your terminal to add the package to your Flutter project:

$ flutter pub add orca

Setup #

Follow our docs to setup your Orca account and configure your products and entitlements: https://orca.maxint.com/docs/

Usage #

Initialize #

Create a Orca instance with your Orca API key and environment:

import 'package:orca/orca.dart';

final orca = Orca(
  publicKey: 'YOUR_ORCA_PUBLIC_KEY',
  environment: OrcaEnvironment.sandbox, // or .production
);

// Identify the customer (required before making purchases)
await orca.identify('user@example.com');

List available entitlements #

Fetch all products/entitlements configured in your Orca dashboard:

final entitlements = await orca.listEntitlements();

for (final entitlement in entitlements) {
  print('${entitlement.name} - ${entitlement.entitlementType.name}');
}

Each OrcaEntitlement contains store-specific product references (.products.playStore, .products.appStore, .products.stripe, .products.gocardless).

Query store products #

Get normalized product details (price, currency, recurrence) for a specific external store:

// On web/desktop, specify the store:
final products = await orca.queryProducts(ExternalStore.stripe);

// On mobile/macOS, the externalStore is ignored (IAP is used):
final iapProducts = await orca.queryProducts(ExternalStore.stripe);

for (final product in products) {
  print('${product.name}: ${product.formattedPrice}');
}

Make a purchase #

await orca.purchase(
  entitlement,
  externalStore: ExternalStore.stripe,    // stripe or gocardless for web/desktop
  redirectUrl: 'https://yourapp.com/success',
  failureRedirectUrl: 'https://yourapp.com/failure',
);

On mobile/macOS, the externalStore parameter is ignored - the native IAP flow is used automatically.

Upgrade / downgrade a subscription #

PlayStore and App Store support this automatically. But for Stripe/GoCardless, we need the hierarchy of products to be defined in the Orca dashboard. So make sure to create Offerings in the Orca dashboard for the entitlements you want to allow upgrades/downgrades for.

Otherwise, it needs to be done manually like below. Pass the current product and proration mode when changing subscriptions:

await orca.purchase(
  newEntitlement,
  externalStore: ExternalStore.stripe,
  redirectUrl: 'https://yourapp.com/success',
  failureRedirectUrl: 'https://yourapp.com/failure',
  proratedProduct: currentEntitlement.products.stripe,
  prorationMode: ProrationMode.upgrade,   // or ProrationMode.downgrade
);

Listen to purchase events #

orca.purchaseEvents.listen((event) {
  switch (event.event) {
    case PurchaseEventType.success:
      print('Purchase completed!');
    case PurchaseEventType.canceled:
      print('User cancelled the purchase.');
    case PurchaseEventType.failed:
      print('Receipt verification failed.');
    case PurchaseEventType.error:
      print('An error occurred during purchase.');
  }
});

Get active entitlements #

Check what the user currently owns:

final activeEntitlements = await orca.getActiveEntitlements();

for (final e in activeEntitlements) {
  print('${e.entitlementId} - status: ${e.status.name}, expires: ${e.expiresAt}');
}

Manage subscriptions #

// Android: open Google Play subscription management
launchUrl(Uri.parse(orca.playStoreManagementUrl));

// iOS / macOS: open App Store subscription management
launchUrl(Uri.parse(orca.appStoreManagementUrl));

Clean up #

orca.logout();  // Clears customer identity, stops SSE stream

Configuration #

The Orca backend must be configured with your products and store mappings. See the Orca documentation for details on setting up entitlements, products, and store integrations.

License #

MIT - see the LICENSE file for details.