Terminal
Terminal/Skill
Guide to structuring Google Play subscriptions into base plans and offers, and mapping a paywall to them.
By RevenueCat
Works with
npx skills add revenuecat/play-billing-skills --skill subscriptionsGoogle Play models every subscription as three nested objects: Subscription, Base Plan, and Offer. The catalog you build in the Play Console must match the catalog your app queries and the paywall your users see. This skill guides you through the hierarchy, helps you pick a catalog shape, and shows how to query and launch the right offer with Play Billing Library 9.x.
Confirm the goal before you touch the Play Console or write code. Answer these questions first.
| Question | Why it matters |
|---|---|
| What product are you selling? | One Subscription per logical entitlement (Premium, Cloud Storage, etc). |
| How many billing periods? | Each billing period becomes a separate Base Plan under that Subscription. |
| Do you need trials, intro pricing, upgrade incentives, or win back? | Offers attach to Base Plans. Prepaid Base Plans cannot carry Offers. |
| Who decides who qualifies for an offer? | Google managed eligibility for new customer trials, developer determined for everything else. |
| Do you have add ons? | Each add on is a separate Subscription. Your backend, not Google, enforces the parent relationship. |
Stop here if the answer to "what are we actually selling" is not yes or no clear. Modeling a fuzzy catalog locks you into Product IDs that you cannot rename later.
Inspect the current state before you design the catalog.
Flag any mismatch between what the app currently queries and what the Play Console contains. A common source of bugs is a Base Plan or Offer that exists in code but was never activated in the console.
Decide the catalog shape. These are the decisions you must make before creating anything in the Play Console.
One Subscription per distinct entitlement. If Premium and Cloud Storage unlock different features, they are two Subscriptions. If Premium Monthly and Premium Yearly unlock the same features, they are one Subscription with two Base Plans.
Add one Base Plan per billing period or plan type you want to sell under that Subscription.
| Plan type | Use when | Offers allowed |
|---|---|---|
| Auto renewing | Standard recurring subscription. Google charges at each period end until cancellation. | Yes |
| Prepaid | User pays upfront for a fixed window. No auto renew, no grace period, no account hold. | No |
| Installment | User commits to N monthly payments, then rolls to month to month. Brazil, France, Italy, Spain only. | Yes |
A Subscription with a monthly auto renewing plan and a yearly auto renewing plan is the typical paywall shape. Add a prepaid plan if your market needs it. Add an installment plan only if you ship to a supported market.
Offers attach to a single Base Plan. Each Offer has an ordered list of pricing phases. You can stack up to two pricing phases before the full Base Plan price takes over.
| Pattern | Phase 1 | Phase 2 | Eligibility |
|---|---|---|---|
| Free trial | Free for N days | (skip) | New customer acquisition (Google managed) |
| Intro price | Discounted for N periods | (skip) | New customer acquisition or developer determined |
| Trial then intro | Free for N days | Discounted for N periods | New customer acquisition |
| Loyalty discount | Discounted for N periods | (skip) | Developer determined (tagged) |
| Win back | Discounted for N periods | (skip) | Configured as win back in console |
Pick Google managed eligibility for new customer trials. Pick developer determined eligibility when your backend decides (loyalty, cohorts, cross product, custom win back logic). Tag developer determined offers so your app can filter on offerTags.
Before leaving this phase you should be able to fill in this table for every product.
| Subscription Product ID | Base Plan ID | Plan type | Offer ID | Eligibility | Pricing phases |
|---|---|---|---|---|---|
| premium | monthly | auto renewing | free-trial | New customer | 7 days free |
| premium | monthly | auto renewing | intro-3mo | New customer | 2.99 for 3 months |
| premium | yearly | auto renewing | (none) | n/a | full price |
| premium | prepaid-monthly | prepaid | (none) | n/a | full price |
If a row is unclear, go back to Phase 1 and clarify before creating the product.
Query product details once per Subscription you want to show.
val params = QueryProductDetailsParams.newBuilder()
.setProductList(
listOf(
QueryProductDetailsParams.Product.newBuilder()
.setProductId("premium")
.setProductType(ProductType.SUBS)
.build()
)
)
.build()
val result = billingClient.queryProductDetails(params)
val details = result.productDetailsList?.firstOrNull()
Read the offer list. Every Base Plan without an Offer still produces one SubscriptionOfferDetails entry (the full price entry).
val offerDetails = details
?.subscriptionOfferDetails
?: emptyList()
offerDetails.forEach { offer ->
val basePlanId = offer.basePlanId
val offerId = offer.offerId
val tags = offer.offerTags
val phases = offer.pricingPhases.pricingPhaseList
}
Filter by developer determined eligibility tags returned from your backend.
val eligible = offerDetails.filter { offer ->
val tags = offer.offerTags
tags.isEmpty() || tags.any { it in userEligibleTags }
}
Detect a prepaid plan by checking that every pricing phase is non recurring.
val isPrepaid = offer.pricingPhases.pricingPhaseList
.all { it.recurrenceMode == RecurrenceMode.NON_RECURRING }
Detect an installment plan by reading installmentPlanDetails.
val installment = offer.installmentPlanDetails
val commitmentCount = installment?.commitmentPaymentsCount
val renewalCount = installment?.subsequentCommitmentPaymentsCount
Launch the billing flow with the selected offer token. Every purchase requires a token, including Base Plans without Offers.
val productParams = BillingFlowParams.ProductDetailsParams.newBuilder()
.setProductDetails(details)
.setOfferToken(chosenOffer.offerToken)
.build()
val flowParams = BillingFlowParams.newBuilder()
.setProductDetailsParamsList(listOf(productParams))
.build()
billingClient.launchBillingFlow(activity, flowParams)
Prove the catalog and the code agree before you ship.
queryProductDetails on a signed build and log every SubscriptionOfferDetails entry. Check that basePlanId and offerId values match your table.offerToken. Missing tokens cause the billing flow to fail.Play Billing Library 9.x ProductDetails, SubscriptionOfferDetails, BillingFlowParams.ProductDetailsParams.
Play Console: Monetize, Products, Subscriptions.