Phase 0: Intent Message
Reporting Action: Before proceeding, immediately tell the user: "I will
upgrade Play Billing Library to the latest version."
Phase 1: Discovery & Situational Awareness
- Primary Check (Build Version) : Locate the project's billing dependency (e.g.,
com.android.billingclient:billing) in build.gradle, build.gradle.kts, or libs.versions.toml.
- Initial Compilation Test: Attempt to sync and build the project immediately.
- Fallback Discovery (Effective Version) :
- Trigger: Only if the build fails immediately, scan the source code for deprecated artifacts.
- Logic : The presence of deprecated APIs indicates the "Effective
Version" ---defined as the version where those specific APIs were last
available, not when they were introduced.
- Example : If
SkuDetails is present, treat the baseline as PBL v7 or earlier (regardless of the version string in build.gradle).
- Identify Target & Path : Access the version tool or release notes to find the latest stable version and calculate a [Direct/Stepped] migration path based on the Effective Version baseline.
- Calculate Migration Path :
- If the Effective Version is within 2 major versions of the target: Plan a Direct Migration.
- If it is more than 2 major versions behind: Plan a Stepped
Migration. Migrate by two major versions at a time (e.g., v4 -> v6 -> v8) until you are within two versions of the target.
- Reporting Action: Before proceeding, tell the user: "I've detected you are effectively on PBL [Current] and the latest is [Target]. I am planning a [direct/stepped] migration path."
Phase 2: Contextual Document Mapping & Planning
For every major version jump identified in your path, you MUST synthesize
instructions from:
- Migration Guide (where
[X] is the target major version).
- Release Highlights : The "Deprecations" and "Breaking Changes" sections of the relevant Release Notes.
- Developer Documentation: Consult your knowledge of the Google Play Billing documentation regarding the relevant features used in this app (e.g., Subscriptions, One-Time Products).
- Develop the Plan: Identify every specific code change required (API removals, class replacements, logic shifts) and print this out as a checklist.
Phase 3: Instructions for Execution
Reporting Action: For each of the following steps, give a brief explanation of
what you will be doing prior to execution, and a brief summary of what you
accomplished afterwards.
Step 1: SDK & Environment Alignment
- Action : Update
build.gradle to meet SDK requirements (e.g., "PBL 9 requires compileSdk 35").
- Gradle Version: Verify if the new library requires a newer Android Gradle Plugin (AGP) or Kotlin version.
Step 2: Intent-based Refactoring
Analyze the intent of the existing code rather than performing purely textual
string replacement.
- Action : You MUST follow all deprecation instructions and refactor patterns from both the references/migration-logic.md section, the official migration guides, and the general documentation pages identified in Phase 2.
- Verification : Verify you are doing all steps from all documentation and then making sure you follow the specific directions from the checklist in the references.
Step 3: Sequential Verification (Only applicable for Stepped Migrations)
- Upgrade to the first major intermediate version in your path.
- Run
./gradlew assembleDebug to verify no intermediate breaking changes were missed.
- Repeat until you reach the final target version.
Step 4: Final Validation Checklist
- Smart Checklist Verification:
- Open references/version-checklist.md and locate the Smart Version-Specific Checklist.
- Action: For every version between your [Detected Effective Version] and [Detected New Version], verify that every item has been addressed in the code using "Find in Files" or structural analysis.
- Tests : Run all unit and implementation tests (
./gradlew test).
- Clean Build : Verify the project completes a full clean build:
./gradlew clean assembleDebug. Then, run ./gradlew sync and ./gradlew build so that the user can immediately test the new version manually.
Final Report
Explain the "Why" to the developer:
- "I updated your SDK to [Version] because PBL [Version] requires it for [Reason from docs]."
- "I removed your custom
retryConnection() logic because it is now handled natively by the library using enableAutoServiceReconnection()."
- "Successfully upgraded from PBL [Old] to PBL [New] and verified with unit tests. Based on an analysis of features in the latest library and this application's current feature set, I suggest exploring [New Feature] (e.g., Prepaid Plans or Installments) from the latest release because it is now available but not yet implemented."
1---2name: play-billing-library-version-upgrade-23description: Use this skill when upgrading or migrating an Android project from any4 legacy Google Play Billing Library (PBL) version to the latest stable version of5 PBL.6license: Complete terms in LICENSE.txt7metadata:8 source: https://skillmd.com/skills/android/play-billing-library-version-upgrade-29 author: Google LLC10 last-updated: '2026-09-01'11 keywords:12 - android13 - play billing14 - play billing library15 - pbl16 - upgrade17 - migration18 - deprecation19 - google play20---2122## Phase 0: Intent Message2324**Reporting Action**: Before proceeding, immediately tell the user: "I will25upgrade Play Billing Library to the latest version."2627## Phase 1: Discovery \& Situational Awareness28291. **Primary Check (Build Version)** : Locate the project's billing dependency (e.g., `com.android.billingclient:billing`) in `build.gradle`, `build.gradle.kts`, or `libs.versions.toml`.302. **Initial Compilation Test**: Attempt to sync and build the project immediately.313. **Fallback Discovery (Effective Version)** :32 - **Trigger**: Only if the build fails immediately, scan the source code for deprecated artifacts.33 - **Logic** : The presence of deprecated APIs indicates the **"Effective34 Version"** ---defined as the version where those specific APIs were **last35 available**, not when they were introduced.36 - **Example** : If `SkuDetails` is present, treat the baseline as **PBL v7** or earlier (regardless of the version string in `build.gradle`).374. **Identify Target \& Path** : Access the version tool or release notes to find the latest stable version and calculate a \[Direct/Stepped\] migration path based on the **Effective Version** baseline.3839- **Calculate Migration Path** :40 - If the **Effective Version** is within 2 major versions of the target: Plan a **Direct Migration**.41 - If it is more than 2 major versions behind: Plan a **Stepped42 Migration**. Migrate by two major versions at a time (e.g., v4 -\> v6 -\> v8) until you are within two versions of the target.43- **Reporting Action**: Before proceeding, tell the user: "I've detected you are effectively on PBL \[Current\] and the latest is \[Target\]. I am planning a \[direct/stepped\] migration path."4445## Phase 2: Contextual Document Mapping \& Planning4647For every major version jump identified in your path, you **MUST** synthesize48instructions from:4950- **[Migration Guide](https://developer.android.com/google/play/billing/migrate-gpblv%5BX%5D)** (where `[X]` is the target major version).51- **Release Highlights** : The "Deprecations" and "Breaking Changes" sections of the relevant [Release Notes](references/android/google/play/billing/release-notes.md).52- **Developer Documentation**: Consult your knowledge of the Google Play Billing documentation regarding the relevant features used in this app (e.g., Subscriptions, One-Time Products).53- **Develop the Plan**: Identify every specific code change required (API removals, class replacements, logic shifts) and print this out as a checklist.5455## Phase 3: Instructions for Execution5657*Reporting Action: For each of the following steps, give a brief explanation of58what you will be doing prior to execution, and a brief summary of what you59accomplished afterwards.*6061### Step 1: SDK \& Environment Alignment6263- **Action** : Update `build.gradle` to meet SDK requirements (e.g., "PBL 9 requires `compileSdk` 35").64- **Gradle Version**: Verify if the new library requires a newer Android Gradle Plugin (AGP) or Kotlin version.6566### Step 2: Intent-based Refactoring6768Analyze the intent of the existing code rather than performing purely textual69string replacement.7071- **Action** : You **MUST** follow all deprecation instructions and refactor patterns from **both** the [references/migration-logic.md](references/migration-logic.md) section, the official migration guides, and the general documentation pages identified in Phase 2.72- **Verification** : Verify you are doing **all steps from all documentation** and then making sure you follow the specific directions from the checklist in the references.7374### Step 3: Sequential Verification (Only applicable for Stepped Migrations)75761. **Upgrade** to the first major intermediate version in your path.772. **Run `./gradlew assembleDebug`** to verify no intermediate breaking changes were missed.783. **Repeat** until you reach the final target version.7980### Step 4: Final Validation Checklist81821. **Smart Checklist Verification**:832. Open [references/version-checklist.md](references/version-checklist.md) and locate the **Smart Version-Specific Checklist**.843. **Action**: For every version between your \[Detected Effective Version\] and \[Detected New Version\], verify that every item has been addressed in the code using "Find in Files" or structural analysis.854. **Tests** : Run all unit and implementation tests (`./gradlew test`).865. **Clean Build** : Verify the project completes a full clean build: `./gradlew clean assembleDebug`. Then, run `./gradlew sync` and `./gradlew build` so that the user can immediately test the new version manually.8788## Final Report8990Explain the "Why" to the developer:9192- "I updated your SDK to \[Version\] because PBL \[Version\] requires it for \[Reason from docs\]."93- "I removed your custom `retryConnection()` logic because it is now handled natively by the library using `enableAutoServiceReconnection()`."94- "Successfully upgraded from PBL \[Old\] to PBL \[New\] and verified with unit tests. Based on an analysis of features in the latest library and this application's current feature set, I suggest exploring \[New Feature\] (e.g., Prepaid Plans or Installments) from the latest release because it is now available but not yet implemented."