Jak używać
- Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
- W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
- Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.
npx skills add https://github.com/pollyglot/google-play-cli-skills --skill gplay-monetizationPrzed rozpoczęciem
- Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
- Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.
Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.
gplay monetization (subscriptions + one-time products)
gplay subscriptions and gplay iap own the monetization catalog as declarative, version-controlled files (ADR-0041). Shared conventions are in gplay-cli-usage. Both namespaces are [experimental].
| Namespace | What it holds |
|---|---|
subscriptions | subscriptions, their base plans (config + per-territory prices), their offers, lifecycle state |
iap | one-time products, v2 monetization.onetimeproducts ∪ legacy inappproducts |
Both sit outside the Edit lifecycle (no editId): gplay edits begin does not batch them.
The loop
pull → edit the .json files → apply --dry-run → apply [--confirm]One <productId>.json per product, holding the API resource verbatim minus server-derived noise. pull then apply with no edits is a guaranteed no-op. Commit the directory; the diff in review is the catalog change.
Mirror semantics: the trap if you know metadata
metadata apply is additive: a locale live online but absent on disk is left alone. Monetization is the opposite. The directory is the complete declared catalog: a live subscription, product or offer with no file is a delete in the plan.
- `pull` before every `apply`.
applyrefuses an empty directory when
the app has live products, but a partially populated one is a legitimate plan full of deletes.
- `pull` is destructive locally too, and refuses to erase a populated
directory when the live catalog reads back empty (a mis-set --package or a scope loss): that refusal is a signal, not an obstacle to work around.
- Deleting a subscription is additionally guarded server-side: Google refuses
to delete one with a published base plan.
Gates
| Situation | Gate | Exit without it |
|---|---|---|
| Plan contains any delete (product, base plan or offer) | --confirm | 3 |
iap apply cancels a pre-order offer (irreversible) | --confirm | 3 |
iap apply promotes a live legacy product to v2 | --migrate | 3 |
subscriptions prices migrate (reprices live subscribers) | --confirm | 3 |
| Creates, patches, state changes (reversible) | none, they run directly | n/a |
Subscriptions
gplay subscriptions pull # → ./monetization/subscriptions/*.json
# …edit the files…
gplay subscriptions apply --dry-run # ONLINE read, prints the plan, changes nothing
gplay subscriptions apply # creates/patches/state changes
gplay subscriptions apply --confirm # …when the plan also deletes
gplay subscriptions apply --latency-tolerance tolerant # large catalog (iap apply too): up to 24 h to propagate, far higher throughput- Base plans ride the parent patch. Base plan config (billing type,
per-territory regionalConfigs prices) is declared inline under basePlans and patched with the subscription; the API has no create/patch on the sub-resource. Its endpoints only manage state, subscriber price migration, and deletion.
- Only a DRAFT base plan deletes (a published one comes back as
BASE_PLAN_NOT_DRAFT): retire it in two applies, state: INACTIVE first, then drop it from the file.
- Offers are embedded but real.
pullnests each offer under
basePlans[].offers, a file construct the API resource does not carry. apply splits them back out and reconciles them through the offers endpoints under the key productId/basePlanId/offerId.
- `state:` (
ACTIVE/INACTIVE, omit to leave it unmanaged) reconciles
via :activate/:deactivate. DRAFT from anything, or INACTIVE from DRAFT, is a usage error naming the transition.
- Reconciled fields only.
listings,taxAndComplianceSettings,
restrictedPaymentCountries, basePlans. The updateMask is exactly the changed managed fields; nothing outside that projection drifts or diffs. archived is not reconciled (deprecated/output-only upstream).
Prices
# Derive per-region prices from one base price:
gplay subscriptions prices convert --price 4.99 --currency USD --output jsonPaste the returned Money objects into a base plan's regionalConfigs, then apply --dry-run. convert is online (today's rates via convertRegionPrices): it needs a credential and the package axis, and mutates nothing.
# Reprice EXISTING subscribers, money-moving, one base plan per call:
gplay subscriptions prices migrate \
--product premium --base-plan monthly \
--regions FR,DE \
--oldest 2026-01-01T00:00:00Z \
--price-increase-type opt-in \
--dry-run # offline preview, unlike apply --dry-run
gplay subscriptions prices migrate … --confirmThis is the one deliberate exception to "editing files never touches a live purchaser." apply changes what new buyers pay; migrate changes what existing subscribers pay. An apply diff never triggers a migration.
One-time products (iap)
gplay iap pull # v2 ∪ legacy → ./monetization/iap/*.json
gplay iap apply --dry-run
gplay iap apply [--confirm] [--migrate]pull unions the v2 and legacy surfaces by product ID, and a file's origin is its shape; no gplay-invented marker:
| Field present | Model |
|---|---|
sku | legacy inappproducts |
productId | v2 onetimeproducts |
When Google has retired the legacy API for the app, pull and apply read v2 only and print a stderr NOTE saying so. apply then refuses (exit 2) while --dir still holds a legacy (sku) file: run iap pull to rewrite it as v2, after committing or setting aside local edits, since pull mirrors the live catalog.
Purchase options and offers carry `state` too, same stance as subscriptions; CANCELLED (pre-order offer) is the one-way case gated in the table above. INACTIVE_PUBLISHED is Play's own state for an option it migrated: off sale, still exposed to the Billing Library. Declaring INACTIVE over it is refused (exit 2, no write): keep INACTIVE_PUBLISHED (what pull writes) or omit state:, and never activate it to get past the refusal, that puts it back on sale.
Legacy is inert: gplay never creates, edits or deletes a legacy product, the only gesture is the one-way promotion to v2 (rewrite the file with productId and apply with --migrate; rehearse with --dry-run first). When a legacy file is involved (an unexpected refusal, or the question of why pull reads two surfaces), read iap-legacy.md.
CI gate
gplay subscriptions apply --dry-run --output json # the plan, a gplay-owned shape
gplay iap apply --dry-run --output jsonapply --output json emits the plan, not an API echo: {package, dryRun, changes[], summary{…}, requires[]}, where each change carries op (create/patch/delete/activate/deactivate, plus migrate and cancel on iap) and its identity.
A drift check is one line, fail the job when the plan is non-empty:
gplay subscriptions apply --dry-run --output json | jq -e '.changes | length == 0'Permissions
No permission alias maps to monetization, so the 403 hint (exit 11) names no capability: grant the service account Monetization setup on the app in Play Console (Users & permissions), then retry.