Google Play Billing Library 5: Subscription Model and Migration Guide
Google Play Billing Library 5 replaced the old one-SKU-per-configuration approach with a three-level structure: subscriptions, base plans, and offers. That shift touches both the Android client and the backend that tracks purchases. This guide explains the new model, the Library 4 deprecation deadlines, and the concrete call changes you need to plan for. Version-specific details below reflect the captured reference material and should be checked against current Google documentation before you ship.
The new subscription structure
Library 5 nests three concepts. A subscription is the set of benefits a user can access over a period of time — the thing being sold. A base plan is one way to sell that subscription: it fixes the billing period, the renewal type, and the price. An offer is any modification to a base plan's price made available to eligible users, such as a discounted first period or a trial.
Under the old model, each distinct mix of benefits, cadence, and discount had to exist as its own product. Library 5 collapses that: one subscription can carry several base plans, and each base plan can carry several offers. The practical effect is fewer near-duplicate catalog entries and a single place to manage pricing and eligibility.
What the new model enables
The subscription/base-plan/offer structure unlocks several configuration options:
- Prepaid plans that the user must actively extend, which can matter in markets with limits on auto-renewing subscriptions.
- Price-change handling, including whether existing users stay in a legacy price cohort and when their price rises.
- Per-country and per-region availability and pricing, including a setting for newly supported regions.
- Deactivating individual base plans or offers without disabling the parent subscription.
- Tags for grouping and bulk-managing related subscriptions, base plans, and offers.
- Pricing phases that apply a time-based discount and then convert to base pricing.
- Developer-determined offers, where eligibility logic lives in your app and can respond to in-app behavior.
- Mixing Google-determined offers (such as classic free trials) with developer-determined offers on the same product.
How existing subscriptions were converted
Google migrated existing subscriptions automatically. The old product ID became a subscription, with a base plan matching the original billing period. Any free trial or introductory price became an offer. Functionality for the original subscription is preserved.
Because Library 4 and earlier expect a single billing period, price, and optional intro price per subscription, each converted subscription contains one backwards-compatible base plan and offer. You can add more base plans and offers, but apps still on the older API methods will only see the backwards-compatible option. Plan your catalog changes with that split in mind: older app versions keep working against the legacy option while updated versions can use the full set.
Library 4 deprecation deadlines
Google generally supports each Play Billing Library version for at least two years after release. For Library 4, the captured timeline is:
- New apps could no longer use Library 4 from August 2023.
- Updates to existing apps could no longer use Library 4 from November 2023.
These dates are a historical reference point. Check Google's current Play Billing compatibility page before planning a release, because support windows and enforcement dates can change.
Migration checklist: client and backend
Treat the migration as two workstreams that meet in the middle.
Client side:
- Consolidate duplicate products that represent the same benefits with different price or duration configurations.
- Update the Billing Library dependency in your Gradle build.
- Replace SKU-based queries with product-details queries and handle the new offer list.
- Select a specific offer token when launching a subscription purchase.
- Update purchase queries to use product types instead of SKU types.
- Decide on a proration mode for plan changes and test the edge cases.
Backend side:
- If you manage the catalog programmatically, move to the new Monetization endpoints: Monetization.subscriptions for subscription products, Monetization.subscriptions.basePlans for base plans, and Monetization.subscriptions.basePlans.offers for offers. Use these through the SubscriptionPublishing API for anything other than one-time purchases; one-time purchases stay on the inappproducts API.
- Move subscription status reads to the v2 purchases resource.
- Keep the older subscriptions resource for acknowledge, cancel, refund, revoke, and defer operations.
- Capture price data separately, because the v2 resource does not include pricing.
- Update real-time notification handling to work from the purchase token rather than a subscription ID.
A useful rule of thumb: if a call returns product or offer information, it is client-side and changed in Library 5. If a call returns or mutates purchase state, it is backend-side and partly changed.
Updating the dependency
The captured guide pins the billing client at version 5.1.0 in the Gradle dependencies block. Google released 5.1 on October 31, 2022, and the captured guidance recommends using it when implementing Library 5. The exact dependency snippet is preserved in the accompanying code module.
Showing available products
The query path changed from SKUs to products:
- Replace BillingClient.querySkuDetailsAsync() with BillingClient.queryProductDetailsAsync().
- Replace SkuDetailsParams with QueryProductDetailsParams.
Results now arrive as ProductDetails, which carries title, type, and ID, plus a list of subscription offer details. That list contains every base plan and offer available to the user. Unlike Library 4, multiple offers can exist for the same subscription period. Google handles eligibility in some cases; in others your app decides which offers appear on the paywall.
One-time purchase pricing moved into a dedicated one-time purchase offer details object rather than sitting directly on the product details.
EU disclosure requirement: if you show a personalized offer under Article 6(1)(ea) of the Consumer Rights Directive (2011/83/EU) to a user in the EU, you must disclose it through the Play UI by setting the offer-personalized flag to true or false according to what is shown.
Launching the purchase flow
Library 5 lets you choose the specific offer applied to a purchase instead of relying on a default:
- Use ProductDetailsParams in place of SKU details for the billing flow parameters.
- Read the offer ID, base plan ID, and other details from the subscription offer details.
- Pass the selected offer's token into the product details parameters for a subscription, or pass the product details directly for a one-time product.
Worked example: a user on a monthly base plan is eligible for an annual upgrade offer. Your paywall lists the annual base plan and its offers. When the user taps the annual option, you take the offer token from the matching subscription offer details entry and place it in the product details parameters. If the user instead buys a one-time product, no offer token is involved; you pass the product details object.
Processing purchases
Purchase processing is largely unchanged, with one signature difference: queryPurchasesAsync() now takes a query purchases parameters object holding a product type value instead of a SKU type value.
Changing subscriptions and proration modes
Users change plans for many reasons, from switching monthly to annual to moving from a silver to a gold tier. Google provides five proration modes that control how much is charged, when, and when the new plan starts:
- IMMEDIATE_WITH_TIME_PRORATION
- IMMEDIATE_WITHOUT_PRORATION
- IMMEDIATE_AND_CHARGE_PRORATED_PRICE
- IMMEDIATE_AND_CHARGE_FULL_PRICE
- DEFERRED
Failure distinction worth testing: IMMEDIATE_WITH_TIME_PRORATION errors when you try to change between base plans inside the same subscription, but works when moving to a different subscription. The captured guidance notes this behavior was undocumented at the time and might be fixed in a later release. Before relying on it, test the exact upgrade path your users will take.
Managing subscription status through the API
An existing backend that reads subscription status can still handle converted subscriptions created before May 2022 and backwards-compatible offers, but it will not support the new Library 5 features. Full support requires the newer subscription purchases API.
Replace calls to purchases.subscriptions.get with purchases.subscriptionsv2.get. The response is a SubscriptionPurchaseV2 resource with the information needed to manage entitlements under the new model.
Two limitations matter:
- The v2 resource does not include pricing. If you analyze revenue or lifetime value from this API, capture price data through another channel.
- The v2 resource has no methods to acknowledge, cancel, refund, revoke, or defer a subscription. Keep using the older subscriptions resource for those operations.
Real-time notifications
The Pub/Sub payload for real-time purchase notifications no longer includes the subscription ID. Previously that ID was needed to call purchases.subscriptions.get for status. Now you call purchases.subscriptionsv2.get with the purchase token to retrieve subscription status.
Testing
Test subscriptions thoroughly before launching or updating your app. The testing process itself does not differ from Library 4, so the same sandbox and license-tester steps apply. Pay particular attention to offer selection, proration edge cases, and backend price capture, since those are the areas where Library 5 changes behavior.
When a managed billing layer helps
The backend rewrite is the heaviest part of a solo migration: new data structures, a new status resource, price capture, and notification changes all land at once. A managed in-app purchase layer can absorb that work by wrapping the platform billing APIs and normalizing purchase data.
If you use a managed layer, confirm three things before migrating:
- Whether it supports both the backwards-compatible catalog and the full Library 5 catalog, choosing per app version.
- How it captures price data, given that the v2 status resource omits pricing.
- How it selects offers on the paywall, especially when only one offer is eligible.
These are evaluation questions, not endorsements. Verify current capabilities directly with any vendor you consider.
Frequently asked questions
What is the biggest change in Google Play Billing Library 5?
The subscription structure. Instead of one product per combination of benefits, billing period, and discount, you now define a subscription with multiple base plans, and each base plan can carry multiple offers.
Will older app versions still work after I add Library 5 base plans and offers?
Yes, if they rely on the backwards-compatible base plan and offer that Google created during conversion. Apps still using Library 4 or earlier API methods will only see that legacy option, not the new base plans and offers.
Why can't I get subscription prices from the new status API?
The SubscriptionPurchaseV2 resource does not include pricing information. If you need revenue or lifetime value figures, capture the price at purchase time through the client or another backend channel.
Why does IMMEDIATE_WITH_TIME_PRORATION fail on some plan changes?
It errors when changing between base plans within the same subscription, but works when moving to a different subscription. Test your specific upgrade paths, since this behavior may change in later library releases.
Do I need to disclose personalized offers to EU users?
Yes. If you show a personalized offer under Article 6(1)(ea) of the Consumer Rights Directive (2011/83/EU) to a user in the EU, set the offer-personalized flag to true or false in the Play UI according to the offers shown.