SubscriptionFlow Flutter SDK (1.0.0)

Requirements: iOS and Android · Flutter 3.38+ / Dart 3.10+ · StoreKit 2 and Play Billing 8

Your backend, the store and SubscriptionFlow each do one part. Your SubscriptionFlow API credentials never leave your server.

Do this once, in your SubscriptionFlow account.

Your backend issues one pair per customer with its SubscriptionFlow API token. Never call this from the app. Full reference: Issue an account token.

Request

POST https://<your-subscriptionflow-domain>/api/v1/mobile-stores/account-tokens
Authorization: Bearer <access_token>
Content-Type: application/json

{ "customer_id": "9f1c2e0a-5b7d-4c1e-8a64-0d3b2f7a9e11" }

Response 201

{
  "status": true,
  "data": {
    "account_token": "72b8598b-8706-4a5e-96a2-52abbd0400cb",
    "customer_id": "9f1c2e0a-5b7d-4c1e-8a64-0d3b2f7a9e11",
    "created_at": "2026-11-03T09:00:00+00:00",
    "revoked_at": null,
    "client_secret": "OOkXxkYIfion1fcWJqL1GIR5tdbVqMFI5wlABZafEJKlI8EO",
    "reused": false
  }
}

Add the package, then configure it once at launch with your SubscriptionFlow address and a credentials provider.

flutter pub add subscriptionflow_iap

import 'package:flutter/widgets.dart';
import 'package:subscriptionflow_iap/subscriptionflow_iap.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  SubscriptionFlowIap.configure('https://<your-subscriptionflow-domain>', credentials);
  runApp(const MyApp());
}

Future<SubscriptionFlowCredentials>? _inFlight;

// Called before every request. After a 401 the SDK calls it once with forceRefresh: true.
Future<SubscriptionFlowCredentials> credentials({bool forceRefresh = false}) async {
  if (!forceRefresh) {
    final cached = await readPairFromSecureStorage();
    if (cached != null) return cached;
  }
  // Fetch your backend's current stored pair (never rotate here); one fetch at a time.
  return _inFlight ??= fetchPairFromYourBackend().whenComplete(() => _inFlight = null);
}

Listen to purchaseUpdates before you buy. The SDK reports, retries and completes purchases for you.

final sdk = SubscriptionFlowIap.instance;

sdk.purchaseUpdates.listen((update) {
  switch (update.status) {
    case SubscriptionFlowPurchaseStatus.verified:
      // update.verified!.entitlements is the customer's fresh list
      break;
    case SubscriptionFlowPurchaseStatus.failed:
      if (!update.retryable) {
        // Refused for good: show update.message, then
        sdk.finish(update.purchase);
      }
      break;
    case SubscriptionFlowPurchaseStatus.pending:
    case SubscriptionFlowPurchaseStatus.canceled:
      break;
  }
});

final products = await sdk.products({'pro_monthly'});
await sdk.purchase(products.first);

await sdk.restore();
final isPro = await sdk.isEntitled('pro');

The retry, redelivery and offline rules from the iOS and Android guides, already done.

• Retries 429, 5xx and network errors with backoff, honouring Retry-After, then leaves the purchase open for the next delivery.
• iOS redelivers unfinished purchases at launch; on Android the SDK sweeps open purchases at start and on every resume.
• On 401 it asks your provider for a fresh pair once.
• Refused purchases (409 / 422) are remembered and not resent; call finish() after handling them.
• Offline, isEntitled answers from the last list for up to 3 days, measured by SubscriptionFlow's clock.
• Sandbox, TestFlight and licence-tester purchases on a Production connection unlock for the session only; nothing is recorded.

Anyone using your app holds a token, so SubscriptionFlow only links purchases that belong to the caller.

• A purchase tagged with an account token links only to that token's customer, even after the token is revoked.
• An untagged Google purchase links: only the buyer's device knows its purchase token.
• An untagged Apple purchase links only from a signed StoreKit 2 transaction, and only when Let the app SDK claim untagged purchases is on (off by default).
• Register any other untagged purchase from your backend with POST /api/v1/mobile-stores/purchases.
• Every refusal gets the same answer, so the API never reveals whether a purchase exists.

The app endpoints have their own limits and never use your REST API quota. Over a limit the answer is 429 with Retry-After.

How do I test end to end?

Use a SubscriptionFlow account whose store connections are set to Sandbox.

How do I test on iOS?

On a real device signed in with a Sandbox tester. Purchases from an Xcode StoreKit configuration file are refused because Apple did not sign them.

How do I test on Android?

Upload the build to the internal testing track and buy with a licence tester account.

Is there an example app?

Yes: the package ships with a paywall example in example/ that buys, restores and lists entitlements.

Open a support ticket with the store, the environment and the last 6 characters of the transaction id or purchase token.

Issue, reuse, rotate and revoke per-customer account tokens. See Account Tokens for the concepts.

The app (or the Flutter SDK) reports a store purchase right after the store completes it. The SDK completes the store transaction only after a 200.

The app reads its own customer's entitlements with its account token pair. Same data as the backend Entitlements endpoint.