In-app Subscriptions

Quickview

In this document

Overview
Configuring Subscriptions Items
Subscription Cancellation
Payment Processing and Policies
Purchase Verification Strategies
Google Play Developer API

Overview

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 Developer Console and then sell them from inside apps installed on Android devices. In the Developer 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 Developer 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 Developer 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 Developer 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 Developer 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 Developer 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).
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. How your app is notified depends on the In-app Billing API version that you are using:

With In-app Billing Version 3, the failed or expired subscription is no longer returned when you call getPurchases.
With In-app Billing Version 2, Google Play notifies your app at the end of the active cycle that the purchase state of the subscription is now "Expired".

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 version 5 of 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 version 5 of 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 getBuyIntentToReplaceSkus(). This method is passed the new SKU the user wants to buy, and all the old SKUs that are superseded by it. The remaining portions of the old SKUs are used to pay for the new subscription, and billing begins when this credit is used up.

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 Developer 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. Free trials are supported for monthly and annual subscriptions only, and are not supported for 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, Google Play marks the subscription as expired immediately, rather than waiting until the end of the trial period. The user has not paid for the trial period and so is not entitled to continued access after cancellation.

You can set up a trial period for a subscription in the Developer 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 7 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.

Subscription publishing

When you have finished configuring your subscription product details in the Developer 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.

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 programatically 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.

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 the same as the transaction fee for application purchases (30%).

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:

12999556515565155651.5565135565155651 (base order number)
12999556515565155651.5565135565155651..0 (first recurrence orderID)
12999556515565155651.5565135565155651..1 (second recurrence orderID)
12999556515565155651.5565135565155651..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 Developer 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 Developer 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.

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.

Results