Flutter SDK Purchases

Tracking a purchase

trackExternalPurchase(MagifyPurchase purchase) reports a purchase — one-off or subscription. Per-product limit counters are reset, and, depending on what you pass in ios/android, the purchase may be queued for server-side validation — see Server-side validation below.

MagifyPurchase has two factories:

MagifyPurchase.inApp({
  required String productId,
  required String price,      // decimal number as a string
  required String currency,
  required String transactionId,
  MagifyIosPurchase ios = const MagifyIosPurchase(),
  MagifyAndroidPurchase android = const MagifyAndroidPurchase(),
});

MagifyPurchase.subscription({
  required String productId,
  required String price,
  required String currency,
  required String transactionId,
  required bool isTrial,
  MagifyIosPurchase ios = const MagifyIosPurchase(),
  MagifyAndroidPurchase android = const MagifyAndroidPurchase(),
});
await MagifyClient.instance.trackExternalPurchase(
  MagifyPurchase.subscription(
    productId: 'week_premium_subscription',
    price: '4.99',
    currency: 'USD',
    transactionId: '2000000123456789',
    isTrial: false,
  ),
);

MagifyIosPurchase({originalTransactionId, needValidation = true}) and MagifyAndroidPurchase({purchaseToken, billingCountryCode}) carry the platform-only fields.

The constructors throw ArgumentError for an empty productId, transactionId or currency, and for a price that does not parse as a decimal number.

Trusted purchases

trackExternalTrustedPurchase(MagifyTrustedPurchase purchase, {bool? isSubscription}) sends a store-signed purchase record for server-side validation, mirroring the native TrustedPurchaseRecord field for field:

await MagifyClient.instance.trackExternalTrustedPurchase(
  MagifyTrustedPurchase(
    productId: 'week_premium_subscription',
    transactionId: '2000000123456789',
    originalTransactionId: '2000000123456789',
    purchasedAt: DateTime.now(),
    price: '4.99',
    currency: 'USD',
    commissionAmount: '1.49',
    commissionCurrency: 'USD',
    type: MagifyTrustedPurchaseType.initialPurchase,
    periodType: MagifyTrustedPeriodType.normal,
    productIdType: MagifyTrustedProductIdType.subscription,
  ),
  isSubscription: true,
);

isSubscription picks what happens beyond validation itself, and both native platforms read it the same way:

Checking purchase state

Future<bool> isPurchaseProcessed(String productId) reports whether the SDK has already counted a purchase of that product.

final alreadyCounted = await MagifyClient.instance.isPurchaseProcessed('week_premium_subscription');

Server-side validation

trackExternalPurchase only queues a purchase for server-side validation when you pass the store's own proof of purchase through the platform-specific section of MagifyPurchase:

  • Android — MagifyAndroidPurchase(purchaseToken: ...). Passing the Google Play Billing purchase token (alongside transactionId) is what triggers validation against Google Play.
  • iOS — MagifyIosPurchase(originalTransactionId: ..., needValidation: true). needValidation defaults to true, so validation runs as soon as originalTransactionId is set.
await MagifyClient.instance.trackExternalPurchase(
  MagifyPurchase.subscription(
    productId: 'week_premium_subscription',
    price: '4.99',
    currency: 'USD',
    transactionId: '2000000123456789',
    isTrial: false,
    android: MagifyAndroidPurchase(
      purchaseToken: purchase.purchaseToken, // Google Play Billing purchase token
    ),
  ),
);

Leave ios/android at their defaults (const MagifyIosPurchase() / const MagifyAndroidPurchase()) to track the purchase without server-side validation.

This only applies to trackExternalPurchase — Trusted purchases are always sent for server-side validation, since that is the entire point of trackExternalTrustedPurchase.

Server-side verification

Verification verdicts arrive on Stream<MagifyPurchaseVerification> get purchaseVerifications — each event carries a productId and a MagifyPurchaseVerificationCode. This stream is observation only.

The retry behavior after a non-terminal verdict is controlled separately with setPurchaseVerificationPolicy(Map<MagifyPurchaseVerificationCode, MagifyRepeatState> policy) — set this map up front rather than reacting to each verdict individually.

  • A code left out of the map keeps each platform's built-in behavior, and those differ: invalidCredentials drops the record on iOS and retries later on Android. Pass the built-in magifyAlignedPurchaseVerificationPolicy constant to even that out.
  • doesntSupport and cancelled only take effect on iOS; Android handles both itself.
  • An empty map hands retry behavior back to each platform's built-in default.
  • Passing success or invalid throws ArgumentError — both are terminal on both platforms. magifyPurchaseVerificationPolicyCodes is the set of codes the map accepts.
await MagifyClient.instance.setPurchaseVerificationPolicy(magifyAlignedPurchaseVerificationPolicy);

MagifyClient.instance.purchaseVerifications.listen((verification) {
  debugPrint('${verification.productId}: ${verification.code}');
});

Purchase and subscription status

Next step

Continue to Analytics for custom events and transactions, or to Advertisement for ad revenue reporting.

Related articles

Flutter SDK Configuration options

iOS SDK Integration with other SDK

Flutter SDK Initialization

IAppNavigator

Flutter SDK Lifecycle

SubscriptionProduct