Skip to content
AppDues
Log in
Contact salesSign up

Google Play Subscription with Add-ons: A Practical Multi-Item Billing Guide

Google Play's Subscription with Add-ons lets an app sell a base subscription and several optional subscription products in one checkout. Buyers see a combined price and end up with one renewal date; developers get a single purchase to verify and manage. This guide explains how the bundle behaves, which platform limits shape the design, and how to implement it with the Play Billing Library, including the server-side work that keeps entitlements accurate.

What Subscription with Add-ons means

The feature is also described as multi-line subscriptions, because one purchase contains several line items, or as multi-product checkout, because the buyer completes everything in one flow. All three names describe the same capability.

Without it, a base plan and each optional feature are separate purchases. The buyer goes through several checkouts, tracks several renewal dates, and sees several entries in subscription management. With the bundle, the buyer selects a base plan plus any combination of add-ons, pays one combined price, and everything renews together.

Picture a language-learning app. The base plan unlocks the core lesson library. Conversation practice and downloadable offline packs are separate subscription products offered as add-ons. A learner can take the base plan alone, add one extra, or take everything, and still finish in a single checkout with a single renewal date.

How the bundle behaves

Order matters. The first product in the purchase list is the base item; every later product is treated as an add-on. The base item governs the bundle: if it is canceled, the add-ons are canceled with it, and an add-on cannot remain active on its own.

Google Play aligns renewal dates automatically. Adding an add-on to a running subscription triggers a prorated charge so the new item lines up with the base item's renewal date. After that initial adjustment, the whole bundle renews on one date. Removing an add-on keeps access until the current billing period ends, then stops renewal for that item.

Constraints to check before you design

These limits decide whether the bundle fits your product at all. Work through them before writing billing code.

  • Billing periods must match across every item. A monthly base cannot carry annual add-ons, and an annual base cannot carry monthly add-ons. If you want both monthly and annual choices, create separate base plans for each period.
  • Only auto-renewing subscriptions qualify. Prepaid subscriptions cannot serve as the base item or as add-ons.
  • A single purchase can contain at most 50 items. Most apps will never approach this, but highly modular catalogs should account for it.
  • Regional availability is limited. India and South Korea did not support the feature at the time of the referenced documentation, so those users need an alternative purchase path.
  • Pause and resume are unavailable for subscriptions that include add-ons. If pausing is central to your retention design, weigh that loss against the benefit of bundling.

Three ways to structure the offer

Modular features. Let buyers assemble a plan from a solid base plus optional extras. A design tool, for instance, might include core editing in the base plan and offer an asset library, a brand kit, and version history as separate add-ons. Buyers pay for the capabilities they actually use, which can improve conversion. The failure mode is a base plan that feels hollowed out on purpose; buyers read that as a squeeze, not as choice.

Gradual upgrade path. Start everyone on the base plan and introduce add-ons as usage grows or at natural moments in the journey. A fitness app could offer coaching, meal plans, and wearable sync as add-ons once a member is training regularly. Because buying an add-on leaves existing features in place, the upgrade feels additive rather than like a forced tier change. Recommendations based on actual behavior make this stronger.

Bundle and save. Price combinations so that buying several add-ons together costs less than buying them separately. The source illustrates the arithmetic with a $9.99/month base and three add-ons at $4.99/month each: separately $14.97/month, bundled at $11.99/month. That figure is an illustrative example, not a recommended price. The bundle still earns more than a single add-on purchase and raises average revenue per user.

Whichever structure you choose, keep the menu small. Three to five add-ons is a workable range; beyond that, decision paralysis can kill the purchase. Describe each add-on clearly, say who it suits, and consider recommended bundles or a select-all option.

Console setup and product queries

Existing subscription products can be sold as add-ons without special configuration. There is no separate add-on product type: any auto-renewing subscription can act as the base item or as an add-on. What you must get right is billing-period alignment, since every item in a bundle shares one period.

Play Billing Library v5 or higher is required; use the latest version (v8 at time of writing) for full feature and security coverage.

The first client step is fetching product details with queryProductDetailsAsync for every subscription product you intend to offer. The returned ProductDetails objects carry pricing, base plans, offers, and the offer tokens needed later. The complete client code for this step is supplied as a protected module and should be used exactly as provided.

Launching and processing a multi-item purchase

Build a list of ProductDetailsParams, one per selected item, and put the base subscription first. Each entry needs a valid offer token from ProductDetails.subscriptionOfferDetails(). Product IDs must be unique within the list; duplicates are rejected.

After checkout, the purchase callback receives a Purchase whose products property lists every product ID in the bundle. Verify with your backend before granting anything, then grant entitlements for each product and acknowledge the purchase if it is not already acknowledged.

To change an existing bundle, include the current purchase token and a replacement mode, and list every item that should remain active. Omitting an existing add-on removes it. CHARGE_PRORATED_PRICE aligns new items with the base renewal date; CHARGE_FULL_PRICE and WITHOUT_PRORATION are alternatives depending on the transition you want.

Server verification and real-time notifications

Production apps must verify purchases on a backend and process Real-Time Developer Notifications so entitlement records stay in step with Google Play.

One detail matters specifically for bundles: RTDN messages for multi-item purchases do not include subscriptionId, because several subscriptions are involved. Use the purchaseToken from the notification to call the Google Play Developer API, then read the lineItems field. Each entry carries a product ID, expiry time, and auto-renewing plan status, so you can track each component independently.

Edge cases: bundle-wide versus item-level

The distinction that matters most is which events hit the whole bundle and which hit a single item.

  • Grace periods and account holds are bundle-wide. A failed renewal puts every item into recovery together. The grace period length comes from the item with the shortest grace period setting among active items.
  • Refunds and revocation are item-level. The Developer API can revoke one item without touching the rest, which suits a buyer who wants a refund on a single add-on but keeps the base plan.
  • Price changes follow single-item rules with extra coordination. All pending opt-in increases must land on the same renewal time at the new price. If one item has an unconfirmed opt-in increase, new increases on other items may be ignored unless they align.

When a billing platform handles the complexity

Building directly on the Play Billing Library means owning the billing client lifecycle, query caching, purchase verification, entitlement management, real-time notifications, and every edge case above. A subscription platform can absorb that work, but the right choice depends on what your team actually needs and can maintain over time. Rather than assuming a platform is the answer, treat this as a build-versus-buy evaluation: teams that need full control can stay on the native library; teams optimizing for speed and cross-platform consistency can assess a managed platform against their own requirements, budget, and support expectations. A useful way to decide is to list the operational tasks you would otherwise own — connection retries, receipt validation, entitlement mapping across platforms, webhook handling, and analytics — then ask which of those you have the capacity to build and run reliably, and which you would rather delegate to a vendor whose current terms you have verified directly.

Pre-build checklist

  1. Confirm every item you plan to bundle is an auto-renewing subscription.
  2. Confirm all items share one billing period; split base plans if you need monthly and annual variants.
  3. Confirm the feature is available in your target regions, and design a fallback for India and South Korea.
  4. Decide whether losing pause/resume is acceptable for this product.
  5. Keep the add-on menu to roughly three to five options with clear descriptions.
  6. Make sure the base plan stands on its own.
  7. Plan backend verification and RTDN handling before launch, including the lineItems lookup.
  8. Decide how bundle-wide grace periods and item-level refunds will be reflected in your entitlement store.

Frequently asked questions

Does the order of products in the purchase list matter?

Yes. The first product becomes the base item and all later products are add-ons. Canceling the base cancels the add-ons, and add-ons cannot exist without it.

Can I mix monthly and annual items in one bundle?

No. Every item must share the same billing period. If you want to offer both monthly and annual options, create separate base plans for each period.

What happens when a user removes an add-on?

Access continues until the end of the current billing period, and the item does not renew. If you modify a bundle, any existing add-on left out of the product list is removed.

Why is subscriptionId missing from some RTDN messages?

Multi-item purchases involve several subscriptions, so the field is not provided. Use the purchaseToken to query the Developer API and read lineItems for each product's status.

Can a single add-on be refunded without canceling the base plan?

Yes. Refunds and revocation can be handled at the item level through the Google Play Developer API, leaving the rest of the bundle intact.