Retain subscribers with retention offers

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:

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:

  1. The subscriber opens their subscription in Google Play and starts to cancel it.
  2. 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.

  3. 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_CANCELED notification. 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 planTransitionDetails object to the autoRenewingPlan field of the affected line item in the SubscriptionPurchaseV2 resource.

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 planTransitionDetails object in the IN_PROGRESS state. 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 activateOfferTargeting method.

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:

  1. 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.
  2. Discount percentage: Among eligible offers that use the same targeting mode, Google Play shows the offer with the highest displayed discount percentage.
  3. Discounted price: If offers have the same discount percentage, Google Play shows the offer with the lowest discounted price.
  4. Offer ID: If offers are still tied, Google Play shows the offer whose offerId comes last in alphabetical order.

Create a retention offer in Play Console

To create a retention offer in Google Play Console, do the following:

  1. Go to Monetize with Play > Products > Subscriptions.
  2. Select a subscription, and then select the base plan that you want to add the offer to.
  3. Add an offer for Existing subscribers trying to cancel.
  4. 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: Set retentionRule to a RetentionTargetingRule object 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, set retentionPerUserRule. 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. If recurrenceCount is greater than 1, the phase duration must equal the billing period of the base plan.
    • regionalConfigs[]: Set relativeDiscount to the discount as a fraction greater than 0 and less than 1. For example, use 0.5 for 50% off. Retention offers support only relativeDiscount. 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 than startTime.

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 is thisSubscription, 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, from P0D to P1826D. For example, use P90D for 90 days. To not require a minimum paid subscription time, set this field to P0D.
  • allowMultipleClaims: Optional. Whether a subscriber can claim the offer more than once. If false, a subscriber who has ever claimed this offer is never eligible for it again. If true, a subscriber can become eligible again after the time in minOfferCooldownDuration has passed since the end of the previous retention offer's discount period. Defaults to false.
  • minOfferCooldownDuration: Required if allowMultipleClaims is true. 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, from P1D to P1826D. For example, use P180D for 180 days. Don't set this field if allowMultipleClaims is false or 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:

  1. Create a per-user retention offer. When you call the monetization.subscriptions.basePlans.offers.create, monetization.subscriptions.basePlans.offers.patch, or monetization.subscriptions.basePlans.offers.batchUpdate method, set targeting to a retentionPerUserRule object instead of a retentionRule object. The RetentionPerUserTargetingRule object has no fields. An offer can use either retentionRule or retentionPerUserRule, but not both.

    {
      "offerId": "retention-peruser-30off",
      "targeting": {
        "retentionPerUserRule": {}
      }
    }
    

    Activate the offer before you target it to subscribers. If you call the activateOfferTargeting method for an offer that has never been activated, the call fails with an HTTP 400 Bad Request status code and an INVALID_ARGUMENT error 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.

  2. Target the offer to a subscription. Call the purchases.subscriptionsv2.activateOfferTargeting method with your app's package name, the subscription's purchaseToken, and the offerId of 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 Content status 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 a retentionRule defines. 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 activateOfferTargeting method 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 activateOfferTargeting method 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's activateTime to the time of the latest request.

  3. 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.deactivateOfferTargeting method with the same package name, purchaseToken, and offerId. A successful call returns an HTTP 204 No Content status code with no response body.

    The deactivateOfferTargeting method 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 is IN_PROGRESS while 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.offerId is the ID of the accepted retention offer.
  • offerPhase is {"introductoryPrice": {}} during the discounted billing periods. After the discounted billing periods end and the subscription renews at the regular base plan price, offerPhase changes 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_RENEWED notification, as with any other renewal, and the line item's offerPhase changes 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.defer method while a retention offer transition is IN_PROGRESS, the pending transition is preserved and applies at the deferred renewal. To get the new renewal date, check the line item's expiryTime.
  • Plan change before the transition: A retention offer applies only to the purchaseToken of the subscription where the subscriber accepted it. If the subscriber switches to a different base plan or subscription before the expectedTransitionTime, Google Play generates a new purchase token, cancels the scheduled transition, and clears planTransitionDetails. 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 transitionState stays IN_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_PROGRESS transition 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.revoke method. 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:

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:

  1. 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 targeting to a retentionPerUserRule object. For details, see Target retention offers to specific subscribers.
  2. 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.
  3. On the test device, sign in with the license tester account, and then purchase the base plan in your app.
  4. From your backend, call the purchases.subscriptionsv2.activateOfferTargeting method with your app's package name, the license tester's purchaseToken, and the offerId of the retention offer.
  5. 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.
  6. Accept the offer, and then confirm that your backend receives the SUBSCRIPTION_PLAN_TRANSITION_UPDATED RTDN 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:

  1. In your test app or on your test base plan, create a rule-based retention offer, and set minDuration to P0D (0 days). In Google Play Console, choose Cohort-level retention offer. With the Google Play Developer API, set targeting to a retentionRule object. For details, see Set retention eligibility rules.
  2. Activate the offer, wait 10 to 15 minutes for the change to propagate, and then clear the Google Play Store app cache.
  3. On the test device, sign in with the license tester account, and then purchase the test base plan.
  4. 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.
  5. Accept the offer, and then confirm that your backend receives the SUBSCRIPTION_PLAN_TRANSITION_UPDATED RTDN 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 startTime and endTime, if you set them.
  • For a per-user retention offer, the developerTargetedOffers field in the purchases.subscriptionsv2.get response for the license tester's purchaseToken includes 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.