Google Play Billing Choice: choosing and wiring the right integration
Billing Choice does not replace Google Play Billing. It puts your own billing option or website next to it and lets the user decide. Two independent choices — who draws the comparison screen and where the money is collected — produce four integration shapes, and every one of them ends in the same obligation: report the sale to Google with an external transaction token.
What actually changes in the purchase flow
The program is opt-in and named. You work with BillingProgram.BILLING_CHOICE and pass it into nearly every call, so alternative billing behaves like a configured program rather than a global toggle. Google Play Billing stays on the screen as a first-class option every time; your job is to present a fair comparison and honor whichever side the user taps.
Two decisions define the integration:
- Who renders the choice screen. Google can draw it (ChoiceScreenType.GOOGLE_RENDERED), or you can draw your own (ChoiceScreenType.DEVELOPER_RENDERED) under the UX guidelines.
- Where the money lands. Either the user settles the charge inside the app using your own billing system (DeveloperBillingType.IN_APP), or the app hands them off to your website through an external web link (DeveloperBillingType.EXTERNAL_LINK).
The second decision is not only a UX matter. The billing type is recorded inside the transaction token, so Google can tell an in-app alternative sale from an external-link sale when it assesses the service fee.
The four integration scenarios
The scenario table below is the spine of the whole integration; every other section is a variation on one of its four rows. Read it as two axes: 1 versus 2 is where money is collected, A versus B is who renders the screen.
The deciding detail: where the token comes from
The scenario table shows how each purchase launches, but the column that should drive your architecture decision is not in it: the source of the external transaction token.
- Scenario 1A — Google renders the screen and mints the token. It arrives in the DeveloperProvidedBillingDetails object through the DeveloperProvidedBillingListener you registered up front.
- Scenarios 1B, 2A and 2B — you generate the token yourself with createBillingProgramReportingDetails().
Scenario 2A is the one place the A/B shorthand bends. Even though Google renders the choice screen, you mint the token before launching, because it has to travel with the redirect. So the listener-versus-generate split is really 1A versus everything else.
That single difference explains the rest of the client setup: the A scenarios need a callback path because Google has to tell you what the user picked, while the B scenarios already know the tap and instead need the assets to draw a fair screen plus a self-generated token.
Prerequisites before any code compiles
Three things must be in place first.
- Library version. Billing Choice requires Play Billing Library 9.1 or higher. This sits above the broader ecosystem floor: by August 31, 2026, new apps and updates must build against Billing Library 8 or later, with an extension available on request until November 1, 2026. Adopting Billing Choice puts you past that floor.
- Enrollment. Enroll in the program and review its requirements before calling the APIs. If you plan to offer external web links, declare that preference in Play Console before shipping.
- Play Console configuration. Set your choice screen preference (Google-rendered or developer-rendered) and your external web links preference. You may also upload an image representing the payment methods your own billing option accepts, shown on the choice screen.
That payment-method asset follows strict specifications, reproduced in the asset specification table below. Treat the values as fixed: overall size, per-card size, spacing, padding, outline, background, format and the five-method cap all apply together.
Enabling the program when you build the client
You turn Billing Choice on while constructing the BillingClient, through enableBillingProgram() with an EnableBillingProgramParams configured for BillingProgram.BILLING_CHOICE.
The detail that changes between scenarios is setDeveloperProvidedBillingListener(). Register it only when Google renders the choice screen, because Google needs a callback when the user picks your option instead of Play's. The familiar PurchasesUpdatedListener stays on the client and covers the case where the user picks Google Play. The two listeners live in different places — one on the client, one inside EnableBillingProgramParams — and together they cover both outcomes of the screen.
When you render your own screen, omit the DeveloperProvidedBillingListener entirely. You build the same params without it, because you handle the tap yourself and never need Google to call back into your app.
Checking availability and reading the configuration
Billing Choice is not guaranteed for every user, device or region, and the Play Console configuration reaches your app at runtime. isBillingProgramAvailable() answers both questions at once. The Kotlin form is a suspend function returning a result plus an availability details object.
The BillingChoiceAvailabilityDetails object holds the two values that decide your scenario: choiceScreenType (GOOGLE_RENDERED or DEVELOPER_RENDERED) and isExternalLinkAvailable. Read both, and fall back to standard Google Play Billing whenever the program is unavailable rather than assuming it is always on. Callback-style code can use isBillingProgramAvailableAsync(), which delivers the same result and details to a listener instead of suspending.
Scenario 1A: Google renders the choice, payment in app
This is the lightest integration because Google does most of the work. Enable the program with a DeveloperProvidedBillingListener, confirm availability reports GOOGLE_RENDERED, then launch with a developer billing option attached. The enableDeveloperBillingOption() call is what makes Google show the choice screen instead of going straight to Play's payment sheet.
From there the flow forks on the user's tap:
- Play Billing is chosen. Google completes the charge, and the PurchasesUpdatedListener already wired to your client fires with the same result it would deliver in a build without Billing Choice.
- Your option is chosen. The DeveloperProvidedBillingListener you registered is called with a DeveloperProvidedBillingDetails object, and that object contains an externalTransactionToken. Hold onto the token: you need it to charge the user through your own system and, afterward, to file the sale with Google.
You drew no screen and minted no token, because in this scenario Google did both.
Scenario 1B: You render the choice, payment in app
Rendering the screen yourself trades convenience for control. There is no Google screen to call you back from, so no DeveloperProvidedBillingListener. Instead you gather what you need to draw a fair screen and mint your own token when the user chooses you.
First, the Google Play side of the screen. getBillingChoiceInfo() returns the payment method artwork for Google Play (playBillingChoiceImageUrl) and any loyalty message Google wants shown beside its option (playBillingLoyaltyInfo), such as a Play Points rewards message. Load these every time you draw the screen rather than caching them. Callback-style code uses getBillingChoiceInfoAsync(), which is the form the UX guidelines reference.
Once the user taps your option, createBillingProgramReportingDetails() generates the reporting token with the billing type declared as in-app. Before charging the user, call showBillingProgramInformationDialog(), which presents the legally required disclosure for transacting outside Google Play Billing; the request carries the BillingProgram and the token you just generated. After the disclosure, run your own payment flow and keep the externalTransactionToken for the server-side report.
Scenarios 2A and 2B: sending users to an external web link
The external link scenarios replace in-app payment with a redirect to your website. In both, you generate the token yourself with createBillingProgramReportingDetails(), declaring DeveloperBillingType.EXTERNAL_LINK. Attempt these only when availability reported isExternalLinkAvailable as true.
Scenario 2A still launches through launchBillingFlow(), because Google renders the screen. The difference is that the developer billing option now carries the destination URI, the token you generated, and a launch mode. Attach that option to BillingFlowParams with enableDeveloperBillingOption() and call launchBillingFlow() as usual. A Play Billing tap runs the ordinary purchase; a tap on your option opens your link, with the token riding along on the redirect.
Scenario 2B has no billing flow to launch, because you render the screen. You send the user out with launchExternalLink(), setting the link URI, LinkType.LINK_TO_DIGITAL_CONTENT_OFFER, the launch mode, and the token.
A failure distinction worth internalizing: the launchExternalLink() result callback only confirms the link launched. It says nothing about whether the purchase went through, since that transaction happens on your website, outside the app. From that point, closing the sale and recording it are yours to handle.
The external transaction token and the mandatory report
Across all four scenarios the same object recurs: the externalTransactionToken. It links a tap on the choice screen to a line item in your Play revenue report, and it is what separates a working integration from a compliant one.
Every alternative billing transaction — in-app or external link — must be reported back to Google Play. The token ties your report to the original choice and encodes the DeveloperBillingType, so Google knows how to treat the sale when calculating the service fee.
The report is filed server-side against the externaltransactions resource of the Google Play Developer API. Once your system has collected the money, your backend posts to createexternaltransaction with the token in the request body. Which wrapper you use depends on what was sold: a one-time product goes inside oneTimeTransaction, while a subscription goes inside recurringTransaction, which additionally states the subscription type.
For subscriptions, hold onto one distinction: the token is required for the first transaction in a recurring purchase, but renewals do not get a fresh token. Report each renewal against the original sale using initialExternalTransactionId. The API also exposes getexternaltransaction to read a transaction back and refundexternaltransaction to report a refund, so the full lifecycle of an alternative sale is mirrored on Google's side.
The resulting service fee varies by transaction type and geography, with the European Economic Area called out specifically; the published rates live in Google's external offers program documentation rather than the Billing Library reference. Architecturally, alternative billing does not remove the fee — it moves the duty to declare each sale onto your backend.
Subscription upgrades and downgrades
When a user who already bought through your billing system upgrades or downgrades, do not show the choice screen again. The original choice is preserved, and you signal it by carrying the prior transaction's identifier into the replacement flow with setOriginalExternalTransactionId() on SubscriptionUpdateParams. Because the choice is preserved, the user moves directly into the new plan through the billing system they already selected.
Two identifiers are in play and they are not interchangeable:
- setOriginalExternalTransactionId() runs on the client and names the prior purchase this upgrade replaces — that is what lets Google skip the choice screen.
- initialExternalTransactionId is a server-side reporting field that chains a subscription's renewals back to its own first transaction.
The new plan is still a new purchase. Once the upgrade or downgrade completes, report it as a new transaction with its own externalTransactionToken, and that transaction becomes the initialExternalTransactionId its later renewals reference.
Designing a fair choice screen
When you render your own screen, the UX guidelines become requirements you accepted by declaring DEVELOPER_RENDERED in Play Console. The principle behind every rule: the user must be able to compare the two options fairly, with nothing tilting them toward your billing system.
- Label who is responsible. Each option must identify the authorized entity, app name or developer name, so the user knows who fulfills the purchase and handles support.
- Keep the marks distinct. Google's Play icon appears in full color on a neutral light or dark background, following Google's brand guidelines; your side shows only your own app icon or brand logo. Borrowing Google's branding for your option is not allowed.
- Pull payment-method logos at render time. The artwork returned by getBillingChoiceInfoAsync() is what represents Google Play's payment methods, and your own methods get the same treatment. Retrieve and display them on every render — no caching, no edits. If your own methods can't be determined, leaving them out is acceptable; Google Play's must still be shown.
- Keep the buttons equal and close. Button sizes, text size, font style, contrast, tap targets and in-button logo sizing should be equivalent, and the two buttons must sit close together for side-by-side comparison.
- Use equivalent calls to action. The two primary button labels must match in weight and wording style, for example "Pay with Google Play" beside "Pay with [your service]." You may offer different deals on each side, but when you do, Google Play's loyalty benefits have to appear on equal footing.
- Give loyalty equal footing. Whenever loyalty information appears, both options get the same treatment, and Google Play's loyalty message is retrieved through getBillingChoiceInfoAsync() on every render with no caching.
- Disclose the redirect. When your option hands the user off to a website, state clearly and prominently that they are leaving the app, using explicit wording such as "You'll be redirected to a web page."
One nuance: the broad visual-equality clause is phrased with "should," while proximity, equivalent calls to action, in-button logo sizing and the no-caching rules use "must." When unsure whether something is mandatory, treat the equality requirements as binding — the program exists to prevent nudging users away from Google Play Billing.
Supervised users and parental controls
Supervised accounts get one step you don't have to implement. During the Billing Choice flow, Google Play itself surfaces the appropriate parental control screen. This applies across all four scenarios, so it appears whether Google renders the choice screen or you do. Because you neither build nor trigger it, plan for the extra screen when you test with a supervised account.
Choosing a scenario for your team
Billing Choice is a trade. Google Play Billing bundled payment processing, tax handling, receipts, refunds, renewals, fraud protection and the reporting pipeline into its fee. Billing Choice lets you take some of that back, but only by taking on the work that came with it. When a user picks your option, you own payment processing, fulfillment, customer support, refunds and the server-side reporting that keeps you compliant. The fee does not vanish; it is assessed from the transactions you report. And Google Play Billing remains a first-class choice for every user, every time, so your alternative has to earn the selection.
A practical way to decide:
- Want less friction without standing up a payment stack? The Google-rendered scenarios (1A and 2A) carry the least integration burden, because Google draws the screen and, in 1A, mints the token.
- Already run billing infrastructure on the web? An external link scenario (2A or 2B) reuses it.
- Want maximum control over the experience? The fully developer-rendered, in-app scenario (1B) demands the most in return: a compliant choice screen, your own payment flow, the disclosure dialog and the reporting backend, all built and maintained by your team.
The question Billing Choice really asks is not whether to use alternative billing, but which scenario your team can build and operate. The token flow, the reporting obligation and the fairness rules are the cost of admission; seeing them clearly up front is what prevents an integration that works in a demo but falls out of compliance in production.
| Scenario | Choice screen | Payment location | How the purchase launches |
|---|---|---|---|
| 1A | Google renders it (GOOGLE_RENDERED) | In app (IN_APP) | launchBillingFlow() with a developer billing option enabled |
| 1B | You render it (DEVELOPER_RENDERED) | In app (IN_APP) | You handle the tap yourself, then process payment and report |
| 2A | Google renders it (GOOGLE_RENDERED) | External link (EXTERNAL_LINK) | launchBillingFlow() with a link URI and token attached |
| 2B | You render it (DEVELOPER_RENDERED) | External link (EXTERNAL_LINK) | launchExternalLink() with a link URI and token attached |
Scenario labels and enum values are fixed; the launch call differs between the 2A and 2B rows.
| Asset specification | Value |
|---|---|
| Overall image size | 192dp x 20dp |
| Single card size | 32dp x 20dp |
| Spacing between cards | 8dp |
| Inner padding | 3dp |
| Card outline | 1dp inner stroke, 2dp radius, color #E0E0E0 |
| Card background | Solid color, preferably white |
| File format | PNG with transparent background |
| Maximum payment methods | 5 |
All values apply together; the five-method cap is a maximum, not a target.
Frequently asked questions
Do I always generate the external transaction token myself?
No. In Scenario 1A, where Google renders the choice screen and payment happens in app, the token arrives through the DeveloperProvidedBillingListener inside a DeveloperProvidedBillingDetails object. In Scenarios 1B, 2A and 2B you generate it with createBillingProgramReportingDetails(). Scenario 2A is the exception to the A-versus-B shorthand: Google renders the screen, but you mint the token before launching because it must travel with the redirect.
Does a successful launchExternalLink() callback mean the purchase succeeded?
No. The callback only confirms the link launched. The purchase happens on your website, outside the app, so completing and recording the sale is your responsibility. Report it to Google with the token once it completes.
Do subscription renewals need a new token?
No. The token is required for the first transaction in a recurring purchase, but renewals are reported against the original sale using initialExternalTransactionId, the identifier of that first transaction. An upgrade or downgrade, by contrast, is a new purchase with its own token, which then becomes the initialExternalTransactionId for its later renewals.
Does alternative billing remove Google's service fee?
No. The fee is assessed from the transactions you report through the externaltransactions API, and it varies by transaction type and geography, with the European Economic Area called out specifically. Published rates live in Google's external offers program documentation rather than the Billing Library reference.
Do I need to build a parental control screen for supervised users?
No. Google Play automatically displays the appropriate parental control screen during the Billing Choice flow for supervised users, in all four scenarios. You neither build nor trigger it, but expect the extra screen when testing with a supervised account.
{
"recurringTransaction": {
"externalTransactionToken": "the_token_from_the_client",
"externalSubscription": { "subscriptionType": "RECURRING" }
}
}