Product changes (Google Play)
When a customer with an active Google Play subscription purchases a different product through your paywall, you can configure how that subscription change (upgrade or downgrade) is handled.
Without product change configuration, customers who purchase a different product will end up with two active subscriptions running in parallel.
Product change configuration is specific to Google Play. On the App Store, subscription changes are handled automatically by Apple within subscription groups. Learn more about managing subscriptions.
How it works
When product changes are configured on your paywall, the SDK will automatically:
- Detect the active subscription: Check if the customer has an active Google Play subscription.
- Determine the change direction: Compare the normalized price-per-unit-time of the current and new products to classify the change as an upgrade (higher price) or downgrade (lower price).
- Apply the replacement mode: Use the configured replacement mode for upgrades or downgrades when initiating the purchase.
This means customers can switch between subscription products directly from your paywall without you needing to write any product change logic.
To show different paywall content to existing subscribers, use Targeting to serve a different Offering or Paywall, or pass custom variables and use Rules to change component visibility.
If a customer selects the exact package they're already subscribed to, Google Play may show that the item is already owned. In the RevenueCat SDK, this is surfaced as a ProductAlreadyPurchasedError purchase error.
When a customer switches between base plans of the same product (e.g., from a monthly to an annual plan of the same subscription), Google Play handles this automatically using whatever replacement mode you've configured in the Google Play Console. The paywall's product change configuration only applies when switching between different products.
Configuration
- In Google Play Console, make sure the subscription products, base plans, and offers you want to sell are configured for your app.
- In RevenueCat, add the target products to the Offering used by your Paywall.
- In the Paywall Editor, open Paywall settings and configure Play Store only: Replacement mode.
- Choose the replacement mode to use for upgrades and for downgrades, then publish your paywall.
Replacement modes
| Mode | Default for | Description |
|---|---|---|
| Charge prorated price | Upgrades | Replacement takes effect immediately, and the price difference for the remaining period is charged to the user. Only available for upgrades. |
| Deferred | Downgrades | Replacement takes effect when the current plan expires, and the new price is charged at the same time. |
| Without proration | — | The old subscription is cancelled, and the new one takes effect immediately. The user is charged the full price of the new subscription on the old subscription's expiration date. |
| With time proration | — | The old subscription is cancelled, and the new one takes effect immediately. Remaining time on the old subscription pushes out the first payment date for the new subscription. |
| Charge full price | — | Replacement takes effect immediately. The user is charged the full price of the new plan and given a full billing cycle, plus remaining prorated time from the old plan. |
For detailed descriptions and Google's recommendations, see Google's replacement mode documentation.
If you use Deferred, configure Google Server Notifications so RevenueCat receives the subscription update when the new product takes effect.
Supported SDK versions
| RevenueCat SDK | Minimum version |
|---|---|
| purchases-android | 9.21.0 and up |