Build a custom Android paywall and control plan changes
A custom Android purchase flow involves two separate choices: who draws the paywall and who completes the Google Play transaction. Keeping those choices separate makes it easier to add sign-in checks, analytics, restore handling, and deliberate proration without replacing the entire purchase system.
Separate interface ownership from transaction ownership
Start by deciding which parts remain managed for you. With your own interface and managed completion, fetch an offering, render its packages, and start the purchase through the Android SDK. With a managed paywall and managed completion, keep the dashboard-designed interface while observing purchase, restore, cancellation, and web-checkout events. With a managed paywall and your own completion, supply custom purchase logic and accept responsibility for acknowledging transactions. Writing your own billing calls and synchronizing purchases afterward is a migration pattern, not merely a paywall customization.
Read offerings and prices defensively
Fetch offerings before rendering packages. The current offering can be absent, so handle that state instead of assuming a dashboard configuration exists. Standard package types have nullable convenience accessors, while lookup by a custom identifier can throw when the identifier is missing. For display, use the localized formatted price. Use micros and currency code only when calculation is required. A subscription period is present for Google subscriptions but absent for one-time products and Amazon products.
Use returned offers instead of an eligibility API
Android does not provide the iOS-style eligibility methods. Ineligible offers are simply absent from the returned subscription options. SubscriptionOptions is the collection of offers for a product; each SubscriptionOption contains pricing phases. Collection accessors select a free-trial, introductory, or default offer, while option accessors expose the free, introductory, and full-price phases. A single offer can contain both free and introductory phases. When labeling phases, remember that the payment-mode value can be null outside finite recurring phases, including ordinary full-price recurring phases and prepaid plans.
Choose the purchase form that matches your result handling
The purchase builder accepts a package, a store product, or a specific subscription option. Package and store-product forms use the product default option. That default excludes certain tagged offers, prefers the longest free trial or cheapest first phase, and then falls back to the base plan. Pass a specific option only when the user selected a non-default offer. In callback form, the transaction can be nullable; in the interface form, it is non-null. Cancellation is represented by the same cancelled-purchase error code, so do not present a user dismissal as a purchase failure. Coroutine callers can use the throwing form or a result-returning form, and should log the underlying error message as well as the public error description.
Gate access from active entitlements and provide restore
Gate access from the customer information returned by a successful purchase. Use active entitlements, not the complete historical collection. The indexed entitlement lookup also requires an active check. Useful settings-screen details include renewal state, expiration, period type, cancellation time, and billing-issue time; cancellation or billing dates do not by themselves remove access while the entitlement remains active. A customer-info update listener observes cache changes but is not a server push, so fetch current customer information when fresh state is required. Restore is also required so users on a new device can recover access.
Make plan changes explicit
A plan change needs the current subscription identifier and a replacement mode. The identifier should contain only the subscription ID, not the combined subscription and base-plan form. Product changes work in the Play Store and Galaxy Store but are ignored by the Amazon Appstore. The current replacement-mode type supersedes the deprecated Google-specific type and setter. Its five modes cover immediate changes with or without proration, immediate full-price charging, time proration, and deferred application at expiration. Omitting the mode selects the no-proration behavior, which can give an upgrading user the better plan immediately without a charge that day.
Match the replacement mode to the business outcome
For a paid upgrade, charge the prorated difference when the new plan costs more per unit of time. For a generous upgrade, convert remaining time into free time on the new tier. For a downgrade, defer the change until the paid period ends. For a same-price crossgrade, choose immediate time proration or deferral according to when the change should be felt. Time proration is unsuitable for base-plan changes within one store product in the Play Store. Full-price charging is unsupported in the Galaxy Store and produces an unsupported error. With deferral, the immediate result still describes the old plan, so treat the change as scheduled.
Apply personalized-price and add-on limits
Personalized-price disclosure is a compliance setting, not a way to change the price. Enable it only when the displayed price is actually personalized; Amazon ignores it. Add-ons are limited to Play Store subscriptions, require matching renewal periods, and allow at most 49 add-ons in one purchase. These add-on builder methods remain experimental.
Observe and gate a managed paywall
A managed paywall can be embedded with options for the offering, listener, dismiss button, and custom variables. The embedded form hides the dismiss button by default, unlike dialog and activity forms. Listener methods cover purchase and restore lifecycle events, errors, cancellation, links, and web checkout. Web checkout is not cancellation because the user may still complete payment elsewhere. Initiated purchase and restore hooks can pause the flow for sign-in, confirmation, or another check; resuming proceeds, while declining aborts before the store sheet appears. Use the paywall-specific resumable type, not the similarly named customer-center type.
Handle full-screen results and custom variables
For a full-screen managed paywall, construct the activity launcher during activity creation and handle purchased, restored, error, and cancelled results. Cancellation is mapped to its own result rather than delivered as a generic purchase error. Listener and purchase-logic attachments are held in memory; if the process dies while the paywall is open, those attachments can be lost and the activity can return cancelled even though the user did not decline. Custom variables support string, number, and boolean values. Invalid keys are dropped with a warning in the standard options path, while the dialog options path does not validate them.
Own the transaction only with an acknowledgement plan
When your code completes the transaction, configure the SDK accordingly and provide purchase logic. The purchase method receives the activity and parameters containing the package, selected option, old product, and replacement mode. Restore normally synchronizes purchases already known to the store. Results distinguish success, cancellation, and error; always pass error details for an error result because an empty error result produces neither a dialog nor tracking. Narrow the replacement mode to the current store type before passing it to the purchase builder. Several managed-completion listener callbacks do not fire in this mode, so move completion analytics and unlocking into your own success path. Most importantly, your code must acknowledge purchases within three days or Google Play can refund the user automatically.
Choose an approach and run a final checklist
Use a custom interface when design control matters most. Use an embedded managed paywall when the dashboard design should remain but lifecycle hooks are needed. Use the activity launcher when the paywall should be its own screen and return a result. Use custom purchase logic only when your billing implementation must complete the store transaction. Before shipping, verify the current offering, active-entitlement gating, restore, cancellation messaging, replacement mode, deferred-change handling, and purchase acknowledgement.
| Approach | Best fit | Key responsibility |
|---|---|---|
| Custom UI with managed completion | Full design control | Render offerings and handle purchase results |
| Managed paywall with managed completion | Dashboard design plus lifecycle hooks | Observe events and gate initiated actions |
| Managed paywall with custom completion | Existing billing implementation | Complete and acknowledge the store transaction |
| Custom billing with synchronization | Migration from another billing stack | Own the complete store transaction |
The fourth pattern, using your own billing calls followed by synchronization, is a migration approach rather than a paywall customization.
| Mode | Timing | Charge today | Typical use |
|---|---|---|---|
| WITHOUT_PRORATION | Immediate | No | Default behavior; rarely ideal for paid upgrades |
| WITH_TIME_PRORATION | Immediate | No | Generous upgrade or same-price crossgrade |
| CHARGE_PRORATED_PRICE | Immediate | Price difference | Paid upgrade |
| CHARGE_FULL_PRICE | Immediate | Full new price | Immediate paid switch where remaining time is credited forward |
| DEFERRED | At old-plan expiration | No | Downgrade or delayed crossgrade |
CHARGE_PRORATED_PRICE requires the new plan to cost more per unit of time. Product changes are ignored by the Amazon Appstore.
Frequently asked questions
How do I check trial or intro-offer eligibility on Android?
There is no Android equivalent of the iOS eligibility check. Google Play only returns offers the user can receive, so render the subscription options returned for the product and inspect their pricing phases.
Which entitlement collection should gate access?
Use the active entitlements collection and confirm the specific entitlement is active. Reading every entitlement ever held can incorrectly grant access after expiration.
Which replacement mode fits an upgrade or downgrade?
Use CHARGE_PRORATED_PRICE for an upgrade where the new plan costs more per unit of time. For a downgrade, DEFERRED normally keeps the current plan until it expires before applying the cheaper plan.
Why does a deferred plan change still show the old plan?
Treat it as scheduled, not completed. The success result can still describe the old plan, so rely on the entitlement expiration and later customer information rather than recording the new product immediately.
What changes when purchases are completed by my app?
Your code must acknowledge the purchase. Failure to acknowledge within three days can lead Google Play to refund the user automatically.