SubscriptionFlow Android SDK (1.0.0)

Requirements: Play Billing Library 8 or later · Kotlin · No SDK to install

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
  }
}

Set the account token as obfuscatedAccountId so Google keeps the purchase attached to the customer.

// Declare the listener before the client: Kotlin initialises properties in order.
private val purchasesListener = PurchasesUpdatedListener { result, purchases ->
    if (result.responseCode == BillingClient.BillingResponseCode.OK) {
        purchases?.filter { it.purchaseState == Purchase.PurchaseState.PURCHASED }
            ?.forEach { report(it) }
    }
}

private val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesListener)
    .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    .build()

fun buy(activity: Activity, product: ProductDetails, pair: SFPair) {
    val offer = product.subscriptionOfferDetails?.firstOrNull() ?: return
    val params = BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(product)
                .setOfferToken(offer.offerToken)
                .build()
        ))
        .setObfuscatedAccountId(pair.accountToken)   // links the purchase to the customer
        .build()
    billingClient.launchBillingFlow(activity, params)
}

Send the purchase token. SubscriptionFlow verifies it with Google and acknowledges the purchase for you when it links it. Full reference: Report a purchase (app).

private val http = OkHttpClient()

fun report(purchase: Purchase) {
    val pair = currentPair()   // from secure storage
    val body = JSONObject()
        .put("store", "google")
        .put("purchase_token", purchase.purchaseToken)
        .toString()
        .toRequestBody("application/json".toMediaType())

    val request = Request.Builder()
        .url("https://<your-subscriptionflow-domain>/api/v1/mobile-stores/client/purchases")
        .header("Accept", "application/json")
        .header("X-SF-Account-Token", pair.accountToken)
        .header("X-SF-Client-Secret", pair.clientSecret)
        .post(body)
        .build()

    http.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            response.use {
                when (it.code) {
                    200 -> unlock()                       // linked and acknowledged
                    409, 422 -> showProblem(it.body?.string())
                    401 -> refreshPairAndRetry(purchase)  // once
                    else -> Unit                          // 429 / 5xx: retried on next sweep
                }
            }
        }
        override fun onFailure(call: Call, e: IOException) = Unit  // retried on next sweep
    })
}

Play does not redeliver purchases on its own. When the app starts and whenever it returns to the foreground, ask Play for the subscriptions and report the ones not acknowledged yet.

fun sweep() {
    val params = QueryPurchasesParams.newBuilder()
        .setProductType(BillingClient.ProductType.SUBS)
        .build()
    billingClient.queryPurchasesAsync(params) { result, purchases ->
        if (result.responseCode == BillingClient.BillingResponseCode.OK) {
            purchases.filter { it.purchaseState == Purchase.PurchaseState.PURCHASED && !it.isAcknowledged }
                .forEach { report(it) }
        }
    }
}

Unlock features from the entitlements, not from product ids: they also cover web and App Store subscriptions. Full reference: Get my entitlements (app).

Request

GET https://<your-subscriptionflow-domain>/api/v1/mobile-stores/client/entitlements
X-SF-Account-Token: <account_token>
X-SF-Client-Secret: <client_secret>

Response 200

{
  "status": true,
  "data": [
    {
      "key": "pro",
      "name": "Pro",
      "source": "AppStore",
      "subscription_id": "5faf8...",
      "expires_at": "2026-11-28T09:00:00+00:00",
      "grants": [
        { "source": "AppStore", "subscription_id": "5faf8...",
          "status": "Active", "expires_at": "2026-11-28T09:00:00+00:00" }
      ]
    }
  ]
}

What the purchase report can answer, and what the app should do.

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 Google Play connection is set to Sandbox, upload the build to the internal testing track and buy with a licence tester account.

What happens with licence-tester purchases on a live account?

On a Production connection they are verified and answered with "sandbox": true and the plan's entitlements, but nothing is recorded.

How do renewals, holds and refunds reach SubscriptionFlow?

Through Google's real-time developer notifications (Pub/Sub). Set them up with the notification URL from the Google Play integration page.

Why can I not buy in my debug build?

Google Play only sells to builds of an app that has been uploaded to a testing track, signed in with a tester account.

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.