Terminal
Terminal/Skill
Walks through Play Console setup for Google Play billing: products, service account API access, and Pub/Sub notifications, before writing billing code.
By RevenueCat
Works with
npx skills add revenuecat/play-billing-skills --skill setupUse this skill when any of the following is true:
Outcome: a verified environment with a Play Developer account, a linked Payments profile, an internal test track build, at least one active product, a service account with the right Play Console roles, and a Pub/Sub topic receiving Real Time Developer Notifications.
Gather facts before changing anything. Ask or check:
google-play-developer-notifications@system.gserviceaccount.com been granted Publisher on it?If any answer is "unknown," treat it as a discovery task before executing Phase 3.
Work top down. Each step unblocks the next, so do not skip ahead.
Stop and re-plan if Payments verification, identity verification, or the GCP link is incomplete. Later steps will silently fail otherwise.
play.google.com/console. Choose individual or organization; organization unlocks managed publishing and team roles.Add the Play Billing Library to the app module build.gradle.kts:
dependencies {
val billingVersion = "9.0.0"
implementation(
"com.android.billingclient:billing-ktx:$billingVersion"
)
}
If the project uses a version catalog, define the version in libs.versions.toml:
[versions]
billing = "9.0.0"
[libraries]
billing-ktx = {
module = "com.android.billingclient:billing-ktx",
version.ref = "billing"
}
Pin the version explicitly. PBL 9 requires minSdk 23, targets compileSdk/targetSdk 35, and depends on androidx.core 1.9 or later; an up to date Google Play Store app must be on the test device. Confirm google() and mavenCentral() are present in settings.gradle.kts.
Upload to the internal test track:
Internal releases publish in minutes with no review. Use closed testing (up to 200 email lists) or open testing for broader audiences later.
Create a one time product:
remove_ads. The ID is permanent and cannot be reused once activated.Use a <category>_<descriptor> naming scheme (premium_monthly, coins_500, remove_ads). Keep IDs lowercase with underscores. Do not encode prices or promotions in the ID.
For subscriptions, create a Subscription, then add Base Plans and Offers inside it. A consistent scheme such as premium_monthly (subscription), standard (base plan), and intro_7d_free (offer) stays readable during later debugging.
Newly activated products can take a few minutes to propagate. If queryProductDetails returns empty immediately after activation, wait and retry.
Create the service account in GCP, then grant Play Console roles separately.
play-billing-backend).Grant only the roles the backend needs. Play Console permissions are separate from GCP IAM.
| Play Console role | Purpose | Grant when |
|---|---|---|
| View financial data | Read revenue reports and financial information | Backend reads reporting data |
| Manage orders and subscriptions | Verify purchases, acknowledge transactions, revoke subscriptions, issue refunds | Backend validates purchases or manages subscriptions |
| Admin (all permissions) | Full account control | Avoid unless a specific task requires it |
Use separate service accounts for separate purposes (for example, purchase verification versus analytics). Rotate keys periodically; up to 10 keys per service account are allowed so you can deploy a new key before deleting the old. For Cloud Run, GKE, or App Engine, prefer workload identity federation over downloaded key files.
Test API access with a read call such as listing in app products:
// Server side Kotlin using google-api-services
val transport = GoogleNetHttpTransport.newTrustedTransport()
val credential = GoogleCredentials
.fromStream(FileInputStream("service-account.json"))
.createScoped(
"https://www.googleapis.com/auth/androidpublisher"
)
val publisher = AndroidPublisher.Builder(
transport,
GsonFactory.getDefaultInstance(),
HttpCredentialsAdapter(credential)
).setApplicationName("your-app").build()
Create the topic:
play-billing-notifications).Grant Google publish access:
google-play-developer-notifications@system.gserviceaccount.com.Create a subscription. Pick the delivery model that matches your infrastructure.
| Subscription type | How it delivers | Choose when |
|---|---|---|
| Push | Pub/Sub sends HTTP POST with a base64 JSON payload; endpoint must return 2xx | You have a public HTTPS endpoint and want the simplest path |
| Pull | Your server calls the Pub/Sub API to fetch and acknowledge messages | Server sits behind a firewall, batches work, or needs concurrency control |
Configure a dead letter topic. Pub/Sub retries failed messages indefinitely by default. Set a maximum delivery attempt count (allowed between 5 and 100) so undeliverable messages land on the dead letter topic rather than looping. Monitor the dead letter topic; messages there are events your system did not process.
Each RTDN message payload looks like:
// Decoded Pub/Sub message payload
{
"version": "1.0",
"packageName": "com.example.app",
"eventTimeMillis": "1234567890123",
"subscriptionNotification": {
"version": "1.0",
"notificationType": 4,
"purchaseToken": "abc123...",
"subscriptionId": "premium_monthly"
}
}
Enable RTDN in the Play Console:
projects/your-project-id/topics/play-billing-notifications.Send a test notification and walk the environment checklist.
testNotification field instead of subscriptionNotification or oneTimeProductNotification. The handler should acknowledge it without treating it as a real event.If the test never arrives, check each link in the chain:
| Symptom | Likely cause | Fix |
|---|---|---|
| "This version of the app is not configured for billing through Google Play" | App not on a test track, version code mismatch, or wrong signing key | Install the exact signed build uploaded to the Play Console |
queryProductDetails returns empty | Product not Active, wrong ID or type, or propagation delay | Activate the product; verify ID and INAPP vs SUBS; wait a few minutes |
| 403 from Google Play Developer API | Missing Play Console role or GCP project not linked | Link GCP in Setup > API access; grant roles in Play Console, not only GCP IAM |
| RTDN test never arrives | Wrong topic name, missing Publisher role, unreachable push endpoint | Match full topic name; grant Publisher to google-play-developer-notifications@system.gserviceaccount.com; verify HTTPS endpoint returns 200 |
| "The developer account associated with this app is not eligible for testing" | Testing with the developer account itself | Use a different Google account and add it under Setup > License testing |
| Gradle fails to resolve billing library | Missing repositories or proxy block | Add google() and mavenCentral() in settings.gradle.kts; configure proxy if needed |
Final environment checklist:
When every item is checked, the environment is ready for the billing code that follows in later chapters.