| page.title=In-App Subscriptions |
| parent.title=In-app Billing |
| parent.link=index.html |
| page.metaDescription=Subscriptions let you sell content or features in your app with automated, recurring billing. |
| page.image=/images/play_dev.jpg |
| page.tags="subscriptions, billing, inapp, iap" |
| meta.tags="monetization, inappbilling, subscriptions" |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>Quickview</h2> |
| <ul> |
| <li>Subscriptions let you sell products with automated, recurring billing |
| at a variety of intervals.</li> |
| <li>You can offer a configurable trial period for monthly and |
| annual subscriptions.</li> |
| <li>You can manage subscriptions through the Developer Console, or by using |
| the |
| <a href="https://developers.google.com/android-publisher/">Google Play |
| Developer API</a>.</li> |
| <li>Users purchase your subscriptions from inside your apps, rather than |
| directly from Google Play.</li> |
| <li>You can defer billing for a particular user's subscription, to manage |
| accounts or offer rewards.</li> |
| </ul> |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#overview">Overview of Subscriptions</a></li> |
| <li><a href="#administering">Configuring Subscriptions Items</a></li> |
| <li><a href="#cancellation">Subscription Cancellation</a></li> |
| <li><a href="#payment">Payment Processing and Policies</a></li> |
| <li><a href="#strategies">Purchase Verification Strategies</a></li> |
| <li><a href="#play-dev-api">Google Play Developer API</a></li> |
| </ol> |
| <h2>See also</h2> |
| <ol> |
| <li><a href="{@docRoot}google/play/billing/billing_integrate.html#Subs">Implementing Subscriptions (V3)</a></li> |
| <li><a href="https://developers.google.com/android-publisher/">Google Play Developer API</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p>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.</p> |
| <p>This document is focused on highlighting implementation details that are |
| specific to subscriptions, along with some strategies for the associated billing |
| and business models.</p> |
| |
| <h2 id="overview">Overview of Subscriptions</h2> |
| <p>A <em>subscription</em> 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.</p> |
| |
| <p>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 |
| <a href="#administering">Configuring Subscription Items</a>.</p> |
| |
| <p>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 Wallet, just as it does for standard in-app products and app purchases. |
| This ensures a consistent and familiar purchase flow for your users.</p> |
| |
| <img src="{@docRoot}images/in-app-billing/v3/billing_subscription_v3.png" style="float:right; border:4px solid ddd;"> |
| |
| <p>After users have purchased subscriptions, they can view the subscriptions and |
| cancel them from the <strong>My Apps</strong> 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 <a href="#cancellation">Subscription Cancellation</a>.</p> |
| |
| <p>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 <a |
| href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google Play Developer API</a>. </p> |
| |
| <p>You can also build on your existing external subscriber base from inside your |
| Android apps.</p> |
| <ul> |
| <li>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.</li> |
| <li>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.</li> |
| </ul> |
| </p> |
| |
| <p>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 <a |
| href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en |
| &answer=140504">policies document</a>.</p> |
| |
| <p>To learn about the minimum system requirements for |
| subscriptions, see the <a href="{@docRoot}google/play/billing/versions.html#Subs">Version Notes</a>.</p> |
| |
| <h2 id="administering">Configuring Subscription Items</h2> |
| |
| <p>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:</p> |
| |
| <ul> |
| <li>Purchase Type: always set to <strong>Subscription</strong></li> |
| <li>Subscription ID: An identifier for the subscription</li> |
| <li>Publishing State: Unpublished/Published</li> |
| <li>Language: The default language for displaying the subscription</li> |
| <li>Title: The title of the subscription product</li> |
| <li>Description: Details that tell the user about the subscription</li> |
| <li>Price: Default price of subscription per recurrence</li> |
| <li>Recurrence: Interval of billing recurrence</li> |
| <li>Additional currency pricing (can be auto-filled)</li> |
| </ul> |
| |
| <p>For details on how to add and configure products in the Developer Console, |
| see <a href="{@docRoot}google/play/billing/billing_admin.html">Administering |
| In-app Billing</a>.</p> |
| |
| <p>You can also create and manage subscriptions using the |
| <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html"> |
| Google Play Developer API</a>.</p> |
| |
| <h3 id="pricing">Subscription pricing</h3> |
| |
| <p>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. </p> |
| |
| <p class="caution"><strong>Important</strong>: 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.</p> |
| |
| <h3 id="user-billing">User billing</h3> |
| |
| <p>In the Developer Console, you can configure subscription products with |
| automated recurring billing at your choice of intervals:</p> |
| |
| <ul> |
| <li>Monthly — Google Play bills the customer’s Google Wallet account at |
| the time of purchase and monthly subsequent to the purchase date (exact billing |
| intervals can vary slightly over time).</li> |
| <li>Annually — Google Play bills the customer's Google Wallet account at |
| the time of purchase and again on the same date in subsequent years.</li> |
| |
| <li>Seasonal — Google Play bills the customer's Google Wallet 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.</li> |
| |
| </ul> |
| |
| <p>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.)</p> |
| |
| <p>Over the life of a subscription, the form of payment billed remains the same |
| — Google Play always bills the same form of payment (such as credit card |
| or by Direct Carrier Billing) that was originally used to purchase the |
| subscription.</p> |
| |
| <p>When the subscription payment is approved by Google Wallet, 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 |
| <a |
| href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google Play Developer API</a>.</p> |
| |
| <p>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:</p> |
| <ul> |
| <li>With In-app Billing Version 3, the failed or expired subscription is no longer |
| returned when you call {@code getPurchases}.</li> |
| <li>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". |
| </li> |
| </ul> |
| |
| <p class="note"><strong>Recommendation</strong>: 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.</p> |
| |
| <h3 id="deferred-billing">Deferred Billing</h3> |
| |
| <p>Using the |
| <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google |
| Play Developer API</a>, 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:</p> |
| |
| <ul> |
| <li>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)</li> |
| <li>Give free access to customers as a goodwill gesture</li> |
| </ul> |
| |
| <p>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.</p> |
| |
| <p>For example, Darcy has a monthly subscription to online content for the |
| <em>Fishing Gentleman</em> 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.</p> |
| |
| <p class="note"><strong>Note:</strong> 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.</p> |
| |
| <p>You can also offer free trials to new subscribers, as described in |
| <a href="#trials">Free trials</a>.</p> |
| |
| <h3 id="trials">Free trials</h3> |
| |
| <p>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.</p> |
| |
| <p>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. </p> |
| |
| <p>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 <em>marks the subscription as expired immediately</em>, |
| 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.</p> |
| |
| <p>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.</p> |
| |
| <h3 id="publishing">Subscription publishing</h3> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>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. </p> |
| |
| <p class="caution"><strong>Important</strong>: You can remove the subscription |
| product from the product list offered in your app to prevent users from seeing |
| or purchasing it.</p> |
| |
| <h2 id="cancellation">Subscription Cancellation</h2> |
| |
| <p>Users can view the status of all of their subscriptions and cancel them if |
| necessary from the <strong>My Apps</strong> 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.</p> |
| |
| <p>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 |
| cancelled 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).</p> |
| |
| <p>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. |
| |
| <p class="caution"><strong>Important:</strong> 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 <a href="#refunds">refund |
| and revoke</a> 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 <a |
| href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies document</a> for more information. </p> |
| |
| <h3 id="uninstall">App uninstallation</h3> |
| |
| <p>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 <strong>My Apps</strong> |
| screen of the Play Store app. If the user chooses to cancel the uninstallation, |
| the app and subscriptions remain as they were.</p> |
| |
| <h3 id="refunds">Refunding and revoking subscriptions</h3> |
| |
| <p>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 <strong>My |
| Orders</strong> page in the Play Store, or by contacting you directly.</p> |
| |
| <p>If you receive requests for refunds, you can use the |
| <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google Play |
| Developer API</a> or the Merchant Center to cancel the subscription, verify that it |
| is already cancelled, or refund the user's payment without cancelling it. You |
| can also use the |
| <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google |
| Play Developer API</a> to <em>refund and revoke</em> a |
| user's subscription. If you refund and revoke a subscription, the user's |
| subscription is immediately cancelled, 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.)</p> |
| |
| <p class="caution"><strong>Important:</strong> Partial refunds are not available |
| at this time.</p> |
| |
| <h2 id="payment">Payment Processing and Policies</h2> |
| |
| <p>In general, the terms of Google Play allow you to sell in-app subscriptions |
| only through the standard payment processor, Google Wallet. For purchases of |
| any subscription products, the transaction fee is the same as the transaction |
| fee for application purchases (30%).</p> |
| |
| <p>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).</p> |
| |
| <p>For complete details about terms and policies, see the <a |
| href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies |
| document</a>.</p> |
| |
| <h3 id="orderId">Subscription order numbers</h3> |
| |
| <p>To help you track transactions relating to a given subscription, Google |
| Wallet provides a base Merchant Order Number for all recurrences of the |
| subscription and denotes |
| each recurring transaction by appending an integer as follows: </p> |
| |
| <p><span style="color:#777"><code style="color:#777">12999556515565155651.5565135565155651</code> (base order number)</span><br /> |
| <code>12999556515565155651.5565135565155651..0</code> (first recurrence orderID)<br /> |
| <code>12999556515565155651.5565135565155651..1</code> (second recurrence orderID)<br /> |
| <code>12999556515565155651.5565135565155651..2</code> (third recurrence orderID)<br /> |
| ...<br /></p> |
| |
| <p>Google Play provides the order number as the value of the |
| {@code orderId} field of the {@code INAPP_PURCHASE_DATA} JSON field (in V3) |
| or the {@code PURCHASE_STATE_CHANGED} intent (in V2).</p> |
| |
| <h2 id="strategies">Purchase Verification Strategies</h2> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <h2 id="play-dev-api">Google Play Developer API</h2> |
| |
| <p>Google Play offers an HTTP-based API that lets you perform such tasks as:</p> |
| <ul> |
| <li>Remotely query the validity of a specific subscription at any time</li> |
| <li>Cancel a subscription</li> |
| <li>Defer a subscription's next billing date</li> |
| <li>Refund a subscription payment without cancelling the subscription</li> |
| <li>Refund and revoke a subscription</li> |
| </ul> |
| |
| <p>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.</p> |
| |
| <p>For complete information, see |
| <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google Play |
| Developer API</a>.</p> |