Unifying alternative billing across Android and iOS at the flow level

[hyochan]

Status (2026-11): Not implemented. OpenIAP still exposes Android Billing Programs (api-android.graphql) and Apple external purchase APIs (api-ios.graphql) separately. Before any implementation, we compare each program's eligibility, disclosure, cancellation, token and reporting rules and review the shared API here.

Context

I'm implementing Android alternative billing (user-choice billing with local PG rails) in a production app as a live OpenIAP test vehicle, and looking at what the iOS side would take. Today every app authors two different integrations. Can OpenIAP offer alternative billing under one shared spec for both stores?

Why one shared UI does not work

The store rules differ, so one shared "choice UI" would get an app rejected on one side:

• Google Play allows in-app billing choice (user-choice billing screen, external offers).
• Apple requires its own disclosure sheets before linking out. What is allowed depends on the entitlement, storefront and OS version (iOS 16+, 17.4+, 18.1+). See ExternalPurchaseCustomLink.

Proposal: unify at the flow level

Both platforms share the same flow, check → disclose → handoff → report, and differ only in how each step renders.

1. Shared capability: isAlternativeBillingAvailable(program) in api.graphql. Android maps to the billing-program availability check; iOS maps to entitlement and storefront eligibility.
2. Shared flow type: one state machine. Android presents in-app choice; iOS presents the Apple sheet and opens the external URL.
3. Normalized report token: Play's externalTransactionToken and Apple's externalPurchaseToken become something like AlternativeBillingReport { platform, reportToken }, with per-platform server reporting underneath.
4. Tiering: the shared core is the external-link flow. Android in-app choice stays a platform extension.

Hard requirement: the iOS path is safe by default. Skipping the Apple sheet or rendering PG options inside the app must be impossible to express in the shared API.

Open questions

• Naming and shape of the capability, flow and report types.
• Where reporting lives: client helper, server guidance, or both.
• How to represent the entitlement × storefront × OS-version matrix.
• Whether Android in-app choice needs shared disclosure primitives.

Help wanted: Apple external purchase tokens in Sandbox

On our iPhone in Korea, StoreKit reported KR even with a German VPN and a German Sandbox storefront, so ExternalPurchaseCustomLink.isEligible returned false and no token was issued.

If you can test on an iPhone or iPad in a supported EU country with the External Purchase Custom Link entitlement and a matching Sandbox storefront, please comment with your country, OS version, the isEligible result, and whether StoreKit returned each token (ACQUISITION and SERVICES). Keep the token values private. Thanks!