Google Play Subscription Lifecycle: States, Recovery, and Backend Rules
An Android subscription is not a single on/off switch. It moves through purchase, renewal, payment recovery, pause, cancellation, expiration, restore, resubscribe, plan change, and revocation. Each transition changes what the user may access and what your backend must record. This guide maps those states and the actions that belong with each one.
The lifecycle at a glance
A subscription starts with a purchase, becomes active, and then either renews, runs into payment trouble, is canceled, or expires. Google Play adds intermediate recovery states so a failed charge does not immediately remove access. The practical rule is that the app should render access from a trusted state, while the backend should own the authoritative record of that state.
Use this decision table as a working map. It is a reader aid built from the lifecycle rules described in this guide, not a replacement for Google Play's current documentation.
New purchases and the acknowledgment deadline
A new subscription purchase produces a SUBSCRIPTION_PURCHASED notification and enters SUBSCRIPTION_STATE_ACTIVE. The purchase response also carries an acknowledgment state, an auto-renew flag, and an expiry time for the current period.
The acknowledgment window is where many implementations break. Google Play requires acknowledgment of a subscription purchase within three days of the transaction. If that window passes without acknowledgment, the user is refunded automatically and the subscription is revoked. Acknowledgment is your confirmation that access has been granted, and it protects the user when a charge succeeds on Google's side but the app fails to register it.
Renewals are different: only the initial purchase needs acknowledgment. A successful renewal keeps the subscription active and moves the expiry time forward.
Reading the purchase response
When you query a new subscription through the purchases.subscriptionsv2.get endpoint, the response tells you the current state, whether acknowledgment is still pending, whether auto-renew is on, and when the current period ends. The table below preserves the field values for a fresh purchase.
Linking a purchase to your user account
Google Play's ExternalAccountIdentifiers let you attach your own user and profile identifiers to the billing flow. Those identifiers come back in the purchase response and in Real-Time Developer Notifications, which is what lets your backend attribute a purchase correctly during upgrades, downgrades, and resubscriptions. Without that link, a new purchase token can look like a stranger to your system.
Renewals and renewal-date behavior
For auto-renewing plans, Google Play charges the payment method when the billing period ends. A successful charge triggers SUBSCRIPTION_RENEWED, the state stays active, and the expiry time is updated. Your backend should refresh its stored expiry time when that notification arrives.
Renewal dates follow their own rules. A subscription started on the 29th, 30th, or 31st renews on day 28 when the next month is shorter, or day 29 in a leap year. Once a renewal moves earlier, it stays on that earlier date. A subscription starting March 31 renews April 30, then May 30, June 30, and so on. If you analyze renewal patterns, account for this shift or your reports will misread the calendar.
Grace periods: keeping access while payment is retried
A failed renewal charge does not suspend the subscription immediately. Google Play opens a grace period, a recovery window in which the user keeps full access while the payment is retried. The state becomes SUBSCRIPTION_STATE_IN_GRACE_PERIOD, but auto-renew stays true because the user has not canceled; the problem is the payment method.
Grace periods are enabled by default in the Play Console and are configured per subscription. The available lengths depend on the billing period.
Handling grace period in the app
During grace, the app should keep the subscribed features available and prompt the user to fix the payment method. Google's In-App Messaging API can show a standardized payment-update dialog for the SUBSCRIPTION_GRACE_PERIOD category. A NO_ACTION_NEEDED response can mean the user has already resolved the payment issue.
There is also a silent grace period. Even with a zero-day grace period configured, Google Play provides at least one day of silent retry time. During that window the subscription still looks like SUBSCRIPTION_STATE_ACTIVE rather than IN_GRACE_PERIOD, so a payment problem can surface later than expected. After 24 hours the subscription moves to one of several outcomes: renewed if the retry worked, on hold if account hold is enabled, canceled if the user canceled, or expired if no recovery mechanism is enabled.
Account hold: access suspended pending payment
If grace ends without a successful payment, the subscription enters account hold. This is a harder failure: the user loses access to subscribed content. Account hold is enabled by default and lasts 60 days minus the grace period length, so a seven-day grace period leaves 53 days of hold.
While on hold, the state is SUBSCRIPTION_STATE_ON_HOLD, the expiry time is set to a past timestamp, queryPurchasesAsync() does not return the subscription, and premium features should be locked. Because the client query will not surface the subscription, the app needs to ask your backend or the Google Play Developer API for the hold state.
Users can still cancel, restore, or resubscribe while on hold. If they fix the payment method, a SUBSCRIPTION_RECOVERED notification arrives and the subscription returns to active with the same purchase token. That is a recovery, not a new purchase.
The billing date reset after recovery
Recovery from account hold resets the billing date to the recovery date. A subscription that originally renewed on the 15th of each month, recovered on the 22nd, will renew on the 22nd going forward. The same reset applies when a user manually resumes a paused subscription before the pause period ends.
Pausing a subscription
Pausing gives users a temporary break instead of a cancellation. It is enabled by default in the Play Console but is not available for every billing period. Annual subscriptions cannot be paused, a deliberate limitation because a pause could outlast the subscription itself.
The pause lifecycle and access rules
Pausing happens in stages. When the user schedules a pause, SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED arrives, the state remains SUBSCRIPTION_STATE_ACTIVE, and access continues until the current billing period ends. When the pause takes effect, SUBSCRIPTION_PAUSED arrives, the state becomes SUBSCRIPTION_STATE_PAUSED, access stops, and PausedStateContext carries the expected resume date. When the subscription resumes, either automatically at the end of the pause or manually by the user, SUBSCRIPTION_RECOVERED arrives and the state returns to active.
The distinction that trips up implementations is scheduled versus active pause. A pause that is only scheduled leaves entitlement in place; once the pause is in force, entitlement should stop. Your backend also needs to handle a user canceling a scheduled pause, and your app should offer a way to resume early.
Cancellation and the remaining access period
Cancellation does not cut access immediately. The user keeps access until the end of the paid billing period. The state becomes SUBSCRIPTION_STATE_CANCELED, and the expiry time marks when access will end. The app should show the cancellation status rather than revoke entitlement at the moment of cancellation.
The canceledStateContext field explains why the subscription ended. It can record a voluntary user cancellation with a survey response, a developer cancellation through the API, a replacement caused by an upgrade or downgrade, a payment failure after all recovery mechanisms were exhausted, or a Google cancellation for policy violations. That reason data is useful for churn analysis and retention work.
Expiration: when access must end
When the expiry time passes for a canceled subscription, or when account hold ends without recovery, the subscription expires. A SUBSCRIPTION_EXPIRED notification arrives and the state becomes SUBSCRIPTION_STATE_EXPIRED. At that point, revoke all entitlements tied to the subscription, mark the purchase token invalid in your database, and optionally offer a win-back promotion.
Restore versus resubscribe
These two return paths are easy to confuse, and they behave differently.
Restore happens before expiration. A user who canceled but changed their mind can restore the subscription. It uses the same purchase token, continues as if the cancellation had not happened, and produces a SUBSCRIPTION_RESTARTED notification. No new acknowledgment is needed because the original purchase was already acknowledged.
Resubscribe happens after expiration. It is treated as a new purchase with a new purchase token, produces a SUBSCRIPTION_PURCHASED notification, and must be acknowledged within three days. The response includes out-of-app purchase context with the expired purchase token and expired external account identifiers, which lets you link the new subscription back to the existing user account.
Upgrades, downgrades, and the linked purchase token
A plan change creates a new subscription and invalidates the old one. The new purchase token comes with a linkedPurchaseToken field pointing at the previous subscription. Your backend should find the user by the old token, move them to the new token, invalidate the old one, and acknowledge the new purchase.
Proration controls how the money moves. The mode you choose affects both the user experience and revenue recognition.
Revocations and refunds
Some subscriptions end abruptly. A SUBSCRIPTION_REVOKED notification arrives when you revoke through the Developer API, when a chargeback occurs, or when Google revokes for policy violations. Revocation is immediate: the subscription jumps straight to SUBSCRIPTION_STATE_EXPIRED and access should be revoked at once. A chargeback should also be logged for fraud detection.
Prepaid subscriptions: a shorter lifecycle
Prepaid plans do not renew automatically. The user buys additional time explicitly. That changes which recovery states exist: prepaid plans have no grace period, no account hold, and no pausing, and they only use the Active, Pending, and Expired states.
Acknowledgment timing is also stricter. Plans of one week or longer must be acknowledged within three days. Plans shorter than a week must be acknowledged within half the plan duration, so a three-day prepaid plan must be acknowledged within one and a half days or the user is refunded.
Backend and app checklist
Use this checklist to test your implementation against the lifecycle rules above.
- Acknowledge every new purchase within three days, and acknowledge resubscriptions and plan changes as new purchases.
- Do not require acknowledgment for renewals or restores.
- Process RTDN notifications and keep an authoritative subscription state on the backend rather than trusting the client alone.
- Store the expiry time and update it on renewal.
- Keep access during grace period and during a scheduled pause; revoke access during account hold and active pause.
- Query the backend or the Google Play Developer API for account hold, because queryPurchasesAsync() will not return a held subscription.
- Expect the billing date to reset after account hold recovery and after an early manual resume from pause.
- Treat restore and resubscribe as different flows with different tokens and acknowledgment rules.
- Use linkedPurchaseToken to move a user from an old plan to a new one.
- Revoke access immediately on SUBSCRIPTION_REVOKED.
- Handle edge cases such as device switches mid-subscription, multiple purchases from one user, refunds and chargebacks, and subscription transfers between accounts.
Summary
The lifecycle is broad, but the states that matter most are clear: active means full access; grace period means access continues while payment is retried; account hold means access is suspended pending a payment fix; paused means the user chose a break; canceled means access lasts until the paid period ends; expired means access is revoked. Whether a failed payment turns into lost revenue or a saved subscriber usually depends on how your grace and hold handling is built. Whether the experience feels confusing or smooth depends on how pause, cancellation, and restore are presented.
| Field | Value for new purchase |
|---|---|
| subscriptionState | SUBSCRIPTION_STATE_ACTIVE |
| acknowledgementState | ACKNOWLEDGEMENT_STATE_PENDING |
| autoRenewEnabled | true |
| expiryTime | Next renewal date |
Values reflect a freshly purchased subscription as described in the source material. Check current Google Play API documentation for any changes.
| Billing period | Available grace period options |
|---|---|
| Weekly | 3, 7 days |
| Monthly | 7, 14, 30 days |
| Annual | 7, 14, 30 days |
Grace periods are enabled by default in the Play Console and configured per subscription. Confirm current options in the Play Console.
| Billing Period | Available Pause Durations |
|---|---|
| Weekly | 1, 2, 3, 4 weeks |
| Monthly | 1, 2, 3 months |
| Three-month | 1, 2, 3 months |
| Six-month | 1, 2, 3 months |
| Annual | Not available |
Pause is enabled by default in the Play Console. Annual subscriptions cannot be paused. Confirm current options in the Play Console.
| Mode | Behavior |
|---|---|
| IMMEDIATE_WITH_TIME_PRORATION | User is credited/charged immediately, billing date unchanged |
| IMMEDIATE_AND_CHARGE_PRORATED_PRICE | User charged prorated amount immediately |
| IMMEDIATE_AND_CHARGE_FULL_PRICE | User charged full new plan price immediately |
| DEFERRED | Change takes effect at next renewal |
The mode you choose affects user experience and revenue recognition. Confirm current behavior in Google Play's billing documentation.
| Aspect | Auto-Renewing | Prepaid |
|---|---|---|
| Renewal | Automatic | User-initiated top-up |
| Grace Period | Yes | No |
| Account Hold | Yes | No |
| Pausing | Yes (if enabled) | No |
| States | All states | Only Active, Pending, Expired |
Prepaid plans do not renew automatically and have a shorter set of states. Confirm current behavior in Google Play's billing documentation.
Frequently asked questions
What happens if I don't acknowledge a Google Play subscription purchase?
If a subscription purchase is not acknowledged within three days, the user is automatically refunded and the subscription is revoked. Renewals and restores do not need acknowledgment; only the initial purchase, resubscriptions, and plan changes do.
Why does a subscription still look active after a failed payment?
Google Play provides at least one day of silent grace period for payment retries, even if you configure a zero-day grace period. During that window the subscription appears as SUBSCRIPTION_STATE_ACTIVE rather than IN_GRACE_PERIOD. After 24 hours it moves to renewed, on hold, canceled, or expired depending on the outcome.
How long does account hold last?
Account hold lasts 60 days minus the grace period length. With a seven-day grace period, that is 53 days. During hold the user loses access, the expiry time is set to a past timestamp, and queryPurchasesAsync() does not return the subscription.
What is the difference between restore and resubscribe?
Restore happens before expiration and keeps the same purchase token, continuing the subscription as if it had not been canceled. Resubscribe happens after expiration and is treated as a new purchase with a new purchase token that must be acknowledged within three days.
How quickly must I acknowledge a prepaid subscription?
Plans of one week or longer must be acknowledged within three days. Plans shorter than a week must be acknowledged within half the plan duration, so a three-day plan requires acknowledgment within one and a half days or the user is refunded.