The Google Play subscription lifecycle, mapped to entitlements
Chapters on what happens to a subscription after the first purchase — failed renewals, plan changes, refunds — and what Tierux writes to the entitlement each time. Examples follow Google Play, the deepest-coverage path. Apple App Store support is implemented with limitations — see the platform support matrix for per-feature status.
A subscription spends most of its life renewing quietly. The interesting moments are the exceptions: a card that declines, a subscriber who switches plans, a purchase that gets refunded. Each one changes what your app should unlock, and Google Play reports each one in its own way.
This guide picks up where the entitlement state machine chapter of the verification guide leaves off. That chapter introduces the six stored states; this guide walks the transitions between them, one lifecycle event at a time, with the notification types, the access decision, and the timeline event Tierux records for each.
Chapter 1: How Google Play reports subscription state
The two inputs — a fresh subscription query and a real-time notification — and the table that maps each Play state and notification type to a Tierux status.
Chapter 2: Grace period, account hold, and billing retry
A failed renewal from first decline to recovery or expiry: when access stays on, when it turns off, and which events reach your webhook.
Chapter 3: Plan changes and linked purchase tokens
Upgrades and downgrades issue a new token. How the old entitlement is retired, why a deferred downgrade waits, and how late events on the old token are ignored.
Chapter 4: Refunds, revocation, and voided purchases
What a revoke or a voided purchase does to access, how partial refunds are treated, and how a dashboard revoke differs from a store refund.
Server-side verification guide
The companion guide: from purchase token to entitlement, including the six states this guide moves between.
Paywalls and win-back guide
What happens on the cancellation branch of the lifecycle: the save sheet armed by a Play cancellation notification.
Glossary: Grace period
The short definition of the window where a failed renewal still has access.
Glossary: linkedPurchaseToken
The Play field that ties a plan change back to the purchase it replaced.
Platform support matrix
Per-feature, per-platform status for Google Play and Apple App Store.
Lifecycle state without the polling
Free tier — unlimited apps, 1 paywall. No credit card, no revenue share.
Start free