You can change the prices of your subscription base plans and offers. For
example, you might have digital products that need annual price adjustments, or
you might change the set of benefits for a product and want to reflect these
changes in the price.

For more information about changing subscription prices using the Play Console,
see the documentation in the [Play Console Help
Center](https://support.google.com/googleplay/android-developer/answer/140504).

To programmatically change the subscription base plan price, use the
[`monetization.subscriptions.patch`](https://developers.google.com/android-publisher/api-ref/rest/v3/monetization.subscriptions/patch)
method. This method receives a
[`Subscription`](https://developers.google.com/android-publisher/api-ref/rest/v3/monetization.subscriptions#resource:-subscription)
object with the subscription product configuration that is being changed. Set
the new price in the
[`RegionalBasePlanConfig`](https://developers.google.com/android-publisher/api-ref/rest/v3/monetization.subscriptions#regionalbaseplanconfig)
object under the correct base plan in the subscription's `basePlans` collection.
This can be very useful if you have a sizable catalog and you need to make
updates to all of your products in a short period of time, or if you have a
product catalog management system that automatically makes changes to your
Google Play subscription products when changes occur.
| **Warning:** You should not change the price of a [Subscribe with
| Google](https://developers.google.com/news/subscribe) subscription.

It could be useful to visit your Play Console [change
log](https://support.google.com/googleplay/android-developer/answer/6053184) to
look up info about any price changes you have made in the past. The information
you can find there includes when the prices were updated, who initiated the
change, the regions that were updated, and more. This might assist you in cases
where you need to review past price changes or review an accidental price change
to assess next steps.

## Price changes for new subscription purchases

When you change the price of a base plan or offer, the new price takes effect
within a few hours for all new purchases without you having to take any
additional action.

## Price changes for existing subscribers

When you change subscription prices, existing subscribers are unaffected by
default; they are placed into a legacy price cohort where they continue to pay
their original base plan price when they renew.

If desired, you can move existing subscribers to the current base plan price.
This is action is called [ending a legacy price cohort](https://developer.android.com/google/play/billing/price-changes#end-legacy). Changes to
an offer's pricing phases cannot be applied to existing subscribers. For
installment subscriptions, price changes for a legacy cohort happen at the
end of the active commitment period. You cannot change the price currently
being paid for a user who is in the middle of paying their installments.

## End a legacy price cohort

You can choose to end a legacy price cohort at any time. This can be done
independently for each region. To end a legacy price through the Play Console,
refer to the [Play Console Help
Center](https://support.google.com/googleplay/android-developer/answer/140504).

### End a legacy price cohort with the Google Play Developer API

To programmaticaly end a legacy price cohort, use the
[`monetization.subscriptions.basePlans.migratePrices`](https://developers.google.com/android-publisher/api-ref/rest/v3/monetization.subscriptions.basePlans/migratePrices)
method. This method migrates subscribers who are receiving a historical
subscription price to the current base plan price for the specified regions. The
method also triggers price change notifications to be sent to users who are
currently receiving a historical price older than the supplied timestamp. When
you send this request, you include a list of
[`RegionalPriceMigrationConfig`](https://developers.google.com/android-publisher/api-ref/rest/v3/monetization.subscriptions.basePlans/migratePrices#regionalpricemigrationconfig)
objects in the request body to configure the price cohort migration.

For more information on using legacy price cohorts, see the [Play Console Help
Center](https://support.google.com/googleplay/android-developer/answer/140504).

## Price decreases

When you end a legacy price cohort and the new purchase price is *lower* than
the price that users in the cohort are paying, Google Play notifies the users by
email and these subscribers begin paying the lower price the next time they pay
for their base plan.

**Note:** [Payment authorization](https://support.google.com/googleplay/answer/2476088 "Payment authorization") may be placed up to 48
hours before the start of a user's next renewal period. However, for users in
India or Brazil, this period extends to up to 5 days before the next renewal
period. Users who have already been authorized at the higher price won't be
immediately charged the lower price; they will renew at the lower price on their
subsequent renewal.

[License testers](https://developer.android.com/google/play/billing/test) also receive email notifications
for price decreases.

## Price increases

When ending a legacy price cohort and the new price is *higher* than the price
that users in the cohort are paying, a price increase occurs. Price increases
may or may not require user action.

By default, price increases are *opt-in* changes for existing subscribers. Users
must explicitly accept the higher price before it is first charged, or Google
Play automatically cancels their subscription. Users are charged the higher
price the next time they pay for their base plan following an advance
notification period of 37 days. Starting 30 days before this charge, Play
notifies existing subscribers through email and push notifications.

During the first seven days after the cohort migration is triggered, no users
receive notifications from Google Play. This means that you have seven days from
when you initiate an opt-in price increase to notify your existing subscribers
before Google Play begins notifying them directly. During this period, you can
effectively cancel a pending price increase by making another price change back
to the original price.

After that seven-day period, each user receives automatic notifications from
Google Play 30 days before the first renewal with the new price.

In some cases when increasing prices for existing subscribers, you have the
option to perform price increases with advance notification to users, but
without requiring them to take any action. With this option, unless users
*opt-out* by changing subscription plans or canceling their subscription,
they'll be charged the new price the next time they pay for their base plan
following an advance notification period. This period varies by country and is
either 30 days or 60 days. Beginning that number of days before this charge,
Play notifies existing subscribers through email and push notification.

Opt-out increases are only available in certain locations with limits on the
increase amount and frequency, and are subject to certain developer
requirements.

You can mark a legacy price cohort migration as an opt-out increase if it meets
those criteria, as shown in figure 1.
![Google Play Console legacy price cohort migration with opt-out increase](https://developer.android.com/static/images/google/play/billing/opt-out-increase.png) **Figure 1.** Using Play Console to specify a legacy price cohort migration as an opt-out increase.

![](https://developer.android.com/static/images/google/play/billing/opt-out-increase.png)

## Communicate your price change to the user

| **Important:** This notice must be displayed on all device types where the app is available, including mobile, TV platforms, and streaming devices. The sole exception is watch devices, for which the notice is recommended but not required.

You should notify existing subscribers whenever you end their legacy
price cohort.

For opt-out price increases, you should give users advance notification, and you
must show users an in-app notice. Unlike opt-in price increases, there is no
seven-day waiting period before Play starts notifying users directly.

For opt-in price increases, give users advance notification and inform them of
the need to accept the price increase. When you initiate an opt-in price
increase, you have seven days to notify your existing subscribers before Google
Play begins to notify them directly. We recommend that you notify affected users
in your app and provide a deep link to the Play Store subscription screen to
help them easily review the new price. When users review an opt-in price
increase on the Play Store subscription screen, a dialog similar to figure 2 is
shown.
![Generic dialog notifying the user of a subscription price change](https://developer.android.com/static/images/google/play/billing/price-change-1.png) **Figure 2.** Example dialog notifying the user of a subscription price change.

## Handle user response to an opt-in price change

After you have notified existing subscribers of a price change and it's an
opt-in increase, they may take action before the new price applies to accept or
not accept the price increase. If they do, you will receive an RTDN informing
you of the outcome. See the [purchase lifecycle
guidance](https://developer.android.com/google/play/billing/lifecycle/subscriptions#price-changes) to learn
how to handle these notifications.

If the user doesn't act and they reach the first renewal that the opt-in price
will apply to, their subscription is automatically canceled and expired on that
renewal date.

## Accidental price increases

This section describes the various scenarios for handling an accidental
price change.

- **Opt-in increase** - If you've accidentally initiated an opt-in price
  increase, reverse the change immediately by making another price
  change back to the original price.

  Change the base plan price back to the original price and navigate to the
  legacy price points page to initiate a price decrease to the original
  price. Existing subscribers are not notified about the accidental price change
  if the price is reverted within seven days. If the price is reverted
  back to the old price after seven days, the price change will be canceled
  for any users who have not paid the new price. The price change is cancelled
  after the [payment authorization](https://support.google.com/googleplay/answer/2476088 "Payment authorization") period of up to five
  days. Based on renewal dates, some users may have already received the opt-in
  email notice.
- **Opt-out increase** - You can cancel an accidental opt-out increase by
  reverting the price back to the original price. Change the base plan price
  back to the original price and navigate to the legacy price points page to
  initiate a price decrease to the original price. Depending on when the
  price is reverted if a user has not already paid the higher price,
  their price increase would be canceled after the
  [payment authorization](https://support.google.com/googleplay/answer/2476088 "Payment authorization") period of up to five days.
  Based on renewal dates, some users may have already received the price
  increase notice emails.

- **Price decreases** - You can cancel a price decrease by reverting
  the subscription's price back to its original value by using the Google Play
  Console. Change the base plan price back to the original price and navigate
  to the legacy price points page to initiate a price increase to the
  original price. Developers can initiate either opt-in or opt-out
  (if eligible) to cancel the price decrease. If using opt-out, it would be
  counted toward the frequency. Google Play determines whether the
  cancellation is effective for a given user's next renewal based on
  the timing of this reversion relative to their individual renewal date.

  - A price decrease cancellation is valid if the period between
    reverting the price to its original value and a user's expected
    renewal time at the new price exceeds the relevant country-specific
    notification window (30 or 60 days). The user's next subscription
    renewal occurs at the original, higher price.

  - A price decrease cancellation is invalid if the period between reverting
    the price to its original value and a user's expected renewal time at the
    new price is shorter or equal to the relevant country-specific notification
    window (30 or 60 days). The user will instead go through the price
    increase process after being charged the lower price at least once upon
    the next renewal. The user will then get notified about a price increase.
    Depending on the mode selected during the price migration users would
    need to accept the price increase for opt-in price increase or would
    receive the notifications about an opt out increase. Any frequency and
    amount limitations for opt out increase would apply in this case.

## Handle overlapping price changes

Make sure that you only do one price change at a time. However, if you perform
a price change multiple times, impacted users need to agree only to the
latest price change. For example, if you've ended a legacy price cohort
with an opt-in price increase, changed the price again, and then performed
another opt-in price increase, affected users no longer need to respond
to the first price increase because only the second price increase now applies.
This behaviour applies for legacy price opt-in and opt-out price
increases and price decreases.

When you start a new price migration for an item that has an older price
migration in progress, Google Play handles it as follows:

- Old price migration is canceled.

  Google Play stops the old price migration. In the `SubscriptionPurchaseV2`
  API, you'll see the old price change details marked as `CANCELED`. You'll also
  receive a `SUBSCRIPTION_PRICE_CHANGE_UPDATED` RTDN.
- New Price Migration takes over.

  Immediately after, Google Play starts the new price migration. This will
  appear in `SubscriptionPurchaseV2` as either `OUTSTANDING`
  (for opt-in increases) or `CONFIRMED`
  (for opt-out increases or price decreases). You'll receive
  another `SUBSCRIPTION_PRICE_CHANGE_UPDATED` RTDN for the item.
- The user gets the new price.

  The user will now be moved to the new price migration, and they won't
  complete the previous price change. And the user receives the
  standard notification period for the new price.

## Test price changes

Don't change subscription prices for products owned by active subscribers for
testing purposes.

You can use the [Play Billing Lab app](https://play.google.com/store/apps/details?id=com.google.android.apps.play.billingtestcompanion) and license testers to test subscription
price changes without affecting other active subscribers.

See the [testing guide](https://developer.android.com/google/play/billing/test#price-changes) to learn more
about testing price changes.

## Examples

The examples in this section demonstrate how to apply best practices in
different price change scenarios.  

### Opt-in price increase examples

#### Example 1: Monthly subscription opt-in price increase

On March 3, AltoStrat increases the price for AltoStrat Pro, their premium
video streaming subscription, by ending a legacy price cohort. They move users
in the legacy price cohort of $1 to the current base plan price of $2. The
effective date of the price change is April 9 (37 days after March 3).

Alice is an existing subscriber whose next renewal is on March 5. The first
renewal after the effective date is on May 5, so she renews on March 5 and on
April 5 at the old price ($1). When she renews again on May 5, she is charged
the new price ($2). Google Play starts notifying Alice of the price change on
April 5, which is 30 days before the first renewal date with the new price.
![](https://developer.android.com/static/images/google/play/billing/price-change-schedule-monthly-example-1.svg) **Figure 3.** Example price change timeline diagram of a monthly subscription with a March 5 renewal date.

Bob is an existing subscriber whose next renewal is on March 29. He renews on
March 29 at the old price ($1) because the price change has not yet taken
effect. When he renews again on April 29, he is charged the new price ($2). He
starts receiving price change notifications on March 30, which is 30 days before
the first renewal date with the new price.
![](https://developer.android.com/static/images/google/play/billing/price-change-schedule-monthly-example-2.svg) **Figure 4.** Example price change timeline diagram of a monthly subscription with a March 29 renewal date.

#### Example 2: 3 month subscription opt-in price increase

On March 3, FindMyLove ends a legacy price cohort and increases the 3-month fee
for FindMyLove Premium from $1 to the base plan price of $2. The effective date
of the price change is April 9 (37 days after March 3).

Alice is an existing subscriber whose next renewal is on March 5. Alice renews
at the old price ($1) because the price change has not yet taken effect. When
she renews again on June 5, she is charged the new price ($2). She starts
receiving notification of the price change on May 6, which is 30 days before the
first renewal date with the new price.
![](https://developer.android.com/static/images/google/play/billing/price-change-schedule-monthly-example-3.svg) **Figure 5.** Example price change timeline diagram of a 3 month subscription with a March 5 renewal date.

Bob is an existing subscriber whose next renewal is on April 11. Bob renews at
the new price ($2) because it's after the effective date for the price change.
He starts receiving notifications of the price change on March 12, which is 30
days before the first renewal date with the new price.
![](https://developer.android.com/static/images/google/play/billing/price-change-schedule-monthly-example-4.svg) **Figure 6.** Example price change timeline diagram of a 3 month subscription with an April 11 renewal date.

#### Example 3: Weekly subscription opt-in price increase

On March 3, CutePetsNews ends a legacy price cohort triggering a price migration
of weekly fee for Weekly Dog Alerts from $1 to $2. The effective date of the
price change is April 9.

Alice is an existing subscriber whose next weekly renewal is on March 6. She
renews on March 6, March 13, March 20, March 27, and April 3 at the old price
($1) because the price change has not yet taken effect. When she renews again on
April 10, she is charged the new price ($2). She starts receiving notification
of the price change on March 11, which is 30 days before the first renewal date
with the new price.
![](https://developer.android.com/static/images/google/play/billing/price-change-schedule-monthly-example-5.svg) **Figure 7.** Example price change timeline diagram of a weekly subscription with an April 6 renewal date.

#### Example 4: Monthly subscription with multiple opt-in price changes

This example demonstrates how multiple price changes are handled.

On March 3, AltoStrat triggers a price migration for AltoStrat Pro, their
premium video subscription, increasing the price from $1 per month to $2. On
March 10, the developer triggers a second price migration, increasing the price
to $3 per month.

The effective date of the first price change is April 9 (37 days after March 3).
The effective date of the second price change is April 16 (37 days after March
10).

Alice's next renewal is on March 5. The first renewal after the effective date
is on May 5, so she renews on March 5 and on April 5 at the old price ($1). When
she renews again on May 5, she is charged the newest price ($3). She only
receives
notifications about the second price change because the price changes happened
within the 7-day freeze period. She starts receiving notification of the price
change on April 5, which is 30 days before the first renewal date with the new
price.
![](https://developer.android.com/static/images/google/play/billing/price-change-schedule-monthly-example-6.svg) **Figure 8.** Example price change timeline diagram of a monthly subscription with multiple price changes and a March 5 renewal date.

#### Example 5: 12-month installment subscription opt-in price increase

This example shows how price increases are handled for installment subscriptions.

On March 3, AltoStrat increases the price for AltoStrat Pro, their
premium video streaming subscription, by ending a legacy price cohort. They
move users in the legacy price cohort of $1 to the current base plan price of
$2. The effective date of the price change is April 9 (37 days after March 3).

Alice is an existing subscriber who signed up for a 12-month installment plan
followed by monthly auto-renewals on June 10 of the previous year. Her first
renewal is on June 10 of the current year. Since Alice is in the middle of
paying her installments, she continues to pay $1 on March 10, April 10, and
May 10. She has her first renewal on June 10, where she is charged the new
price ($2) and switches to a monthly auto-renewal cadence. Google Play starts
notifying Alice of the price change on May 11, which is 30 days before the
first renewal date with the new price.  

### Opt-out price change examples

#### Example 1: Monthly subscription opt-out price change

This example shows how opt-out price increases are handled.

AltoStrat needs to make their annual price adjustment to account for
programming cost increases. On January 2, they change the price of
AltoStrat Pro (their premium video streaming subscription) from $1 to $1.30.
This price increase meets the criteria for an opt-out price migration. They
immediately end the legacy price cohort, specifying an opt-out migration. Users
in this cohort are in regions requiring a 30-day minimum opt-out notification
period, so the new price is effective on February 1.

Alice is an existing subscriber, charged on the 14th of each month. Due to the
30-day minimum notification period, she pays the old price ($1) on January 14.
Google Play starts notifying Alice of the price change on January 15, and she
starts paying the new price ($1.30) on February 14.  

### Price step-up consent examples

The [price step-up consent](https://developer.android.com/google/play/billing/lifecycle/subscriptions#price-stepup-consent)
examples in this section are applicable only to the South Korea (KR) region.

#### Example 1: User consents to the price step-up during signup

On March 3, a user signs up for a subscription in South Korea with a
free trial period of 10 days. The user consents to price step-up during
signup. In this scenario, Play applies the price step-up on March 13.

#### Example 2: User doesn't consent to the price step-up during the free trial

On March 3, a user signs up for a subscription in South Korea with a
free trial period of 10 days. The user didn't consent to the price
step-up during the signup or the free trial. The following is the sequence
of events in this scenario:
![](https://developer.android.com/static/images/google/play/billing/price-stepup-example-2.png) **Figure 9.** Example timeline diagram when a user doesn't consent to the price step-up during a free trial. A consent period can be for a maximum of 30 days before the step-up price takes effect. Therefore, in this scenario, if the free trial period is for 40 days, then the consent period would start on March 13 and end on April 12.

#### Example 3: User consents to the price step-up during the free trial

On March 3, a user signs up for a subscription in South Korea with a
free trial period of 10 days. The user consents to the price
step-up during the free trial. The following is the sequence of events in
this scenario:
![](https://developer.android.com/static/images/google/play/billing/price-stepup-example-3.png) **Figure 10.** Example timeline diagram when a user doesn't consents to the price step-up during a free trial.

#### Example 4: User doesn't consent to the price step-up for an introductory offer

On March 3, a user signs up for a subscription in South Korea with an
introductory price period of 60 days. The user doesn't consent to
the price step-up during the signup. The following is the sequence of
events in this scenario:
![](https://developer.android.com/static/images/google/play/billing/price-stepup-example-4.png) **Figure 11.** Example timeline diagram when a user doesn't consent to the price step-up during an introductory offer.

#### Example 5: User consents to the price step-up during both
free trial and introductory offer

If you are offering a subscription for both free trial and an
introductory offer, Play asks for user consent at the following events:

1. During the free trial period, Play asks for the user's consent to move from free trial to introductory price.
2. If the user consents during the free trial, then during the introductory price period, Play asks for the user's consent to move from the introductory price to the regular price.

For example, on March 3, a user signs up for a subscription in South Korea with a
free trial period of 10 days and an introductory price period of 30 days.
The user consents to the price step-up during both the free trial
and the introductory offer. The following is the sequence of events in
this scenario:
![](https://developer.android.com/static/images/google/play/billing/price-stepup-example-5.png) **Figure 12.** Example timeline diagram when a user consents to the price step-up during both free trial and an introductory offer.