Retention offers help you reduce voluntary churn by showing a discount to subscribers at the moment they try to cancel their subscription in Google Play.
When an eligible subscriber starts to cancel, Google Play shows them a retention offer that you configured, such as "Keep your subscription and get 50% off for the next 2 months." If the subscriber accepts the offer, their subscription isn't canceled. The discounted price starts on their next billing date.
This page explains how retention offers work, how to configure them, how to handle the resulting events in your backend, and how to test them.
Before you begin
Before you set up retention offers, make sure that you have done the following:
- Created a subscription with at least one auto-renewing base plan. Retention offers can only be added to auto-renewing base plans.
- Configured Real-time developer notifications (RTDN) and set up your
backend to call the
purchases.subscriptionsv2.getmethod. Your backend uses these to detect when a subscriber accepts a retention offer.
Because Google Play shows retention offers outside your app, you don't need to change your app or update your Google Play Billing Library integration to use them. All of the integration work happens in Google Play Console and your backend.
How retention offers work
Retention offers appear only in Google Play subscription management: the Google
Play Store app and Google Play on the web. They don't appear inside your app.
The Google Play Billing Library doesn't return retention offers in
queryProductDetailsAsync() results, so they aren't included in
ProductDetails.getSubscriptionOfferDetails(), and you can't sell them through
launchBillingFlow(). If your app uses deep links to send subscribers to
the Google Play subscriptions center or to a specific subscription so that they
can manage or cancel it, those subscribers can see your retention offer when
they start to cancel there.
The following steps describe what happens when a subscriber tries to cancel:
- The subscriber opens their subscription in Google Play and starts to cancel it.
Google Play checks whether the subscriber is eligible for one of your retention offers, based on the eligibility rules that you set for the offer, or on whether you targeted the offer to that subscriber.
If the subscriber is eligible, Google Play may show the retention offer as an alternative to canceling. Meeting your eligibility criteria doesn't guarantee that the offer appears, because Google Play also performs additional platform-level checks, such as regional compliance requirements. If Google Play shows the offer, the subscriber can do one of the following:
- Accept the offer: The subscriber accepts with a single tap. The subscription stays active and auto-renewing. The subscriber isn't charged right away; the discounted price applies starting with the next billing period.
- Continue canceling: The subscriber declines the offer and completes
the standard cancellation flow. You receive the usual
SUBSCRIPTION_CANCELEDnotification. For details, see Cancellations.
If the subscriber leaves the cancellation flow without accepting the offer or canceling, their subscription doesn't change. This applies to both the Google Play Store app and Google Play on the web. Viewing a retention offer without accepting it doesn't count toward the offer's claim limit or start the wait period between offers. Google Play checks the claim limit when it shows the offer and again when the subscriber accepts it. An accepted offer counts toward the claim limit when the subscription renews at the discounted price. The wait period between offers starts when the discount period of the previous retention offer on the same base plan ends. The subscriber might see the offer again the next time they try to cancel, provided they're still eligible.
Scheduled plan transition
When a subscriber accepts a retention offer, Google Play models it as a
scheduled plan transition on the subscriber's existing purchase. This differs
from a deferred replacement, which requires a new purchase flow and creates
a new purchase token. With a retention offer, the subscriber keeps the same
purchaseToken, and only the future billing terms change.
When the subscriber accepts the offer, Google Play does the following:
- Sends a
SUBSCRIPTION_PLAN_TRANSITION_UPDATED(21) RTDN to your backend. - Adds a
planTransitionDetailsobject to theautoRenewingPlanfield of the affected line item in theSubscriptionPurchaseV2resource.
For details on handling these events, see Handle retention offer events in your backend.
Eligibility requirements
A subscription can receive a retention offer at any time before its next renewal, as long as all of the following are true:
- The subscription is active and auto-renewing. Subscriptions in a grace period, on account hold, or paused can't receive retention offers.
- The subscription is a single subscription. Retention offers aren't supported for subscriptions with add-ons.
- The subscription doesn't use an installment base plan. Installment base plans aren't eligible for retention offers.
- The next payment is at the regular recurring base plan price. If the subscriber is in a free trial or introductory price phase, the offer is available only during the final billing period of that phase, when the upcoming renewal is at the regular price.
- The subscriber isn't in a discounted billing period of a previously accepted retention offer. A subscriber who is in the discounted phase of a retention offer can't claim another retention offer until the subscription renews at the regular base plan price.
- The subscription has no pending scheduled plan transition. A subscription
can have at most one pending scheduled plan transition, which is a
planTransitionDetailsobject in theIN_PROGRESSstate. For example, a subscriber who already accepted a retention offer that hasn't taken effect yet can't receive another one. - The subscription has no unconfirmed price change.
- The retention offer's discounted price is less than or equal to the subscriber's next base plan renewal price.
- The subscriber meets the eligibility rules that you configured for the
offer. For a per-user retention offer, you activated targeting for the
subscription with the
activateOfferTargetingmethod.
Configure retention offers
You can create retention offers in Google Play Console or by using the Google Play Developer API. Each retention offer uses one of the following targeting modes:
- Rule-based targeting: Google Play decides which subscribers are eligible, based on eligibility rules that you set, such as a minimum paid subscription duration.
- Per-user targeting: Your backend decides which subscribers can see the offer by targeting it to specific subscriptions.
A base plan can have more than one active retention offer in the same country or region. When a subscriber is eligible for more than one offer, Google Play shows at most one retention offer in the cancellation flow. Google Play chooses the offer in the following order:
- Targeting mode: A per-user targeted offer (
retentionPerUserRule) always takes precedence over a rule-based offer (retentionRule), even if the rule-based offer has a higher discount percentage. - Discount percentage: Among eligible offers that use the same targeting mode, Google Play shows the offer with the highest displayed discount percentage.
- Discounted price: If offers have the same discount percentage, Google Play shows the offer with the lowest discounted price.
- Offer ID: If offers are still tied, Google Play shows the offer whose
offerIdcomes last in alphabetical order.
Create a retention offer in Play Console
To create a retention offer in Google Play Console, do the following:
- Go to Monetize with Play > Products > Subscriptions.
- Select a subscription, and then select the base plan that you want to add the offer to.
- Add an offer for Existing subscribers trying to cancel.
- Choose either Cohort-level retention offer or User-level retention offer.
Create a retention offer with the Play Developer API
You can also create and update retention offers programmatically. To create an
offer, call the monetization.subscriptions.basePlans.offers.create
method. To update existing offers, call the
monetization.subscriptions.basePlans.offers.patch or
monetization.subscriptions.basePlans.offers.batchUpdate method. All
three methods support the retentionRule, retentionPerUserRule, startTime,
and endTime fields. In the SubscriptionOffer object, set the following
fields:
offerId: Your unique retention offer ID.targeting: SetretentionRuleto aRetentionTargetingRuleobject that defines who is eligible for the offer. For the available fields, see Set retention eligibility rules. To choose eligible subscribers from your backend instead, setretentionPerUserRule. For details, see Target retention offers to specific subscribers.phases[]: A retention offer supports only a single pricing phase. In that phase, set the following fields:recurrenceCount: The number of billing periods that the discount lasts, from 1 to 52. IfrecurrenceCountis greater than 1, the phasedurationmust equal the billing period of the base plan.regionalConfigs[]: SetrelativeDiscountto the discount as a fraction greater than 0 and less than 1. For example, use0.5for 50% off. Retention offers support onlyrelativeDiscount. Fixed-price (price), absolute discount (absoluteDiscount), and free (free) phases aren't supported.
startTime: Optional. The time when the retention offer becomes available to eligible subscribers, as an RFC 3339 timestamp. Setting this field doesn't activate the offer. If you don't set this field, the offer becomes available based on its state.endTime: Optional. The time when the retention offer stops being available, as an RFC 3339 timestamp, regardless of the offer's state. If you don't set this field, the offer has no end date. If you set this field, it must be in the future and later thanstartTime.
The monetization.subscriptions.basePlans.offers.create method always creates
the offer in the DRAFT state, even if you set startTime. To make the offer
active, call the monetization.subscriptions.basePlans.offers.activate
method.
Set retention eligibility rules
The RetentionTargetingRule object contains the following fields:
scope: Required. The subscriptions that the rule considers. For retention offers, the only supported value isthisSubscription, the subscription in which the offer is defined. Set this field to{"thisSubscription": {}}.minDuration: Required. The minimum time that a user must have been a paid subscriber to be eligible, as an ISO 8601 duration in days, fromP0DtoP1826D. For example, useP90Dfor 90 days. To not require a minimum paid subscription time, set this field toP0D.allowMultipleClaims: Optional. Whether a subscriber can claim the offer more than once. Iffalse, a subscriber who has ever claimed this offer is never eligible for it again. Iftrue, a subscriber can become eligible again after the time inminOfferCooldownDurationhas passed since the end of the previous retention offer's discount period. Defaults tofalse.minOfferCooldownDuration: Required ifallowMultipleClaimsistrue. The minimum time that must pass after the previous retention offer's discount period ends before the subscriber is eligible again, as an ISO 8601 duration in days, fromP1DtoP1826D. For example, useP180Dfor 180 days. Don't set this field ifallowMultipleClaimsisfalseor not set.
The following example shows the startTime, endTime, and targeting fields
of a SubscriptionOffer object for a retention offer that's available to
subscribers who have paid for at least 90 days, and that they can claim again
180 days after their previous retention discount ends:
{
"offerId": "retention-50off-2m",
"startTime": "2026-12-01T00:00:00Z",
"endTime": "2027-03-01T00:00:00Z",
"targeting": {
"retentionRule": {
"scope": {
"thisSubscription": {}
},
"minDuration": "P90D",
"allowMultipleClaims": true,
"minOfferCooldownDuration": "P180D"
}
}
}
Target retention offers to specific subscribers
Instead of letting Google Play decide eligibility with a
RetentionTargetingRule, you can make a retention offer available only to the
subscribers that your backend chooses. For example, you might target an offer to
subscribers that your churn-prediction model flags as at risk, or to subscribers
who start a cancellation journey in your app.
Subscribers see a per-user retention offer in the same Google Play cancellation flow as any other retention offer, and you handle acceptance the same way. For details, see Handle retention offer events in your backend.
To target retention offers to specific subscribers, do the following:
Create a per-user retention offer. When you call the
monetization.subscriptions.basePlans.offers.create,monetization.subscriptions.basePlans.offers.patch, ormonetization.subscriptions.basePlans.offers.batchUpdatemethod, settargetingto aretentionPerUserRuleobject instead of aretentionRuleobject. TheRetentionPerUserTargetingRuleobject has no fields. An offer can use eitherretentionRuleorretentionPerUserRule, but not both.{ "offerId": "retention-peruser-30off", "targeting": { "retentionPerUserRule": {} } }Activate the offer before you target it to subscribers. If you call the
activateOfferTargetingmethod for an offer that has never been activated, the call fails with an HTTP400 Bad Requeststatus code and anINVALID_ARGUMENTerror status. For details, see Handle targeting errors. Even when the offer is active, Google Play shows it only to subscribers whose subscriptions you target in the next step.Target the offer to a subscription. Call the
purchases.subscriptionsv2.activateOfferTargetingmethod with your app's package name, the subscription'spurchaseToken, and theofferIdof the per-user retention offer:POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/subscriptionsv2/tokens/{purchaseToken}:activateOfferTargeting { "offerId": "retention-peruser-30off" }A successful call returns an HTTP
204 No Contentstatus code with no response body. Google Play stores the targeting with the subscription, so you don't need to call the API at the moment the subscriber cancels. The next time the subscriber starts to cancel in Google Play, Google Play can show the offer, as long as the subscription meets the eligibility requirements. Per-user targeting replaces only the eligibility rules that aretentionRuledefines. All other eligibility requirements, and the platform-level checks that Google Play performs, such as regional compliance requirements, still apply.You can target more than one per-user retention offer to the same subscription. To do so, call the
activateOfferTargetingmethod once for each offer. Google Play still shows at most one retention offer in the cancellation flow. For details about how Google Play chooses the offer, see Configure retention offers.The
activateOfferTargetingmethod is idempotent. If you call it for an offer that's already targeted to the subscription, the call succeeds and Google Play updates the offer'sactivateTimeto the time of the latest request.Remove the targeting when needed. If you no longer want a subscriber to receive the offer, for example because their churn risk changed, call the
purchases.subscriptionsv2.deactivateOfferTargetingmethod with the same package name,purchaseToken, andofferId. A successful call returns an HTTP204 No Contentstatus code with no response body.The
deactivateOfferTargetingmethod is also idempotent. If the offer isn't targeted to the subscription, for example because you never activated the targeting, the call succeeds and has no effect.
Targeting applies to a single purchaseToken and doesn't expire while the
subscription is active and auto-renewing. It stays in place after the subscriber
sees, accepts, or declines the offer. Google Play removes it only when you call
the deactivateOfferTargeting method, or 60 days after the subscription
expires. If a plan change or resubscription creates a new purchaseToken, the
targeting doesn't carry over.
To check which per-user retention offers are targeted to a subscription, call
the purchases.subscriptionsv2.get method. The developerTargetedOffers
field of each line item lists the targeted offers. Each entry contains the
offerId and the activateTime when you activated the targeting:
{
"lineItems": [
{
"productId": "premium_monthly_sub",
"developerTargetedOffers": [
{
"offerId": "retention-peruser-30off",
"activateTime": "2026-12-03T15:04:05Z"
}
]
}
]
}
Handle targeting errors
When a call to the activateOfferTargeting or deactivateOfferTargeting
method fails, the response contains an HTTP status code and an error status
that describes the cause. The following table lists the HTTP status codes and
error statuses that these methods can return:
| HTTP status code | Error status | Methods | Cause |
|---|---|---|---|
404 Not Found |
NOT_FOUND |
Both | The purchaseToken doesn't exist. |
400 Bad Request |
INVALID_ARGUMENT |
activateOfferTargeting |
The offerId doesn't exist on the subscription's current
base plan, or the offer is still in the draft state and has never been
activated. |
400 Bad Request |
FAILED_PRECONDITION |
activateOfferTargeting |
The offer's targeting isn't set to
retentionPerUserRule. |
400 Bad Request |
FAILED_PRECONDITION |
activateOfferTargeting |
The subscription has already expired. |
The activateOfferTargeting method doesn't check whether a non-expired
subscription is eligible for the offer. For example, if the subscription is
canceled but hasn't expired yet, the call succeeds and Google Play stores the
targeting. Google Play
evaluates the subscription's eligibility when the subscriber enters the
cancellation flow.
Handle retention offer events in your backend
When a subscriber accepts a retention offer, and later when the discounted
renewal happens, Google Play sends RTDNs to your backend. After you receive each
notification, call the purchases.subscriptionsv2.get method with the
purchaseToken from the notification to get the latest subscription state.
Accepting a retention offer doesn't create a new purchase. The purchaseToken
stays the same, so you don't need to acknowledge the purchase again, and Google
Play doesn't generate a linkedPurchaseToken. Keep the subscriber's existing
entitlement in place. Process the discounted renewal order the same way as any
other subscription renewal.
| Notification type | When it's sent | What to do |
|---|---|---|
SUBSCRIPTION_PLAN_TRANSITION_UPDATED (21) |
When a subscriber accepts a retention offer in the cancellation flow. | Call the purchases.subscriptionsv2.get method and check
planTransitionDetails. The transitionState is
IN_PROGRESS. The subscription remains active and
auto-renewing, so continue to grant access. |
SUBSCRIPTION_RENEWED (2) |
When the current billing period ends and the subscription renews at the discounted retention offer price. | Call the purchases.subscriptionsv2.get method, confirm
that offerDetails.offerId is the retention offer ID and that
planTransitionDetails is no longer present, and extend the
subscriber's access to the new expiryTime. |
The planTransitionDetails object contains the following fields:
productId: The product ID of the plan that the subscription transitions to. For a retention offer, this is the same product.basePlanId: The base plan ID of the plan that the subscription transitions to.offerId: The ID of the retention offer that the subscriber accepted. Use this field to identify which retention offer was redeemed.transitionInfo.transitionState: The state of the transition. For retention offers, the state isIN_PROGRESSwhile the transition is pending.transitionInfo.expectedTransitionTime: When the retention offer terms are expected to take effect.
Google Play includes planTransitionDetails only while the transition is
pending. When the subscription renews at the discounted retention offer price,
the transition completes and Google Play removes planTransitionDetails from
the purchases.subscriptionsv2.get response. From then on, the line item
itself shows the active retention discount:
offerDetails.offerIdis the ID of the accepted retention offer.offerPhaseis{"introductoryPrice": {}}during the discounted billing periods. After the discounted billing periods end and the subscription renews at the regular base plan price,offerPhasechanges to{"basePrice": {}}.
Response after the subscriber accepts the offer
After the subscriber accepts the retention offer, the current billing period
continues unchanged. The planTransitionDetails object shows the scheduled
transition with a transitionState of IN_PROGRESS:
{
"lineItems": [
{
"productId": "premium_monthly_sub",
"expiryTime": "2026-12-15T10:00:00Z",
"offerDetails": {
"basePlanId": "monthly-base"
},
"autoRenewingPlan": {
"autoRenewEnabled": true,
"planTransitionDetails": {
"productId": "premium_monthly_sub",
"basePlanId": "monthly-base",
"offerId": "retention-50off-2m",
"transitionInfo": {
"transitionState": "IN_PROGRESS",
"expectedTransitionTime": "2026-12-15T10:00:00Z"
}
}
}
}
]
}
Response after the discounted renewal
After the renewal date passes and the subscriber is charged the discounted
price, offerDetails.offerId shows the retention offer, offerPhase shows
introductoryPrice, and the response no longer includes
planTransitionDetails:
{
"lineItems": [
{
"productId": "premium_monthly_sub",
"expiryTime": "2027-01-15T10:00:00Z",
"offerDetails": {
"basePlanId": "monthly-base",
"offerId": "retention-50off-2m"
},
"offerPhase": {
"introductoryPrice": {}
},
"autoRenewingPlan": {
"autoRenewEnabled": true,
"recurringPrice": {
"currencyCode": "USD",
"units": "9",
"nanos": 990000000
}
}
}
]
}
Lifecycle interactions
Keep the following behaviors in mind when you handle retention offers:
- End of the discount: After the discounted billing periods end, the
subscription automatically renews at the regular base plan price. You
receive a
SUBSCRIPTION_RENEWEDnotification, as with any other renewal, and the line item'sofferPhasechanges to{"basePrice": {}}. The subscriber doesn't need to take any action. - Payment recovery after the discount: If the renewal at the regular base plan price after the discount ends is declined and the subscription enters a grace period or account hold, payment recovery charges the regular base plan price. Google Play doesn't apply the completed retention offer discount. If the payment for the first discounted renewal is declined, the pending transition is preserved, and the retention offer price applies when the payment recovers.
- Deferred billing: If you call the
purchases.subscriptionsv2.defermethod while a retention offer transition isIN_PROGRESS, the pending transition is preserved and applies at the deferred renewal. To get the new renewal date, check the line item'sexpiryTime. - Plan change before the transition: A retention offer applies only to the
purchaseTokenof the subscription where the subscriber accepted it. If the subscriber switches to a different base plan or subscription before theexpectedTransitionTime, Google Play generates a new purchase token, cancels the scheduled transition, and clearsplanTransitionDetails. The pending retention offer doesn't apply to the new plan. - Cancellation and restore: If a subscriber cancels the subscription after
accepting a retention offer, the scheduled transition remains pending and
transitionStatestaysIN_PROGRESS. If the subscriber restores the subscription before it expires, the retention offer discount still applies at renewal. - Expiration and resubscription: If the subscription expires without being restored, Google Play cancels the pending transition. If the user resubscribes or signs up again later, Google Play creates a new subscription purchase, and the previously accepted retention offer doesn't apply.
- Offer changes: If you change the discount or billing periods of a retention offer, the change applies only to future redemptions. Subscribers who already accepted the offer keep the original terms.
- Offer deactivation: If you deactivate a retention offer, or the offer
reaches its end date, subscribers who already accepted it keep the terms
they agreed to. Subscribers with an
IN_PROGRESStransition still receive the discount at their next renewal, and subscribers who are already in the discounted billing periods keep the discount for the full agreed duration. - Price changes: Base plan price changes still apply. Google Play migrates a subscriber to a new price only when the subscriber is paying the regular price and has no pending retention offer transition. For more information, see Change subscription prices.
- Refunds: You can refund a subscriber with the standard refund and revoke
APIs, such as the
purchases.subscriptionsv2.revokemethod. This refunds the most recent payment and ends the subscriber's access.
Test retention offers
Google Play shows only active retention offers in the cancellation flow, and it evaluates eligibility rules in real calendar time. To test retention offers with a license tester account, use one of the following methods:
- Test a per-user retention offer on a production base plan, without showing the offer to real subscribers.
- Test a rule-based retention offer in a test app or on a test base plan that production users can't access.
Before you use either method, go to Settings > License testing in Google Play Console and add the test Google Account as a license tester.
Test a per-user retention offer
Google Play shows a per-user retention offer only to the subscriptions that you target, so you can test it on a production base plan without exposing it to real subscribers. To test a per-user retention offer, do the following:
- Create a per-user retention offer under the base plan, and then activate
it. In Google Play Console, choose User-level retention offer.
With the Google Play Developer API, set
targetingto aretentionPerUserRuleobject. For details, see Target retention offers to specific subscribers. - If you just activated the offer, wait 10 to 15 minutes for the change to propagate, and then clear the Google Play Store app cache.
- On the test device, sign in with the license tester account, and then purchase the base plan in your app.
- From your backend, call the
purchases.subscriptionsv2.activateOfferTargetingmethod with your app's package name, the license tester'spurchaseToken, and theofferIdof the retention offer. - In the Google Play Store app, go to Payments & subscriptions > Subscriptions, select the subscription, and tap Cancel subscription. The retention offer appears in the cancellation flow.
- Accept the offer, and then confirm that your backend receives the
SUBSCRIPTION_PLAN_TRANSITION_UPDATEDRTDN and handles the discounted renewal.
Test a rule-based retention offer
After you activate a rule-based retention offer, Google Play can show it to any eligible subscriber on the base plan. To avoid exposing the offer to production users, test it in a non-production test app or on a dedicated test base plan that production users can't access. To test a rule-based retention offer, do the following:
- In your test app or on your test base plan, create a rule-based retention
offer, and set
minDurationtoP0D(0 days). In Google Play Console, choose Cohort-level retention offer. With the Google Play Developer API, settargetingto aretentionRuleobject. For details, see Set retention eligibility rules. - Activate the offer, wait 10 to 15 minutes for the change to propagate, and then clear the Google Play Store app cache.
- On the test device, sign in with the license tester account, and then purchase the test base plan.
- In the Google Play Store app, go to Payments & subscriptions > Subscriptions, select the subscription, and tap Cancel subscription. Because the offer doesn't require a minimum paid subscription duration, you can start the cancellation flow right after the purchase. The retention offer appears in the cancellation flow.
- Accept the offer, and then confirm that your backend receives the
SUBSCRIPTION_PLAN_TRANSITION_UPDATEDRTDN and handles the discounted renewal.
After you verify the integration, create and activate the rule-based retention offer on your production base plan.
Troubleshoot retention offer testing
If the retention offer doesn't appear, check the following:
- The retention offer is active, and the current time is between its
startTimeandendTime, if you set them. - For a per-user retention offer, the
developerTargetedOffersfield in thepurchases.subscriptionsv2.getresponse for the license tester'spurchaseTokenincludes the offer. - The subscription is a single subscription, not a subscription with add-ons.
- The subscription isn't in a grace period, on account hold, or paused.
- The subscription has no pending plan change or price change.
- The next renewal is at the regular base plan price. For free trials and introductory offers, the retention offer is available only during the final billing period of the trial or introductory phase.
- You waited 10 to 15 minutes after you activated or changed the offer, and you cleared the Play Store app cache.