SubscriptionFlow iOS SDK (1.0.0)

Requirements: iOS 15 or later · StoreKit 2 + Swift concurrency · 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
  }
}

StoreKit 2 requires the appAccountToken to be a UUID. SubscriptionFlow account tokens are UUIDs.

import StoreKit

struct SFPair { let accountToken: String; let clientSecret: String }

func buy(productId: String, pair: SFPair) async throws {
    guard let product = try await Product.products(for: [productId]).first,
          let token = UUID(uuidString: pair.accountToken) else { return }

    let result = try await product.purchase(options: [.appAccountToken(token)])
    switch result {
    case .success(let verification):
        await handle(verification, pair: pair)
    case .pending, .userCancelled:
        break
    @unknown default:
        break
    }
}

Send the signed transaction (JWS). SubscriptionFlow verifies it with Apple. Full reference: Report a purchase (app).

let baseURL = URL(string: "https://<your-subscriptionflow-domain>")!

func handle(_ verification: VerificationResult<Transaction>, pair: SFPair) async {
    var request = URLRequest(url: baseURL.appendingPathComponent("api/v1/mobile-stores/client/purchases"))
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("application/json", forHTTPHeaderField: "Accept")
    request.setValue(pair.accountToken, forHTTPHeaderField: "X-SF-Account-Token")
    request.setValue(pair.clientSecret, forHTTPHeaderField: "X-SF-Client-Secret")
    request.httpBody = try? JSONSerialization.data(withJSONObject: [
        "store": "apple",
        "signed_transaction": verification.jwsRepresentation,
    ])

    guard let (_, response) = try? await URLSession.shared.data(for: request),
          let status = (response as? HTTPURLResponse)?.statusCode else {
        return // network error: leave it unfinished, StoreKit delivers it again
    }

    switch status {
    case 200:
        await verification.unsafePayloadValue.finish()   // linked: unlock features
    case 409, 422:
        // Refused for good: tell the user / support, then finish so it is not redelivered.
        await verification.unsafePayloadValue.finish()
    case 401:
        break // fetch the current pair from your backend and call handle() again once
    default:
        break // 429 / 5xx: leave unfinished and try again later
    }
}

Renewals, purchases approved later (Ask to Buy) and purchases left unfinished arrive through Transaction.updates. Start listening as soon as the app launches.

func listenForTransactions(pair: SFPair) -> Task<Void, Never> {
    Task.detached {
        for await verification in Transaction.updates {
            await handle(verification, pair: pair)
        }
    }
}

For a Restore purchases button, sync with the App Store and report the current transactions again. Reporting twice never creates duplicates.

func restore(pair: SFPair) async throws {
    try await AppStore.sync()
    for await verification in Transaction.currentEntitlements {
        await handle(verification, pair: pair)
    }
}

Unlock features from the entitlements, not from product ids: they also cover web and Google Play 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 Apple connection is set to Sandbox, and buy on a real device signed in with a Sandbox tester.

What happens with App Review and TestFlight purchases?

They use the sandbox. On a Production connection SubscriptionFlow answers 200 with "sandbox": true and the entitlements of the mapped plan, but records nothing. Unlock the feature for that session only.

Why are purchases from Xcode refused?

Purchases from a local StoreKit configuration file are not signed by Apple, so they cannot be verified. This is by design.

Does reporting the same purchase twice create duplicates?

No. Reports are idempotent, so restore and retries are always safe.

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.