Unified StoreReplacementMode API by fire-at-will · Pull Request #3234 · RevenueCat/purchases-android

fire-at-will · 2026-03-13T19:04:46Z

Motivation

With the introduction of the Galaxy Store, we needed to find a way to gracefully model our replacement mode APIs for product changes, now that we have two stores in the Android SDK that support product changes with replacement modes.

Our current replacement mode APIs are store-specific. This allows you to tailor the replacement modes to each store, but puts the onus on the developer to maintain different logic for each store to call the appropriate PurchaseParams.Builder function to set the replacement mode for that store.

Description

This PR introduces a new unified StoreReplacementMode enum that can be used across both the Play Store and the Galaxy Store. It replaces the existing GoogleReplacementMode and GalaxyReplacementMode enums. It has the same fields as the existing GoogleReplacementMode:

public enum class StoreReplacementMode : ReplacementMode {
    WITHOUT_PRORATION,
    WITH_TIME_PRORATION,
    CHARGE_FULL_PRICE,
    CHARGE_PRORATED_PRICE,
    DEFERRED,
}

The following table documents how each StoreReplacementMode maps to each store:

StoreReplacementMode	Play Store Replacement Mode	Galaxy Replacement Mode
WITHOUT_PRORATION	WITHOUT_PRORATION	INSTANT_NO_PRORATION
WITH_TIME_PRORATION	WITH_TIME_PRORATION	INSTANT_PRORATED_DATE
CHARGE_FULL_PRICE	CHARGE_FULL_PRICE	N/A - error returned if provided to purchase()
CHARGE_PRORATED_PRICE	CHARGE_PRORATED_PRICE	INSTANT_PRORATED_CHARGE
DEFERRED	DEFERRED	DEFERRED

Additionally, this PR deprecates the existing GoogleReplacementMode enum and associated public APIs and hard-removes the experimental GalaxyReplacementMode enum and its APIs.

Under the hood, it also updates the product change flows for both the Galaxy and Play Stores to use the StoreReplacementMode enum instead of the store-specific enums.

API Changes

Additions

StoreReplacementMode enum
PurchaseParams.replacementMode: StoreReplacementMode (defaults to WITHOUT_PRORATION)
PurchaseParams.Builder.replacementMode(replacementMode: StoreReplacementMode)

Deprecations

GoogleReplacementMode - use StoreReplacementMode instead
PurchaseParams.googleReplacementMode - use PurchaseParams.replacementMode instead
PurchaseParams.Builder.googleReplacementMode - use PurchaseParams.Builder.replacementMode instead
PurchaseParams.Builder.googleReplacementMode(googleReplacementMode: GoogleReplacementMode) - use PurchaseParams.Builder.replacementMode(replacementMode: StoreReplacementMode) instead

Hard Removals

These are all currently marked as @ExperimentalPreviewRevenueCatPurchasesAPI:

GalaxyReplacementMode - use StoreReplacementMode instead
PurchaseParams.galaxyReplacementMode - use PurchaseParams.replacementMode instead
PurchaseParams.Builder.galaxyReplacementMode - use PurchaseParams.Builder.replacementMode instead
PurchaseParams.Builder.galaxyReplacementMode(galaxyReplacementMode: GalaxyReplacementMode) - use PurchaseParams.Builder.replacementMode(replacementMode: StoreReplacementMode) instead

Paywalls Changes

This PR includes minor changes to the paywalls product to account for this change, primarily in how product changes and custom purchase logic are handled.

Testing

Lots of unit tests
Manually tested:
- Product changes on the Galaxy Store using the new StoreReplacementAPI work
- Confirmed that making a product change on the Galaxy Store with StoreReplacementAPI.CHARGE_FULL_PRICE returns an unsupported error
- Product changes on the Play Store using the deprecated GoogleReplacementAPI still work
- Product changes on the Play Store using the new StoreReplacementAPI work

Note

Medium Risk
Introduces a new unified replacement-mode API and rewires Play/Galaxy product-change flows and backend payload mapping, which could affect upgrade/downgrade behavior and receipt posting across stores. Risk is mitigated by extensive test updates but touches core purchase paths.

Overview
Unifies subscription product-change replacement modes across stores by introducing StoreReplacementMode and a new PurchaseParams.Builder.replacementMode(...) / PurchaseParams.replacementMode field, while hard-removing experimental GalaxyReplacementMode APIs and deprecating GoogleReplacementMode and related PurchaseParams accessors.

Updates Play Store and Galaxy Store purchase/product-change implementations to consume StoreReplacementMode, including store-specific conversions (Play Billing mode, Galaxy proration mode) and store-aware backend serialization for proration_mode.

Adjusts sample/test harnesses and paywall product-change config/serializers to use StoreReplacementMode, and refreshes unit tests to cover new defaults, mapping behavior, deferred product-change handling, and Galaxy unsupported-mode errors (notably CHARGE_FULL_PRICE).

^{Written by Cursor Bugbot for commit 065832a. This will update automatically on new commits. Configure here.}

codecov · 2026-03-13T19:20:30Z

Codecov Report

❌ Patch coverage is 91.66667% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.43%. Comparing base (b4a62c7) to head (7985a60).
⚠️ Report is 25 commits behind head on main.

Files with missing lines	Patch %	Lines
...urchases/models/StoreReplacementModeConversions.kt	94.00%	2 Missing and 1 partial ⚠️
...kotlin/com/revenuecat/purchases/ReplacementMode.kt	85.71%	0 Missing and 2 partials ⚠️
...at/purchases/google/BillingFlowParamsExtensions.kt	60.00%	1 Missing and 1 partial ⚠️
.../com/revenuecat/purchases/PurchasesOrchestrator.kt	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3234      +/-   ##
==========================================
+ Coverage   79.39%   79.43%   +0.04%     
==========================================
  Files         356      357       +1     
  Lines       14344    14387      +43     
  Branches     1959     1966       +7     
==========================================
+ Hits        11389    11429      +40     
- Misses       2151     2152       +1     
- Partials      804      806       +2

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

emerge-tools · 2026-03-16T20:55:16Z

📸 Snapshot Test

582 unchanged

Name	Added	Removed	Modified	Renamed	Unchanged	Errored	Approval
TestPurchasesUIAndroidCompatibility Paparazzi com.revenuecat.testpurchasesuiandroidcompatibility.paparazzi	0	0	0	0	257	0	N/A
TestPurchasesUIAndroidCompatibility com.revenuecat.testpurchasesuiandroidcompatibility	0	0	0	0	325	0	N/A

🛸 Powered by Emerge Tools

…tMode

…eplacementMode

fire-at-will · 2026-03-18T14:37:42Z

purchases/src/main/kotlin/com/revenuecat/purchases/ReplacementMode.kt

+    }
+}
+
 internal object ReplacementModeSerializer : KSerializer<ReplacementMode> {


This PR updates ReplacementModeSerializer to be asymmetric to account for the migration from GoogleReplacementMode -> StoreReplacementMode.

For serialization, it always serializes to StoreReplacementMode, even if the object is a GoogleReplacementMode.

For deserialization, it supports both GoogleReplacementMode and StoreReplacementMode as inputs to maintain backwards compatibility, but always deserializes to a StoreReplacementMode.

fire-at-will · 2026-03-18T15:43:24Z

...c/main/kotlin/com/revenuecat/purchases/galaxy/conversions/StoreReplacementModeConversions.kt

+        StoreReplacementMode.CHARGE_PRORATED_PRICE -> HelperDefine.ProrationMode.INSTANT_PRORATED_CHARGE
+        StoreReplacementMode.DEFERRED -> HelperDefine.ProrationMode.DEFERRED
+        StoreReplacementMode.CHARGE_FULL_PRICE -> {
+            val message = GalaxyStrings.CHARGE_FULL_PRICE_NOT_SUPPORTED


If StoreReplacementMode.CHARGE_FULL_PRICE is provided to the Galaxy store for a product change, we return an error, since there is no equivalent of this mode for the Galaxy Store.

We could gracefully degrade to a default here, but I thought it might be best to fail since the request can't be executed as specified. What do y'all think?

fire-at-will · 2026-03-18T15:50:00Z

ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/PurchaseLogic.kt

-         * For Google Play, use [com.revenuecat.purchases.models.GoogleReplacementMode].
+         * Use [com.revenuecat.purchases.models.StoreReplacementMode].
         */
        public fun replacementMode(replacementMode: ReplacementMode?): Builder = apply {


I don't believe this is technically a breaking change since .replacementMode() uses ReplacementMode

tonidero

Great work! My only comment is whether we should try to avoid using enums for the new type now that we have the chance. Lmk what you think!

tonidero · 2026-03-23T10:06:19Z

purchases/src/main/kotlin/com/revenuecat/purchases/models/StoreReplacementModeConversions.kt

+    return mapping.legacyPlayBackendName
+}
+
+internal fun StoreReplacementMode.storeBackendName(store: Store): String? {


Could have been nice to try to consolidate these in the backend... But that should be a different PR.

tonidero · 2026-03-23T10:09:07Z

purchases/src/main/kotlin/com/revenuecat/purchases/models/StoreReplacementMode.kt

+ * Enum of possible replacement modes to be used when performing a subscription product change.
+ */
+@Parcelize
+public enum class StoreReplacementMode : ReplacementMode {


I'm thinking... should we take the chance to make this not an enum? Since we want to avoid enums/sealed classes in public APIs when possible.... The approach we've been folllowing can be seen for example with the CustomVariableValue type. It would mean we can't have exhaustive when-else statements... but I think that's exactly the point, for public APIs 😅 . Wdyt?

If this is the direction we're trying to take our APIs, I'm more than happy to go with the pattern! Will update the PR to use an abstract class like CustomVariableValue does :)

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

cursor · 2026-04-01T15:06:13Z

purchases/src/main/kotlin/com/revenuecat/purchases/google/BillingWrapper.kt

            val productId =
-                if (replaceProductInfo?.replacementMode == GoogleReplacementMode.DEFERRED) {
+                if (replaceProductInfo?.replacementMode == StoreReplacementMode.DEFERRED ||
+                    replaceProductInfo?.replacementMode == GoogleReplacementMode.DEFERRED


Inconsistent replacement mode handling in BillingWrapper DEFERRED check

Low Severity

The DEFERRED mode check on lines 300–301 defensively handles both StoreReplacementMode.DEFERRED and GoogleReplacementMode.DEFERRED, but the PurchaseContext assignment on line 326 uses as? StoreReplacementMode?, which silently drops GoogleReplacementMode to null. If a GoogleReplacementMode.DEFERRED were to reach this code, the callback would be correctly routed to the old product ID, but the replacement mode stored on the resulting StoreTransaction (and sent to the backend) would be null. The two locations are inconsistent in their handling of the deprecated type.

Additional Locations (1)

purchases/src/main/kotlin/com/revenuecat/purchases/google/BillingWrapper.kt#L325-L326

add StoreReplacementMode + API tests

26157e8

fire-at-will added the pr:feat A new feature label Mar 13, 2026

fire-at-will added 13 commits March 13, 2026 14:22

add StoreReplacementMode -> store specific conversions + tests

fe1db6e

remove Product change

49a58cb

remove GalaxyPurchasingData.Product api.txt change

6d3b024

add StoreReplacementMode to api.txts

3039a06

add .replacementMode() to PurchaseParams

9a42704

set PurchaseParams.googleReplacementMode when setting replacementMode

e1e2017

detekt

d067c44

Merge branch 'main' into shared-replacement-mode

bf8c82a

Merge branch 'main' into shared-replacement-mode

c302f2d

galaxy-specific flow updates

8782fcb

add unit tests for galaxy flow

503e9e0

Update PurchasesOrchestrator.kt

ac40b0e

update PurchasesCommonTest

9666938

fire-at-will added 13 commits March 17, 2026 10:19

Google -> StoreReplacementMode in play store flows

4ecb493

detekt

3448485

Merge branch 'main' into shared-replacement-mode

93e19aa

update backend name generation to use StoreReplacementMode

aabb558

set replacementMode in PurchaseParams when providing googleReplacemen…

da3dd6e

…tMode

make ReplacementModeSerializer use StoreReplacementMode

a98959f

update PurchaseParams public APIs

7b76f17

remove GalaxyReplacementMode

1f08ad0

actually remove GalaxyReplacementMode

8fd6aab

Merge branch 'main' into shared-replacement-mode

0981b79

deprecate GoogleReplacementMode

0d1859f

migrate paywalls to use StoreReplacementMode

de85b71

send replacement mode to handleReceipt() in galaxy flow

f0312d4

fire-at-will added 5 commits March 17, 2026 15:04

update paywall tests

28c8ac1

docs updates

31a571f

default to WITHOUT_PRORATION in galaxy when it receives unsupported r…

266a2ba

…eplacementMode

update paywall docs

56356cd

ReplacementMode serialization tweaks

8fb4f13

fire-at-will commented Mar 18, 2026

View reviewed changes

fire-at-will added 3 commits March 18, 2026 10:23

centralize ReplacementMode mapping

a981323

detekt

5948a18

Merge branch 'main' into shared-replacement-mode

9993691

fire-at-will marked this pull request as ready for review March 18, 2026 15:40

fire-at-will requested review from a team as code owners March 18, 2026 15:40

fire-at-will commented Mar 18, 2026

View reviewed changes

fire-at-will changed the title ~~[WIP]: Unified StoreReplacementMode API~~ Unified StoreReplacementMode API Mar 18, 2026

fire-at-will requested a review from tonidero March 18, 2026 15:48

fire-at-will commented Mar 18, 2026

View reviewed changes

fire-at-will requested a review from vegaro March 18, 2026 16:20

fire-at-will added 4 commits March 19, 2026 09:56

update PurchaseTester to use new replacementMode APIs

a7e0ef9

Update PurchaseParamsValidatorTest.kt

987bc18

update api testers

ff9863c

update PurchaseTester to allow product changes on galaxy store

7985a60

tonidero reviewed Mar 23, 2026

View reviewed changes

Merge branch 'main' into shared-replacement-mode

065832a

cursor bot reviewed Apr 1, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Unified StoreReplacementMode API#3234

Unified StoreReplacementMode API#3234
fire-at-will wants to merge 40 commits intomainfrom
shared-replacement-mode

fire-at-will commented Mar 13, 2026 •

edited by cursor bot

Loading

Uh oh!

codecov bot commented Mar 13, 2026 •

edited

Loading

Uh oh!

emerge-tools bot commented Mar 16, 2026 •

edited

Loading

Uh oh!

fire-at-will Mar 18, 2026

Uh oh!

fire-at-will Mar 18, 2026

Uh oh!

fire-at-will Mar 18, 2026

Uh oh!

tonidero left a comment

Uh oh!

tonidero Mar 23, 2026

Uh oh!

tonidero Mar 23, 2026

Uh oh!

fire-at-will Apr 1, 2026

Uh oh!

cursor bot left a comment

Uh oh!

cursor bot Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

fire-at-will commented Mar 13, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Description

API Changes

Additions

Deprecations

Hard Removals

Paywalls Changes

Testing

Uh oh!

codecov bot commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

emerge-tools bot commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📸 Snapshot Test

582 unchanged

Uh oh!

fire-at-will Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

fire-at-will Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

fire-at-will Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

tonidero left a comment

Choose a reason for hiding this comment

Uh oh!

tonidero Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

tonidero Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

fire-at-will Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Apr 1, 2026

Choose a reason for hiding this comment

Inconsistent replacement mode handling in BillingWrapper DEFERRED check

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fire-at-will commented Mar 13, 2026 •

edited by cursor bot

Loading

codecov bot commented Mar 13, 2026 •

edited

Loading

emerge-tools bot commented Mar 16, 2026 •

edited

Loading