In-app Subscriptions

Subscriptions let you sell content, services, or features in your app with automated, recurring billing. You can easily adapt an existing In-app Billing implementation to sell subscriptions.

This document is focused on highlighting implementation details that are specific to subscriptions, along with some strategies for the associated billing and business models.

  • Subscriptions let you sell products with automated, recurring billing at a variety of intervals.
  • You can offer a configurable trial period for monthly and annual subscriptions.
  • You can manage subscriptions through the Play Console, or by using the Google Play Developer API.
  • Users purchase your subscriptions from inside your apps, rather than directly from Google Play.
  • Users can renew their subscriptions while a current subscription is active.
  • Users can upgrade or downgrade a subscription in the middle of a subscription period. The old subscription's cost is pro-rated, and the unused portion is applied to the replacement subscription.
  • You can defer billing for a particular user's subscription, to manage accounts or offer rewards.


A subscription is a product type offered in In-app Billing that lets you sell content, services, or features to users from inside your app with recurring, automated billing at the interval you specify. You can sell subscriptions to almost any type of digital content, from any type of app or game.

As with other in-app products, you configure and publish subscriptions using the Play Console and then sell them from inside apps installed on Android devices. In the Play Console, you create subscription products and add them to a product list, then set a price and optional trial period for each, choose a billing interval, and then publish. For more information about using the Play Console, see Configuring Subscription Items.

When users purchase subscriptions in your apps, Google Play handles all checkout details so your apps never have to directly process any financial transactions. Google Play processes all payments for subscriptions through Google payments, just as it does for standard in-app products and app purchases. This ensures a consistent and familiar purchase flow for your users.

After users have purchased subscriptions, they can view the subscriptions and cancel them from the My Apps screen in the Play Store app or from the app's product details page in the Play Store app. For more information about handling user cancellations, see Subscription Cancellation.

In addition to client-side API calls, you can use the server-side API for In-app Billing to provide subscription purchasers with extended access to content (for example, from your web site or another service). The server-side API lets you validate the status of a subscription when users sign into your other services. For more information about the API, see Google Play Developer API.

You can also build on your existing external subscriber base from inside your Android apps.

  • If you sell subscriptions on a web site, for example, you can add your own business logic to your Android app to determine whether the user has already purchased a subscription elsewhere, then allow access to your content if so or offer a subscription purchase from Google Play if not.
  • You can implement your own solution for sharing subscriptions across as many different apps or products as you want. For example, you could sell a subscription that gives a subscriber access to an entire collection of apps, games, or other content for a monthly or annual fee. To implement this solution, you could add your own business logic to your app to determine whether the user has already purchased a given subscription and if so, allow access to your content.

In general the same basic policies and terms apply to subscriptions as to standard in-app products, however there are some differences. For complete information about the current policies and terms, please read the policies document.

To learn about the minimum system requirements for subscriptions, see the Version Notes.

Configuring Subscription Items

To create and manage subscriptions, you can use the Play Console to set up a product list for the app, then configure these attributes for each subscription product:

  • Purchase Type: always set to Subscription
  • Subscription ID: An identifier for the subscription
  • Publishing State: Unpublished/Published
  • Language: The default language for displaying the subscription
  • Title: The title of the subscription product
  • Description: Details that tell the user about the subscription
  • Price: Default price of subscription per recurrence
  • Recurrence: Interval of billing recurrence
  • Additional currency pricing (can be auto-filled)

For details on how to add and configure products in the Play Console, see Administering In-app Billing.

You can also create and manage subscriptions using the Google Play Developer API.

Subscription pricing

When you create a subscription in the Play Console, you can set a price for it in any available currencies. Each subscription must have a non-zero price. You can price multiple subscriptions for the same content differently — for example you could offer a discount on an annual subscription relative to the monthly equivalent.

Important: To change the price of a subscription, you can publish a new subscription product ID at a new price, then offer it in your app instead of the original product. Users who have already purchased will continue to be charged at the original price, but new users will be charged at the new price.

User billing

In the Play Console, you can configure subscription products with automated recurring billing at your choice of intervals:

  • Weekly — Google Play bills the customer’s Google payments account at the time of purchase and every week after the original purchase date.
  • Monthly — Google Play bills the customer’s Google payments account at the time of purchase and monthly subsequent to the purchase date (exact billing intervals can vary slightly over time).
  • 3 Months — Google Play bills the customer’s Google payments account at the time of purchase and every three months after that (exact billing intervals can vary slightly over time).
  • 6 Months — Google Play bills the customer’s Google payments account at the time of purchase and every six months after that (exact billing intervals can vary slightly over time).
  • Annually — Google Play bills the customer's Google payments account at the time of purchase and again on the same date in subsequent years.
  • Seasonal — Google Play bills the customer's Google payments account at the beginning of each "season" (you specify the season beginning and end dates). This is intended for annual purchases of seasonal content (such as sports-related content). The subscription runs through the end of the season, and restarts the next year at the start of the season.

Billing continues indefinitely at the interval and price specified for the subscription. At each subscription renewal, Google Play charges the user account automatically, then notifies the user of the charges afterward by email. For monthly and annual subscriptions, billing cycles will always match subscription cycles, based on the purchase date. (Seasonal subscriptions are charged annually, on the first day of the season.)

When the subscription payment is approved, Google Play provides a purchase token back to the purchasing app through the In-app Billing API. Your apps can store the token locally or pass it to your backend servers, which can then use it to validate or cancel the subscription remotely using the Google Play Developer API.

If a recurring payment fails (for example, because the customer’s credit card has become invalid), the subscription does not renew. The getPurchases() method does not return failed or expired subscriptions.

Recommendation: Include business logic in your app to notify your backend servers of subscription purchases, tokens, and any billing errors that may occur. Your backend servers can use the server-side API to query and update your records and follow up with customers directly, if needed.

Manual Renewal

With the In-app Billing API, users can renew a subscription during its active period even if the subscription is not set to automatically renew. If the user purchases a subscription while the subscription is active, it is extended by the appropriate period at the current rate.

For example, Achilles has a subscription to the Modern Hoplite app. His subscription is currently due to expire on August 1. On July 10, he purchases a 1-month subscription at the current rate. This one month is added to his existing subscription, so the subscription now expires on September 1.

It is up to the app to convey this with an appropriate UI. For example, if a user does not have an active subscription, the app might have a buy button, but if the user has a subscription the button might say renew.

Subscription Upgrade/Downgrade

With the In-app Billing API, users can upgrade or downgrade a subscription during its active period. When the user does this, the active subscription is canceled and a new subscription is created. The unused balance of the old subscription is applied on a pro-rated basis to the new subscription. The first billing period for the new subscription begins after that balance is used up. (The new subscription does not need to have a period of the same length as the old one.)

For example, Samwise has a subscription to online content from the Country Gardener app. He currently has a monthly subscription to the Tier 1 version of the content (which has text-only content). This subscription costs him £2/month, and renews on the first of the month. On April 15, he chooses to upgrade to the Tier 2 subscription (which includes video updates), costing £3/month. His Tier 1 subscription is immediately ended. Since he paid for a full month (April 1-30), but only used half of it, half of a month's subscription (£1) is applied to his new subscription. However, since that new subscription costs £3/month, the £1 credit balance only pays for ten days. So Samwise's credit pays for his subscription from April 15-25. On April 26, he is charged £3 for his new subscription, and another £3 on the 26th of each month following.

Note: The new subscription's billing date depends on when the subscriber's pro-rated credit runs out, so the subscriber cannot upgrade or downgrade to a seasonal subscription, which has fixed and predetermined beginning and end dates.

When a user upgrades or downgrades a subscription, your app calls getBuyIntentExtraParams(). This method is passed the new SKU the user wants to buy, and all the old SKUs that are superseded by it.

Deferred Billing

Using the Google Play Developer API, you can defer the next billing date for a subscriber. The user continues to be subscribed to the content, and has full access to it, but is not charged during the deferral period. This allows you to do things like:

  • Give users free access as part of a bundle or a special offer (for example, giving free access to web content to users who subscribe to a print magazine)
  • Give free access to customers as a goodwill gesture

The longest you can defer billing is for one year per call. Of course, you can call the API again before the year is up to defer billing further.

For example, Darcy has a monthly subscription to online content for the Fishing Gentleman app. He is normally billed £1.25 on the first of each month. On March 10, he participates in an online survey for the app publisher. The publisher rewards him by deferring his next payment until June 1. Darcy is not charged on April 1 or May 1, but still has access to the content as normal. On June 1, he is charged his normal £1.25 subscription fee.

Note: The API always defers the billing date by a whole number of days. If you request a deferral period that includes a fractional number of days, the API rounds the period up to the next full day. For example, if a user's subscription is set to renew on 15 June 2015 at 14:00:00 UTC, and you use the API to defer the renewal date to 15 August 2015 at 02:00:00 UTC, the API will round up to the next full day and set the renewal date to 15 August 2015 14:00:00 UTC.

You can also offer free trials to new subscribers, as described in Free trials.

Free trials

In the Play Console, you can set up a free trial period that lets users try your subscription content before buying it. The trial period runs for the period of time that you set and then automatically converts to a full subscription managed according to the subscription's billing interval and price. Google Play supports free trials for all subscription types, including seasonal subscriptions.

To take advantage of a free trial, a user must "purchase" the full subscription through the standard In-app Billing flow, providing a valid form of payment to use for billing and completing the normal purchase transaction. However, the user is not charged any money, because the initial period corresponds to the free trial. Instead, Google Play records a transaction of $0.00 and the subscription is marked as purchased for the duration of the trial period or until cancellation. When the transaction is complete, Google Play notifies users by email that they have purchased a subscription that includes a free trial period and that the initial charge was $0.00.

When the trial period ends, Google Play automatically initiates billing against the credit card that the user provided during the initial purchase, at the amount set for the full subscription, and continuing at the subscription interval. If necessary, the user can cancel the subscription at any time during the trial period. In this case, the subscription remains active until the end of the trial period, but Google Play sets the subscription not to renew automatically; at the end of the trial period the subscription expires, and Google Play does not charge the user.

You can set up a trial period for a subscription in the Play Console, without needing to modify or update your APK. Just locate and edit the subscription in your product list, set a valid number of days for the trial (must be 3 days or longer), and publish. You can change the period any time, although note that Google Play does not apply the change to users who have already "purchased" a trial period for the subscription. Only new subscription purchases will use the updated trial period. You can create one free trial period per subscription product.

A user can only receive one free trial across all available subscription products in your app. You can choose to allow a user to receive a free trial once for each available subscription product by completing the following steps:

  1. Log into the Google Play Console.
  2. Select your app, then navigate to Store presence > In-app products.
  3. Select the Subscriptions tab, then expand the Subscription settings section.
  4. Check the Activate subscription-level free trial checkbox that appears.

Introductory pricing

The Play Console also allows you to enable introductory pricing as a way to incentivize users to try your product. You can select a duration equal to a number of billing periods, or in terms of days, weeks, or months. The duration must be at least 3 days, but no more than 12 months.

Subscription publishing

When you have finished configuring your subscription product details in the Play Console or via the API, you can publish the subscription in the app product list.

In the product list, you can add subscriptions, in-app products, or both. You can add multiple subscriptions that give access to different content or services, or you can add multiple subscriptions that give access to the same content but for different intervals or different prices, such as for a promotion. For example, a news outlet might decide to offer both monthly and annual subscriptions to the same content, with annual having a discount. You can also offer in-app purchase equivalents for subscription products, to ensure that your content is available to users of older devices that do not support subscriptions.

After you add a subscription or in-app product to the product list, you must publish the product before Google Play can make it available for purchase. Note that you must also publish the app itself before Google Play will make the products available for purchase inside the app.

Important: You can remove the subscription product from the product list offered in your app to prevent users from seeing or purchasing it.

Prorated Seasonal Subscription Prices

You can set up prorated prices for users who buy seasonal subscriptions after the season's start date. You specify the date on which the discounted price takes effect. The discounted price takes effect at 0:00 UTC on the specified date. You can set multiple prorated prices, dropping the subscription price lower and lower as the season goes on. If a user purchases a prorated seasonal subscription and remains subscribed until the start of the next season, Google Play charges them the full subscription price when the next season starts.

For example, the professional checkers season runs from March 1 to August 31. The Checkers Dilettante app offers a seasonal subscription for €10. The app also offers two prorated prices: €7.50 for users who sign up on or after June 1, and €5 for users who sign up on or after August 15. Regardless of when the user signs up, the seasonal subscription ends on August 31.

Real-time Developer Notifications

The In-app Billing API provides server push notifications that give developers the capability to monitor state changes for Play-managed subscriptions. To enable this capability, you will need to integrate your backend with Cloud Pub/Sub using your own Google Cloud Platform (GCP) project, and fill in Google Play Console the Pub/Sub topic to which Play should publish notifications. Using Real-time Developer Notifications you will be able to be more proactive with your users and increase your engament to reduce churn, for example.

After preparing your back-end to receive Real-time Developer Notifications, you will be notified when one of the following events happen:

  • A new subscription is purchased.
  • Renewal.
  • Recovered, when the user was on hold.
  • Canceled.
  • On hold, sent once when the user enters on hold (if enabled).
  • In grace period, sent when the user enters grace period (if enabled).
  • Restarted, sent when the user reactivates their subscription from the Play Store (requires subscription restore opt-in from Play Console. See Subscription restore for more details).

Due to the variety of notifications that can potentially be sent to the Pub/Sub topic, you can take advantage of the Google Stackdriver, a monitoring, logging, and diagnostics tool. Stackdriver will allow you to monitor traffic on a topic and set up alerts for certain conditions. Check the Real-time Developer Notifications section for implementation details.

Subscription Cancellation

Users can view the status of all of their subscriptions and cancel them if necessary from the My Apps screen in the Play Store app. Currently, the In-app Billing API does not provide support for programmatically canceling subscriptions from inside the purchasing app.

When the user cancels a subscription, Google Play does not offer a refund for the current billing cycle. Instead, it allows the user to have access to the canceled subscription until the end of the current billing cycle, at which time it terminates the subscription. For example, if a user purchases a monthly subscription and cancels it on the 15th day of the cycle, Google Play will consider the subscription valid until the end of the 30th day (or other day, depending on the month).

In some cases, the user may contact you directly to request cancellation of a subscription. In this and similar cases, you can use the server-side API to query and directly cancel the user’s subscription from your servers.

Important: In all cases, you must continue to offer the content that your subscribers have purchased through their subscriptions, as long any user is able to access it. That is, you must not remove any content while any user still has an active subscription to it, even if that subscription will terminate at the end of the current billing cycle. Alternatively, you can use the refund and revoke API to revoke each subscriber's subscription (one by one) and refund their subscription payments. Removing content that any subscriber is entitled to access will result in penalties. Please see the policies document for more information.

Subscription restore

After a user cancels a subscription, the subscription is still active until the expiration date. Thus it stays visible in the Play Store app until the subscription expires. After the user cancels, but before it expires, the user is able to restore the access to the subscription by clicking the RESTORE button in the Account > Subscriptions section in the Play Store app.

Figure 1. Account > Subscriptions section in the Play Store app

To detect when a subscription is restored, you can follow two different ways:

  1. Act upon SUBSCRIPTION_RESTARTED notification. Check more details on the page Real-time Developer Notifications.
  2. Use the getPurchases() method each time the application is opened. Note that once restored, the purchaseToken will be identical to what it was before the subscription was canceled.

After preparing your app for subscription restore, you can enable the feature by completing the following steps:

  1. Log into the Google Play Console.
  2. Select your app, then navigate to Store presence > In-app products.
  3. On this page, select the Subscriptions tab, then expand the Subscription settings section.
  4. Check the Allow users to restore subscriptions in Google Play checkbox that appears, as shown in Figure 2, then click Save.
    Figure 2. Locating the Activate subscription restore checkbox in the Google Play Console

App uninstallation

When the user uninstalls an app that includes purchased subscriptions, the Play Store app will notify the user that there are active subscriptions. If the user chooses to continue with the uninstallation, the app is removed and the subscriptions remain active and recurring billing continues. The user can return to cancel the associated subscriptions at any time in the My Apps screen of the Play Store app. If the user chooses to cancel the uninstallation, the app and subscriptions remain as they were.

Refunding and revoking subscriptions

With subscriptions, Google Play does not provide a refund window, so users will need to request a refund. They can request a refund from the My Orders page in the Play Store, or by contacting you directly.

If you receive requests for refunds, you can use the Google Play Developer API or the Merchant Center to cancel the subscription, verify that it is already canceled, or refund the user's payment without canceling it. You can also use the Google Play Developer API to refund and revoke a user's subscription. If you refund and revoke a subscription, the user's subscription is immediately canceled, and the user's most recent subscription payment is refunded. (If you want to refund more than the most recent payment, you can process additional refunds through the Merchant Center.)

Important: Partial refunds are not available at this time.

Payment Processing and Policies

In general, the terms of Google Play allow you to sell in-app subscriptions only through the standard payment processor, Google payments. For purchases of any subscription products, the transaction fee is 30% for the first 12 paid months and reduced to 15% for any subscribers you retain after 12 paid months.

Apps published on Google Play that are selling subscriptions must use In-app Billing to handle the transaction and may not provide links to a purchase flow outside of the app and Google Play (such as to a web site).

For complete details about terms and policies, see the policies document.

Subscription order numbers

To help you track transactions relating to a given subscription, Google payments provides a base Merchant Order Number for all recurrences of the subscription and denotes each recurring transaction by appending an integer as follows:

GPA.1234-5678-9012-34567 (base order number)
GPA.1234-5678-9012-34567..0 (first recurrence orderID)
GPA.1234-5678-9012-34567..1 (second recurrence orderID)
GPA.1234-5678-9012-34567..2 (third recurrence orderID)

Google Play provides the order number as the value of the orderId field of the INAPP_PURCHASE_DATA JSON field (in V3) or the PURCHASE_STATE_CHANGED intent (in V2).

Grace period for declined payments

The Play Console allows you to set a grace period for subscriptions, so you can give your subscribers a chance to update their payment method if a recurring payment is declined. This setting is useful if your subscribers have an expired credit card, subscribed using a prepaid card, or canceled a card without updating their payment information. For information about setting a grace period for subscriptions, see the Play Console Help topic Add subscriptions & recurring charges.

For information on how setting a grace period affects data returned from the getBuyIntent() method, see the INAPP_PURCHASE_DATA fields table.

Account holds for declined payments

In the Google Play Console, you can add account hold support for your app. This feature helps resolve problems with a user's subscription renewal payment. If a subscription renewal payment issue occurs after the grace period has expired, perform one of the following actions, based on whether your app supports the account hold capability:

  • If your app includes account hold support, your app should block a user's access to the subscribed content when the user's account goes on hold. If the subscription is recovered, your app should restore access to the subscribed content. However, if the subscription cannot be recovered during this hold period, the subscription is canceled, and the user must purchase a new subscription.
  • If your app doesn't include account hold support, Google Play cancels the subscription immediately after the grace period ends.

Note: When an account goes on hold, you should deny access to the features that your app's subscription enables, and you should explain to the user that they need to fix their payment issue. After the account comes off hold, you should restore access to the subscribed features.

Before activating the account holds feature, you need to prepare your system to support the feature:

  • Preserve all information about your app's subscriptions on your app's backend server, as a given subscription isn't canceled during an account hold. That way, you can reinstate the subscription if Google Play removes the account hold before canceling the subscription.
  • Call getPurchases() each time the user opens your app. That way, you can detect when a user fixes their subscription payment issue, and you can immediately provide that user with access to the subscribed content. During an account hold, neither the Android In-app Billing API nor the Google Play Developer API lists the subscription as active.
  • Check the value of purchaseToken when the subscription is recovered. Typically, the purchaseToken is identical to what it was before the user's account hold started. It's possible, however, that the user regained access to the subscribed content by repurchasing the subscription during the hold period. In that case, a new purchaseToken value is returned to represent the new instance of the subscription.

After preparing your system for the account holds feature, you can enable the feature by completing the following steps:

  1. Log into the Google Play Console.
  2. Select your app, then navigate to Store presence > In-app products.
  3. On this page, select the Subscriptions tab, then expand the Subscription settings section.
  4. Check the Activate account hold checkbox that appears, as shown in Figure 3, then click Save.

    Figure 3. Locating the Activate account hold checkbox in the Google Play Console

The account hold period lasts 30 days, but even during this time period, you should check whether the user's subscription within your app has been canceled, restored, or repurchased. To verify that the user is still on hold, you should check the user's current subscription status whenever a user who is currently on hold attempts to access the subscribed content in your app.

If you're using the Google Play Developer API to query a subscription's details, the contents of the JSON response vary depending on the state of the subscription, as shown in the following snippets.

Result from a query for a subscription during an account hold:

  "kind": "androidpublisher#subscriptionPurchase",
  "expiryTimeMillis": timestamp_in_past,
  "autoRenewing": true,
  "paymentState": 0  # Payment pending

Result from a query for a subscription following an account hold during which the subscription was recovered:

  "kind": "androidpublisher#subscriptionPurchase",
  "expiryTimeMillis": timestamp_in_future,
  "autoRenewing": true,
  "paymentState": 1  # Payment received

Result from a query for the subscription following an account hold during or after which the subscription was canceled:

  "kind": "androidpublisher#subscriptionPurchase",
  "expiryTimeMillis": timestamp_in_past,
  "autoRenewing": false,
  "cancelReason": 1  # The system canceled the subscription

Mitigating Impact of VAT on Subscriptions

It is not possible to change the price of an existing subscription SKU. Thus, when a country or region launches a VAT/GST/Tax initiative with inclusive pricing, this change impacts developer margin. Similarly, if a region moves from tax-exclusive pricing to tax-inclusive pricing, the end user effectively receives a discount on pricing commensurate with the tax rate. The main way to maintain the desired price point that reflects the legacy SKU price + tax, is to create a new SKU. Although a new SKU can be created at that new price point and sold to new subscribers, there is no way to automatically migrate existing users to a new sku.

The following sections introduce some mitigation strategies that developers can adopt:

Deactivate sku at lower price point

There is no way to deactivate a subscription SKU once it has gone live. However, users can only purchase a given sku if the developer exposes a purchase flow for it in the app. There is no client-side call to get all skus for a given app, so the solution here is simply to no longer surface the legacy sku to new users.

Migrate existing users

The user must perform this process on the client side. Developers need to build a purchase flow for existing users so that they may transition from the legacy sku to the new price point via the getBuyIntentExtraParams method. The replaceSkusProration value should be set to true so that users receive credit for any existing balance on the legacy subscription. It is recommended that developers notify users within the app that their existing subscription plan is coming to an end and that they need to migrate to the new plan.

End-of-life legacy subscription service

There are effectively three options for mitigating the impact of VAT on subscriptions:

  1. Do nothing (a.k.a grandfathering). Continue to deliver the same experience to the users who are on the legacy sku. Consider surfacing an occasional nudge for them to upgrade to the new sku.
  2. Reduce services. If feasible provide a lower tier of content/service commensurate with the impact of the tax change. Continue to notify users that if they wish to retain full access to the service, they need to migrate to the new price-point plan.
  3. Force migration. Use the Purchases.subscriptions cancel API to stop auto-renewing for all users on the legacy sku. Notify users within the app that the sku to which they had a subscription is no longer available and encourage them to migrate to the new sku to retain access at the end of their current period.

Grandfathering retains all users but results in a known reduction of revenue in proportion to the tax impact, whereas forced migration may result in significant user churn. Which approach, or combination of approaches, to take is left as a business decision for each developer.

Purchase Verification Strategies

In a typical scenario, your app verifies the order status for new purchases to ensure that they are valid before granting access to the purchased content.

To verify a purchase, the app passes the purchase token and other details up to your backend servers, which verifies them directly with Google Play using the Google Play Developer API. If the backend server determines that the purchase is valid, it notifies the app and grants access to the content.

Keep in mind that users will want the ability to use your app at any time, including when there may be no network connection available. Make sure that your approach to purchase verification accounts for the offline use-case.

Google Play Developer API

Google Play offers an HTTP-based API that lets you perform such tasks as:

  • Remotely query the validity of a specific subscription at any time
  • Cancel a subscription
  • Defer a subscription's next billing date
  • Refund a subscription payment without canceling the subscription
  • Refund and revoke a subscription

The API is designed to be used from your backend servers as a way of securely managing subscriptions, as well as extending and integrating subscriptions with other services.

For complete information, see Google Play Developer API.