Subscription replacement always fails with DEVELOPER_ERROR when subscriptionProductReplacementParams is supplied

[Dim2960]

Subscription replacement always fails with DEVELOPER_ERROR when subscriptionProductReplacementParams is supplied

Summary

When requestPurchase is called with subscriptionProductReplacementParams, the
resulting BillingFlowParams carries an old purchase token without a replacement
mode. Play rejects the flow with DEVELOPER_ERROR — "Invalid arguments provided
to the API" — regardless of the mode requested.

Omitting subscriptionProductReplacementParams works, but then the mode is
hardcoded to CHARGE_FULL_PRICE, so callers have no way to select a replacement
mode at all.

Environment

expo-iap	5.2.4 (openiap-google 3.2.3) — also verified on 3.3.1
Play Billing	9.1.0
Build	Android release, minifyEnabled true
Device	Samsung, Android 15
Store	real Play, license-tested account

Verified on both 3.2.3 and 3.3.1 (latest published at the time of writing):
the code path below is identical in the two versions, so upgrading does not help.
This is not the R8 issue from #307 — 3.2.3 already contains the typed-call fix
from #309.

Where it comes from

packages/google/openiap/src/play/java/dev/hyo/openiap/OpenIapModule.kt:

val updateParamsBuilder = BillingFlowParams.SubscriptionUpdateParams.newBuilder()
androidArgs.purchaseToken?.takeIf { it.isNotBlank() }?.let {
    updateParamsBuilder.setOldPurchaseToken(it)          // ← old token IS set
}
androidArgs.originalExternalTransactionId?.takeIf { it.isNotBlank() }?.let {
    updateParamsBuilder.setOriginalExternalTransactionId(it)
}

// Developer-billed replacements use only the original external
// transaction ID unless the caller explicitly supplies a mode.
val replacementMode = 5.takeIf {
    !androidArgs.purchaseToken.isNullOrBlank() &&
        androidArgs.originalExternalTransactionId.isNullOrBlank() &&
        androidArgs.subscriptionProductReplacementParams == null   // ← the culprit
}
replacementMode?.let { mode ->
    updateParamsBuilder.setSubscriptionReplacementMode(mode)       // ← never reached
}

val updateParams = updateParamsBuilder.build()
flowBuilder.setSubscriptionUpdateParams(updateParams)              // ← applied anyway

Supplying subscriptionProductReplacementParams makes replacementMode null, so
setSubscriptionReplacementMode is skipped — but setSubscriptionUpdateParams is
still applied with the old purchase token. Play then has a subscription to replace
and no instruction on how to bill it.

The mode is applied at product level
(ProductDetailsParams.Builder.setSubscriptionProductReplacementParams), but that
does not appear to be sufficient for a single-product subscription changing
between two base plans.

Reproduction

Subscription product with two auto-renewing base plans (same billing period,
different prices). Active subscription on base plan A, auto-renew ON.

await requestPurchase({
  type: 'subs',
  request: {
    google: {
      skus: ['sub_example'],
      subscriptionOffers: [{ sku: 'sub_example', offerToken: '<offer token of plan B>' }],
      purchaseToken: '<token of the active subscription>',
      subscriptionProductReplacementParams: {
        oldProductId: 'sub_example',
        replacementMode: 'charge-prorated-price',
      },
    },
  },
});

Actual payload reaching the native side (from adb logcat -s ExpoIap:V, with
setprop log.tag.ExpoIap DEBUG):

requestPurchase payload: {"type":"subs","skus":["sub_example"],
  "purchaseToken":"hidden","originalExternalTransactionId":null,
  "subscriptionOffers":[{"sku":"sub_example","offerToken":"hidden"}],
  "subscriptionProductReplacementParams":{"oldProductId":"sub_example",
                                          "replacementMode":"charge-prorated-price"}}
requestPurchase result: []

The Play sheet opens and closes after ~3 s; the error surfaced to JS is
"Invalid arguments provided to the API" (DEVELOPER_ERROR).

Same result with with-time-proration — the mode itself is not the variable.

Removing subscriptionProductReplacementParams entirely makes the flow succeed,
which confirms the diagnosis: the legacy SubscriptionUpdateParams path works, and
it is the only one that ends up carrying a mode.

Impact

With the current code a caller can have either a working replacement or a
chosen mode, never both:

Sent	Result
purchaseToken + subscriptionProductReplacementParams	DEVELOPER_ERROR
purchaseToken alone	works, but always CHARGE_FULL_PRICE (hardcoded 5)

CHARGE_FULL_PRICE is not a safe default for every case:

• on a downgrade it charges the user immediately for a cheaper plan;
• on an upgrade between base plans of the same product, Play treats it as the
  same entitlement and carries the remaining time over as raw duration, so the
  user gets time on the expensive plan at the cheap plan's price.

Concretely, on a real store with a 12-month product: subscribing to the cheap base
plan and upgrading immediately yields two years of the expensive plan for the
price of one plus the cheap one.

Suggested fix

Let the caller's mode reach the legacy builder, falling back to the current default:

val replacementMode = androidArgs.subscriptionProductReplacementParams
        ?.replacementMode
        ?.toLegacyReplacementModeConstant()   // SubscriptionUpdateParams.ReplacementMode values
    ?: 5.takeIf {
        !androidArgs.purchaseToken.isNullOrBlank() &&
            androidArgs.originalExternalTransactionId.isNullOrBlank()
    }

Note that this needs a mapping to BillingFlowParams.SubscriptionUpdateParams.ReplacementMode,
whose numeric values differ from
ProductDetailsParams.SubscriptionProductReplacementParams.ReplacementMode — the very
distinction raised in #71.

Whether the product-level parameters should then still be set for a single-product
subscription is the open question; the legacy path alone is known to work.

I am happy to open a PR if the direction looks right.

[hyochan]

Thank you for the detailed report. I traced the payload through Expo IAP and openiap-google and compared it with the Play Billing 9.1 contract.

The current split is intentional:

• oldProductId and the requested mode are set on ProductDetailsParams.SubscriptionProductReplacementParams.
• The old purchase token is set on SubscriptionUpdateParams.
• The deprecated SubscriptionUpdateParams.setSubscriptionReplacementMode() is not called when product-level replacement params are present.

This matches the preferred Billing 9.1 subscription replacement example. The legacy builder contract explicitly says not to call setSubscriptionReplacementMode() when any product has setSubscriptionProductReplacementParams(). Applying the suggested legacy mapping would therefore send two mode sources and violate that contract.

The reported reproduction is a same-subscription switch (oldProductId and the target product are both sub_example) from an auto-renewing plan to another auto-renewing plan. Google allows only CHARGE_FULL_PRICE and WITHOUT_PRORATION for that combination. Both tested modes in the report—CHARGE_PRORATED_PRICE and WITH_TIME_PRORATION—are invalid for a same-subscription auto-renewing switch, so Play returning DEVELOPER_ERROR is consistent with the documented restrictions. Omitting the product-level params succeeds because the compatibility path supplies CHARGE_FULL_PRICE, which is valid for this case.

Could you retry the same flow with replacementMode: "without-proration" (and, optionally, "charge-full-price" as a control)? If either valid mode still returns DEVELOPER_ERROR, please share the sanitized native BillingResult.debugMessage and confirm that both the current and target base plans are auto-renewing. I will treat that as a concrete SDK bug and fix it.

I also reran the focused replacement-mode tests against Play Billing 9.1.0; all mappings and the typed product-level builder passed.

[Dim2960]

You're right on all counts, and thanks for tracing the payload through both layers — that spared me from filing a fix against the wrong contract.

Confirming your reading against my setup: our two tiers (Advanced and Premium) are two base plans of a single Play subscription (sub_jitavision), so every plan change is a same-subscription switch between auto-renewing plans. That is exactly the case where Play accepts only CHARGE_FULL_PRICE and WITHOUT_PRORATION — and both modes in my report (CHARGE_PRORATED_PRICE, WITH_TIME_PRORATION) are invalid there. The DEVELOPER_ERROR was Play enforcing its documented restriction, not the SDK mishandling the params.

The current split — oldProductId + mode on ProductDetailsParams, old purchase token on SubscriptionUpdateParams, and no call to the deprecated setSubscriptionReplacementMode() — matches the Billing 9.1 contract. My suggested legacy mapping would indeed have sent two mode sources; that suggestion was wrong.

I have not run the without-proration retry you asked for, so I can't give you a debugMessage — I'd rather say so than leave you waiting on data that isn't coming. The reason is that the answer stopped mattering for us: neither valid mode is commercially viable on a shared subscription product.

• CHARGE_FULL_PRICE — on a downgrade, charges the user upfront to move to a cheaper plan. On an upgrade, the remaining time carries over as raw duration with no conversion to the new plan's value, which turns "subscribe to the cheap tier, upgrade immediately" into a repeatable discount.
• WITHOUT_PRORATION — on a downgrade, drops the time already paid for on the higher tier. On an upgrade, hands out the higher tier for free until renewal.

Each one shortchanges one side in one direction and the other side in the other, so we have routed plan changes to the Play Store (cancel, then re-subscribe) and removed the replacement plumbing from the app. If we ever split the two tiers into separate Play subscriptions, the change becomes a cross-subscription switch, CHARGE_PRORATED_PRICE and DEFERRED become available, and I'll come back with real numbers.

Two small observations from reading logs during this, both take-them-or-leave-them:

1. A DEVELOPER_ERROR returned while subscriptionProductReplacementParams is set is almost always an invalid mode for the switch type. If the Android side appended the valid-mode set for the detected case to the error message, it would have pointed me at the answer in minutes instead of days.

2. ExpoIapLog.sanitizeMap masks by key name without inspecting the value, so requestPurchase payload prints "purchaseToken":"hidden" even when no token was supplied — the same reason userIdAmazon shows as "hidden" on Google purchases. When reading a log it looks like a token is being sent, which had me second-guessing a payload that was in fact correct. Printing null for null values, or omitting the key entirely, would remove a genuine source of confusion.

Feel free to close this as working as intended.

[hyochan]

Thank you for the thorough follow-up and for confirming the setup — that closes the loop cleanly.

Final state:

• Working as intended. The DEVELOPER_ERROR was Play enforcing its documented restriction for a same-subscription switch between auto-renewing base plans (only CHARGE_FULL_PRICE and WITHOUT_PRORATION are accepted there). The current parameter split — mode on ProductDetailsParams.SubscriptionProductReplacementParams, old purchase token on SubscriptionUpdateParams, no call to the deprecated setSubscriptionReplacementMode() — matches the Billing 9.1 contract, so no SDK change is needed for the replacement flow itself.
• Since you have routed plan changes to the Play Store and removed the replacement plumbing, there is no outstanding data to wait on.

Both of your observations were worth keeping and are now tracked as follow-ups:

• Append the valid replacement-mode set to subscription replacement DEVELOPER_ERROR #371 — append the valid replacement-mode set for the detected switch type to the DEVELOPER_ERROR message, so the next person gets the answer in minutes instead of days.
• Log sanitizers print "hidden" for sensitive keys whose value is null #372 — stop printing "hidden" for sensitive keys whose value is null, so logs no longer imply data that was never sent.

Closing as working as intended. If you later split the tiers into separate Play subscriptions and hit issues with the cross-subscription modes, please open a new issue — happy to dig in with you again.