Terminal
Terminal/Skill
Guide to Google Play alternative billing and external offers on Android, covering regional eligibility, the APIs, and reporting transactions within 24 hours.
By RevenueCat
Works with
npx skills add revenuecat/play-billing-skills --skill alternative-billingGoogle Play exposes several programs that let you present payment paths outside Google Play billing. This skill walks you through picking the right program for your region, wiring the PBL APIs, and reporting transactions to the externaltransactions API within 24 hours.
Confirm program eligibility before you touch any code. Eligibility is driven by region, product type, and Play Console enrollment.
build.gradle. Features map to PBL versions:| Program | Minimum PBL |
|---|---|
| User choice billing | 5.2 (6.1 renamed APIs) |
| Alternative billing only | 6.1 |
| External offers (unified API) | 8.2.1 |
| External content links | 8.2.1 |
| External payment links | 8.3.0 |
| Region | Available programs |
|---|---|
| South Korea | User choice billing |
| EEA | User choice billing, alternative billing only, external offers, external content links, external payment links |
| India | User choice billing |
| United States | User choice billing, external content links, external payment links |
Do not hard code country lists. The PBL surfaces eligibility.
billingClient.isBillingProgramAvailableAsync(
BillingProgram.EXTERNAL_OFFER,
listener
)
For alternative billing only, use isAlternativeBillingOnlyAvailableAsync(). A BILLING_UNAVAILABLE result means the user or account is ineligible.
Pick the program variant that matches your goals and region coverage.
| Program | Flow | BillingClient setup | Token source |
|---|---|---|---|
| User choice billing | Google renders a choice screen | enableUserChoiceBilling(listener) | UserChoiceDetails.externalTransactionToken |
| Alternative billing only | No Google Play billing at all, info dialog required | enableAlternativeBillingOnly() | createAlternativeBillingOnlyReportingDetailsAsync() |
| External offers | Link out to a website for deals | enableBillingProgram(EXTERNAL_OFFER) | createBillingProgramReportingDetailsAsync() |
| External content links | Link out for digital content (US) | enableBillingProgram(EXTERNAL_CONTENT_LINK) | createBillingProgramReportingDetailsAsync() |
| External payment links | Choice screen with developer option | enableBillingProgram(EXTERNAL_PAYMENTS, devListener) | createBillingProgramReportingDetailsAsync() |
externalTransactionToken: generated by the PBL, tied to one user and device context, attached to the initial report only. Generate a new token per transaction.externalTransactionId: string you generate, uniquely identifies the transaction in your system. Each renewal uses a new ID referencing the first via initialExternalTransactionId. Do not put PII in the ID.Before you write client code, plan these backend pieces:
POST /androidpublisher/v3/applications/{packageName}/externalTransactions within 24 hours of charge.initialExternalTransactionId without the token.:refund on the original transaction ID.createexternaltransaction and refundexternaltransaction share 1,200 QPM. Stagger migrations.launchBillingFlow().PurchasesUpdatedListener fires.UserChoiceBillingListener fires with token and products.externaltransactions.isAlternativeBillingOnlyAvailableAsync().showAlternativeBillingOnlyInformationDialog(). On USER_CANCELED, retry next attempt.createAlternativeBillingOnlyReportingDetailsAsync() to get a fresh token.val userChoiceListener = UserChoiceBillingListener { details ->
backend.startExternalPurchase(
details.externalTransactionToken,
details.products
)
}
val billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases(
PendingPurchasesParams.newBuilder().build()
)
.enableUserChoiceBilling(userChoiceListener)
.build()
For subscription upgrades that stay in your billing system, set setOriginalExternalTransactionId() on SubscriptionUpdateParams to skip the choice screen.
billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
object : AlternativeBillingOnlyReportingDetailsListener {
override fun onAlternativeBillingOnlyTokenResponse(
result: BillingResult,
details: AlternativeBillingOnlyReportingDetails?
) {
if (result.responseCode != BillingResponseCode.OK) return
backend.send(details?.externalTransactionToken)
}
}
)
val params = BillingProgramReportingDetailsParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_OFFER)
.build()
billingClient.createBillingProgramReportingDetailsAsync(
params,
reportingListener
)
Launch the link after you persist the token:
val linkParams = LaunchExternalLinkParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_OFFER)
.setLinkUri(Uri.parse("https://myapp.com/offer"))
.setLaunchMode(
LaunchExternalLinkParams.LaunchMode
.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
)
.build()
billingClient.launchExternalLink(activity, linkParams, listener)
val devBillingListener = DeveloperProvidedBillingListener { details ->
backend.handleExternalPayment(details)
}
val billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases(
PendingPurchasesParams.newBuilder().build()
)
.enableBillingProgram(
EnableBillingProgramParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setDeveloperProvidedBillingListener(devBillingListener)
.build()
)
.build()
Attach a DeveloperBillingOptionParams to your BillingFlowParams when you call launchBillingFlow(). The choice screen renders only when the user is in a supported country, the program is enabled on the client, and you passed a developer option.
PBL 9 change:
DeveloperProvidedBillingDetails.getLinkUri()is now@Nullable. The external payment link may not be resolved at selection time, so guard against bothnulland empty string before parsing it as aUri:val linkUri = details.linkUri if (!linkUri.isNullOrEmpty()) { startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(linkUri))) } else { showExternalPaymentUnavailableState() }
POST /androidpublisher/v3/applications/{packageName}/externalTransactions?externalTransactionId=txn-1
{
"originalPreTaxAmount": { "priceMicros": "4990000", "currency": "USD" },
"originalTaxAmount": { "priceMicros": "449100", "currency": "USD" },
"transactionTime": "2026-01-15T10:30:00Z",
"recurringTransaction": {
"externalTransactionToken": "token_from_pbl",
"externalSubscription": { "subscriptionType": "RECURRING" }
},
"userTaxAddress": { "regionCode": "US" }
}
Amounts use priceMicros. Multiply by 1,000,000. For India, include administrativeArea in userTaxAddress because tax rates vary by state.
Drop the token, add initialExternalTransactionId:
{
"recurringTransaction": {
"initialExternalTransactionId": "txn-1",
"externalSubscription": { "subscriptionType": "RECURRING" }
}
}
POST /androidpublisher/v3/applications/{packageName}/externalTransactions/{externalTransactionId}:refund
Supply the pre tax amount for partial refunds.
createBillingProgramReportingDetailsAsync(). 8.2.0 has a bug.externalTransactionId and from any external link Uri.