in_app_purchase_amazon

1. What the review found

1.1 The Flutter side

• in_app_purchase 3.3.0 (June 2026) is fully federated: in_app_purchase (app-facing) → in_app_purchase_platform_interface ^1.4 → endorsed in_app_purchase_android ^0.5 (Google Play Billing, Pigeon-based) and in_app_purchase_storekit ^0.4 (StoreKit 1/2).
• The platform interface explicitly invites third-party implementations: extend InAppPurchasePlatform, call InAppPurchasePlatform.setInstance(...); store-specific extras go through InAppPurchasePlatformAddition. Breaking changes to the interface are avoided by policy, and the base class ships default (throwing) implementations, so new interface methods do not break compile of an external implementation.
• The surface to implement is small: purchaseStream, isAvailable(), queryProductDetails(), buyNonConsumable(), buyConsumable(), completePurchase(), restorePurchases(), countryCode().
• Override mechanism exists. flutter/flutter #137040 (merged July 2024, stable from Flutter 3.27) lets an app override an endorsed native implementation simply by adding a direct dependency on another package that declares implements: in_app_purchase for the same platform. Both packages remain in pubspec.lock; only the override is registered. This is the piece that was missing for years and it is now in place.
• The Android implementation pattern to copy is well established: Pigeon @HostApi/@FlutterApi, a typed billing_client_wrappers library, GooglePlayProductDetails/GooglePlayPurchaseDetails subclasses, and a registerPlatform() static that sets both the platform instance and the addition instance.

1.2 The Amazon side

• Use the Appstore SDK, not the compatibility shim. The Appstore Billing Compatibility SDK (the Play-Billing-lookalike, com.amazon.device:appstore-billing-compatibility:4.2.0) loses technical support and maintenance on 15 September 2026 — thirteen days from now. Building on it would mean building on an abandoned layer. The Appstore SDK proper (com.amazon.device:amazon-appstore-sdk:3.0.9, May 2026) is the supported path and is on Maven Central, so the plugin can pull it with a normal Gradle dependency; no JAR redistribution or license question.
• The IAP API is small and asynchronous: PurchasingService.registerListener / getUserData / getProductData / getPurchaseUpdates(reset) / purchase(sku) / notifyFulfillment(receiptId, result) / enablePendingPurchases, with responses delivered to one PurchasingListener via a manifest-declared ResponseReceiver broadcast receiver. Every request returns a RequestId which the response carries back — that is the correlation key the Dart layer needs.
• Three product types: CONSUMABLE, ENTITLED, SUBSCRIPTION. Fulfillment is explicit (notifyFulfillment), and sending anything other than FULFILLED cancels and refunds the order. Pending purchases (Amazon Kids parent approval) exist since 3.0.4. Tiered subscriptions, Quick Subscribe and add-on subscriptions exist but are gated to select partners — out of scope for v1.
• Amazon's own cross-platform IAP plugins (Cordova, Xamarin, AIR) lost support in June 2026; Amazon's guidance is now "integrate the Appstore SDK natively". A Flutter package doing exactly that is aligned with where Amazon is pushing developers.
• Market reality check. Amazon shut the Appstore on non-Amazon Android devices on 20 August 2025 (and killed Amazon Coins). The only remaining targets are Fire tablets and Fire TV running Fire OS. Amazon's newest Fire TV hardware is moving to Vega OS, which is not Android and does not run Flutter. So the addressable surface for this package is Fire OS tablets and the installed base of Android-based Fire TVs — real, but not growing.

1.3 Prior art

2. Why it is not trivial

2.1 Feature map — what an app written against in_app_purchase gets on each store

Read this as "what does my existing in_app_purchase code do when the platform underneath is Amazon". The Play and App Store columns describe the endorsed implementations as of 3.3.0; the Amazon column describes the package proposed in this document, not the raw Amazon SDK.

Reading the map. Everything in the "core purchase flow" group is green or nearly so — an app that only queries products, buys, completes and restores will run unchanged on Amazon. The amber cells cluster in three places: price fidelity (one lossy field), status nuance (cancel vs. error, pending only for Kids), and the subscription-management extras that Play and Apple expose but Amazon either doesn't have or gates behind partner programmes. The red cells are almost all features that are store-specific on every store already (offer codes, proration, obfuscated ids), so an app written portably against the interface is unlikely to depend on them. The two places where Amazon is actually ahead — client-side refund path and cancellation visibility — go into the platform addition rather than being hidden.

3. Packaging and registration

Two packages, both in one repo. The split costs almost nothing and unlocks both deployment styles.

Mode A — dedicated Amazon build (recommended for v1)

# pubspec.yaml of the Amazon-flavoured app
dependencies:
  in_app_purchase: ^3.3.0
  in_app_purchase_amazon_default: ^0.1.0   # overrides in_app_purchase_android on Android

Requires Flutter ≥ 3.27. App code is unchanged: InAppPurchase.instance now talks to Amazon. This matches how Amazon submissions already work (separate PEM key asset, separate signing, usually a separate product flavor for Fire OS form factors).

Mode B — single binary, runtime switch

dependencies:
  in_app_purchase: ^3.3.0
  in_app_purchase_amazon: ^0.1.0   # no override; Play Billing stays registered

// main.dart
WidgetsFlutterBinding.ensureInitialized();
if (await InAppPurchaseAmazonPlatform.isAmazonInstall()) {   // installer == com.amazon.venezia, or --dart-define=STORE=amazon
  InAppPurchaseAmazonPlatform.registerPlatform();             // replaces the Play instance before first use
}

Works because InAppPurchasePlatform.instance is a plain setter and InAppPurchase.instance delegates lazily. Caveat: both SDKs ship in the APK. Google tolerates that; Amazon review historically frowns on Play dependencies in Fire OS submissions. Document it, don't default to it.

Plugin pubspec (core)

name: in_app_purchase_amazon
flutter:
  plugin:
    platforms:
      android:
        package: dev.yourorg.inapppurchaseamazon
        pluginClass: InAppPurchaseAmazonPlugin
dependencies:
  in_app_purchase_platform_interface: ^1.4.0
  plugin_platform_interface: ^2.1.0
dev_dependencies:
  pigeon: ^26.0.0

Android build contributions

• implementation "com.amazon.device:amazon-appstore-sdk:3.0.9" pinned, not 3.+.
• Plugin AndroidManifest.xml contributes (via manifest merge) the <queries> for com.amazon.venezia and com.amazon.sdktestclient, and the com.amazon.device.iap.ResponseReceiver with android:exported="true" and permission com.amazon.inapp.purchasing.Permission.NOTIFY. Apps add nothing to their manifest.
• consumer-rules.pro: -keep class com.amazon.** { *; }, -dontwarn com.amazon.**.
• AppstoreAuthenticationKey.pem stays an app responsibility in app/src/<flavor>/assets/. The example app documents it; the plugin checks for its presence at register time and logs a clear warning if missing (a missing key makes every call fail with FAILED, which is otherwise hard to diagnose).
• minSdk 24 to match in_app_purchase_android.

4. Native layer (Kotlin + Pigeon)

Mirror in_app_purchase_android: one Pigeon file, one Kotlin plugin class, one listener class. No method channels by hand.

// pigeons/messages.dart
enum AmazonRequestStatus { successful, failed, notSupported, alreadyPurchased, invalidSku, pending }
enum AmazonProductType   { consumable, entitled, subscription }
enum AmazonFulfillmentResult { fulfilled, existingPurchase, notEligible, unavailable }

class PlatformUserData { late String userId; late String marketplace; String? countryCode; }
class PlatformPromotionPlan { late String promotionPrice; late String promotionPricePeriod; late int promotionPriceCycles; }
class PlatformPromotion { late String promotionType; late List<PlatformPromotionPlan> plans; }
class PlatformProduct {
  late String sku; late AmazonProductType productType;
  late String title; late String description; late String price; late String smallIconUrl;
  String? subscriptionPeriod; String? freeTrialPeriod;
  late List<PlatformPromotion> promotions;
  late String rawJson;
}
class PlatformReceipt {
  late String receiptId; late String sku; late AmazonProductType productType;
  late int purchaseDateMillis; int? cancelDateMillis; late bool isCanceled;
  String? termSku; int? deferredDateMillis; String? deferredSku;
  late String rawJson;
}
class PlatformUserDataResponse        { late String requestId; late AmazonRequestStatus status; PlatformUserData? userData; }
class PlatformProductDataResponse     { late String requestId; late AmazonRequestStatus status; late List<PlatformProduct> products; late List<String> unavailableSkus; }
class PlatformPurchaseResponse        { late String requestId; late AmazonRequestStatus status; PlatformUserData? userData; PlatformReceipt? receipt; }
class PlatformPurchaseUpdatesResponse { late String requestId; late AmazonRequestStatus status; PlatformUserData? userData; late List<PlatformReceipt> receipts; late bool hasMore; }

@HostApi()
abstract class AmazonBillingApi {
  void registerListener();                       // idempotent; app context
  String getUserData();                          // returns requestId
  String getProductData(List<String> skus);
  String getPurchaseUpdates(bool reset);
  String purchase(String sku);
  void notifyFulfillment(String receiptId, AmazonFulfillmentResult result);
  void enablePendingPurchases();
  bool isSandboxMode();                          // LicensingService.getAppstoreSDKMode() == SANDBOX
  String? installerPackageName();                // for Mode B detection
  void setAutoSyncOnResume(bool enabled);
}

@FlutterApi()
abstract class AmazonBillingCallbackApi {
  void onUserDataResponse(PlatformUserDataResponse r);
  void onProductDataResponse(PlatformProductDataResponse r);
  void onPurchaseUpdatesResponse(PlatformPurchaseUpdatesResponse r);
  void onPurchaseResponse(PlatformPurchaseResponse r);
}

Kotlin plugin responsibilities

• onAttachedToEngine: keep application context, build Pigeon host, create the single PurchasingListener that forwards every callback to the Flutter API. registerListener() from Dart calls PurchasingService.registerListener(appContext, listener) once.
• Implements ActivityAware + DefaultLifecycleObserver. On onResume, if auto-sync is enabled (default true), fire getUserData() and getPurchaseUpdates(false). Responses for these plugin-initiated requests are tagged so the Dart layer routes them to the stream rather than to a waiting completer.
• Every callback runs on the UI thread already; marshal straight into Pigeon. Convert Receipt/Product via their toJSON() for rawJson so nothing is lost even if a field is unmapped.
• Map Java enums to Pigeon enums in one place; unknown values become failed plus a log line, never a crash.

5. Dart layer

lib/
  in_app_purchase_amazon.dart          // exports platform, addition, param, details types
  amazon_appstore_wrappers.dart        // typed wrappers (mirrors billing_client_wrappers)
  src/
    in_app_purchase_amazon_platform.dart
    in_app_purchase_amazon_platform_addition.dart
    amazon_product_details.dart        // AmazonProductDetails extends ProductDetails
    amazon_purchase_details.dart       // AmazonPurchaseDetails extends PurchaseDetails
    amazon_purchase_param.dart         // AmazonPurchaseParam extends PurchaseParam
    request_router.dart                // RequestId -> Completer / stream routing
    price_parser.dart                  // best-effort rawPrice + marketplace->currency
    messages.g.dart                    // pigeon output

class InAppPurchaseAmazonPlatform extends InAppPurchasePlatform {
  static void registerPlatform() {
    InAppPurchasePlatform.instance = InAppPurchaseAmazonPlatform();
    InAppPurchasePlatformAddition.instance = InAppPurchaseAmazonPlatformAddition(...);
  }
  static Future<bool> isAmazonInstall();   // installer == com.amazon.venezia || dart-define

  @override Stream<List<PurchaseDetails>> get purchaseStream;   // broadcast
  @override Future<bool> isAvailable();
  @override Future<ProductDetailsResponse> queryProductDetails(Set<String> identifiers);
  @override Future<bool> buyNonConsumable({required PurchaseParam purchaseParam});
  @override Future<bool> buyConsumable({required PurchaseParam purchaseParam, bool autoConsume = true});
  @override Future<void> completePurchase(PurchaseDetails purchase);
  @override Future<void> restorePurchases({String? applicationUserName});
  @override Future<String> countryCode();
}

class InAppPurchaseAmazonPlatformAddition extends InAppPurchasePlatformAddition {
  Future<AmazonUserData> getUserData();
  Future<void> notifyFulfillment(String receiptId, AmazonFulfillmentResult result); // the refund path
  Future<void> enablePendingPurchases();
  Future<bool> isSandboxMode();
  Future<List<AmazonReceipt>> getPurchaseUpdates({required bool reset}); // raw, paginated-to-completion
  void setAutoSyncOnResume(bool enabled);
}

class AmazonProductDetails extends ProductDetails {
  final AmazonProduct product;          // full wrapper incl. promotions, periods, icon
  final bool priceIsEstimated;          // true when rawPrice/currencyCode were inferred
}
class AmazonPurchaseDetails extends PurchaseDetails {
  final AmazonReceipt receipt;
  final String userId;                  // needed for RVS
  final String marketplace;
  final AmazonRequestStatus rawStatus;  // so apps can see FAILED vs. anything else
}

Request router

One Map<String, Completer> per response type keyed by requestId. If a response arrives with no matching completer (plugin-initiated auto-sync, or a response that outlived an engine restart) it is routed to purchaseStream when it carries receipts, otherwise dropped with a debug log. getPurchaseUpdates pagination (hasMore) is handled inside the router: it re-issues the call and accumulates until hasMore == false, then completes. Timeouts: none by default (Amazon can legitimately take a while while the parent approves a pending purchase); an optional per-call timeout is exposed on the addition.

6. Semantic mapping

Status mapping

Field mapping

7. Open decisions and known gaps

1. Price fidelity. The inferred rawPrice/currencyCode are the one place this implementation is lossy versus Play/StoreKit. Decision: ship the heuristic, flag it with priceIsEstimated, and tell apps that need exact amounts to read them from their own catalogue or from RVS. Do not silently return plausible-looking wrong numbers without the flag.
2. FAILED → canceled. Chosen because that is what it means 99% of the time and because canceled is what UIs should do with it. The raw status is preserved. Alternative (map to error) would make every user back-out show an error dialog in apps written against Play semantics.
3. Subscription upgrades. No equivalent of ChangeSubscriptionParam. A GooglePlayPurchaseParam passed to this platform is ignored with a debug warning; modifySubscription() can be added to the addition later for partners who have tiered subscriptions enabled.
4. Auto-sync on resume default. On by default because Amazon calls it mandatory and apps written against the interface would otherwise silently miss approved pending purchases. Can be disabled via the addition for apps that call restorePurchases() themselves.
5. Idempotency. The plugin dedupes receipts within one process lifetime by receiptId before emitting. Cross-launch dedupe is the app's job (as on every store) and the README says so.
6. Receipt verification. Out of scope client-side (Amazon says server-side RVS only). README includes the RVS request shape and links the sandbox endpoint. Expose isSandboxMode() so backends can be pointed at the RVS sandbox during App Tester runs.
7. Endorsement. Assume none. flutter/packages hosts only first-party store implementations; design and document as a non-endorsed override, which is precisely what #137040 was built for.
8. Package name. Confirm in_app_purchase_amazon is free on pub.dev; otherwise in_app_purchase_amazon_appstore. Publish under a verified publisher so it can be found via "packages that implement in_app_purchase".

8. Testing

• Dart unit tests against the Pigeon-generated TestAmazonBillingApi mock: every mapping row above becomes a test; router pagination, dedupe, orphaned-response handling, chunked getProductData.
• Kotlin unit tests for enum/JSON conversion with Robolectric (the SDK classes are plain Java; no device needed for conversion tests).
• Device integration on a Fire tablet with Amazon App Tester and an amazon.sdktester.json pushed to /sdcard/: consumable, entitlement, subscription (incl. free trial + promo), cancel-in-dialog, pending purchase via Amazon Kids profile, already-purchased, restore after data clear. Automate with integration_test plus manual steps for the dialog interactions. Fire TV Stick (Android-based) for D-pad flow sanity.
• Live App Testing (Amazon LAT) before first release: production RVS, real marketplace pricing strings for the parser table (collect at least US, UK, DE, JP, IN samples).
• CI: flutter analyze, unit tests, example app builds in both Mode A and Mode B, Flutter stable and beta.

9. Milestones and effort

Roughly 4–5 weeks for one engineer familiar with Flutter plugins and Android, most of it in M1 and in device testing. The native bridge itself is a few hundred lines; the time goes into the semantic edges and the test matrix.

10. Risks

11. Sources

• in_app_purchase 3.3.0 on pub.dev · in_app_purchase_platform_interface docs
• flutter/flutter #137040 — Support overriding native endorsed plugins (closes #80374)
• Integrate the Appstore SDK (Maven Central coordinates, PEM key) · Appstore SDK release notes (3.0.9, May 2026)
• Implement Appstore SDK IAP (API surface, manifest, fulfillment rules, product fields)
• Appstore Billing Compatibility SDK (support ends 15 Sep 2026) · Amazon SDK download notes
• Amazon: changes to Appstore for Android devices and Coins (shutdown 20 Aug 2025)
• Prior art: amazon_iap, flutter_amazon_iap, predatorx7/in_app_purchase_amazon, flutter_inapp_purchase