Google Play Billing Integration Guide: Complete Tutorial

Google Play Billing Overview

Google Play Billing Library is the required payment system for digital goods and services sold within Android apps distributed on Google Play. As of 2026, you must use Play Billing Library 7.x for all new integrations.

Revenue Share

• Standard — 70/30 split (developer keeps 70%)
• Small business — 85/15 split for developers earning under $1M/year
• Subscriptions — 85/15 after the first year of each subscriber
• Media & games — Reduced rates available for qualifying content

Initial Setup

1. Play Console Configuration

1. Open Google Play Console → Your app → Monetize → Products
2. Set up a merchant account if you have not already (linked to Google Payments)
3. Create your in-app products or subscriptions (more details below)

2. Project Dependencies

Add the Billing Library to your app-level build.gradle:

implementation "com.android.billingclient:billing-ktx:7.x.x"

The -ktx artifact includes Kotlin extensions with coroutine support, which simplifies async billing operations significantly.

3. BillingClient Initialization

Create a BillingClient instance in your Application class or ViewModel. The client manages the connection to Google Play and handles all purchase flows.

Product Types

Google Play Billing supports three product types:

One-Time Products (INAPP)

• Consumable — Can be purchased multiple times (coins, lives, credits). Must be consumed after purchase
• Non-consumable — Purchased once, permanent unlock (premium features, ad-free, themes)

Subscriptions (SUBS)

• Auto-renewing subscriptions with configurable billing periods
• Support for free trials, introductory pricing, grace periods
• Multiple base plans and offers per subscription
• Prepaid subscriptions (pay upfront for a fixed period)

Implementing One-Time Purchases

Step 1: Query Products

Use queryProductDetailsAsync() to retrieve product information (price, description, currency) from Google Play. Always query fresh data — do not hardcode prices in your app.

Step 2: Launch Purchase Flow

Call launchBillingFlow() with the product details. This opens Google Play's native purchase dialog. The user confirms payment using their Google account payment method.

Step 3: Handle Purchase Result

The PurchasesUpdatedListener receives the result. Check purchase.purchaseState for PURCHASED, PENDING, or UNSPECIFIED states.

Step 4: Acknowledge or Consume

Non-consumable purchases must be acknowledged within 3 days using acknowledgePurchase(). Consumable purchases must be consumed using consumePurchase() before the user can buy again.

Implementing Subscriptions

Subscription Architecture (Billing 7.x)

The modern subscription model uses a hierarchy: Product → Base Plans → Offers. A single subscription product (e.g., "Premium") can have multiple base plans (monthly, annual) and offers (free trial, discount).

Key Features

• Free trials — 3, 7, 14, or 30-day trials. Only one trial per user per product
• Introductory pricing — Discounted price for first N billing periods
• Grace period — 3, 7, 14, or 30 days. User retains access while payment issue is resolved
• Account hold — After grace period, subscription pauses. User loses access but can reactivate
• Upgrade/downgrade — Proration modes for switching between plans

Lifecycle Management

Use Real-Time Developer Notifications (RTDN) to receive push notifications about subscription state changes (renewal, cancellation, pause, hold, revoke). This is essential for keeping your server in sync with actual subscription states.

Server-Side Verification

Never trust client-side purchase verification alone. Always verify purchases on your server:

1. Client sends purchase token to your backend
2. Backend calls Google Play Developer API to verify the token
3. API returns purchase details including order ID, purchase state, and expiry
4. Backend grants entitlement only after successful verification

Google Play Developer API

Use the purchases.products.get endpoint for one-time purchases and purchases.subscriptionsv2.get for subscriptions. Authenticate using a service account with appropriate Play Console permissions.

Testing Purchases

License Testers

Add test email addresses in Play Console → Settings → License testing. These accounts can make purchases for free using test payment methods.

Testing Checklist

• Successful purchase flow (product query → purchase → acknowledgment)
• Purchase restoration (reinstall, new device)
• Subscription renewal (accelerated time for testing)
• Subscription cancellation and grace period
• Network failure during purchase
• Pending transactions (slow payment methods)
• Server-side verification with test tokens

Policy Compliance

• Digital goods — Must use Google Play Billing (no alternative payment for digital content)
• Physical goods — Can use any payment processor (Stripe, PayPal, etc.)
• Transparency — Clearly display prices before purchase. No hidden fees or misleading pricing
• Subscription info — Show subscription terms, renewal price, and cancellation instructions
• Refund access — Provide a way for users to request refunds or contact support
• Price anchoring — Strike-through pricing must reflect genuine previous prices

Monetization Best Practices

1. Offer value before paywall — Let users experience your app before asking for money
2. A/B test pricing — Use Play Console experiments to find optimal price points
3. Implement restore purchases — Required for a good user experience and Play Store compliance
4. Handle edge cases — Network failures, pending purchases, multi-device sync
5. Monitor metrics — Conversion rate, ARPU, churn rate, LTV
6. Localized pricing — Use Google's suggested prices for each country
7. Win-back offers — Target churned subscribers with re-subscription discounts