Google Play Billing Integration Guide: Complete Tutorial

Google Play Billing Overview

Google Play Billing is the standard purchase system for eligible digital products in apps distributed through Google Play. Before implementation, confirm the currently supported Billing Library version and the deadline that applies to new releases and updates.

Service Fees

• Program — Identify the fee program in which the developer is actually enrolled
• Product — Separate paid apps, one-time products, subscriptions, and any eligible program
• Market — Record country, taxes, alternative-billing eligibility, and user-choice obligations
• Forecast — Use the current official fee schedule instead of a universal split

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:VERSION"

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 — Configure eligible offers and enforce the current account and user rules
• Introductory pricing — Discounted price for first N billing periods
• Grace period — Configure the supported duration and define entitlement behavior while payment is recovered
• 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

For valuable entitlements, do not rely on client-side purchase state alone. Verify and reconcile purchases on a trusted backend:

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 — Apply the current Payments policy and any eligible market-specific program
• Physical goods or services — Confirm the applicable policy, disclosures, and payment responsibilities
• 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