1page.title=In-App Subscriptions 2parent.title=In-app Billing 3parent.link=index.html 4page.metaDescription=Subscriptions let you sell content or features in your app with automated, recurring billing. 5page.image=/images/play_dev.jpg 6page.tags="subscriptions, billing, inapp, iap" 7meta.tags="monetization, inappbilling, subscriptions" 8@jd:body 9 10<div id="qv-wrapper"> 11<div id="qv"> 12 <h2>Quickview</h2> 13 <ul> 14 <li>Subscriptions let you sell products with automated, recurring billing 15 at a variety of intervals.</li> 16 <li>You can offer a configurable trial period for monthly and 17 annual subscriptions.</li> 18 <li>You can manage subscriptions through the Developer Console, or by using 19 the 20 <a href="https://developers.google.com/android-publisher/">Google Play 21 Developer API</a>.</li> 22 <li>Users purchase your subscriptions from inside your apps, rather than 23 directly from Google Play.</li> 24 <li>You can defer billing for a particular user's subscription, to manage 25 accounts or offer rewards.</li> 26 </ul> 27 <h2>In this document</h2> 28 <ol> 29 <li><a href="#overview">Overview of Subscriptions</a></li> 30 <li><a href="#administering">Configuring Subscriptions Items</a></li> 31 <li><a href="#cancellation">Subscription Cancellation</a></li> 32 <li><a href="#payment">Payment Processing and Policies</a></li> 33 <li><a href="#strategies">Purchase Verification Strategies</a></li> 34 <li><a href="#play-dev-api">Google Play Developer API</a></li> 35 </ol> 36 <h2>See also</h2> 37 <ol> 38 <li><a href="{@docRoot}google/play/billing/billing_integrate.html#Subs">Implementing Subscriptions (V3)</a></li> 39 <li><a href="https://developers.google.com/android-publisher/">Google Play Developer API</a></li> 40 </ol> 41</div> 42</div> 43 44<p>Subscriptions let you sell content, services, or features in your app with 45automated, recurring billing. You can easily adapt an existing In-app Billing 46implementation to sell subscriptions.</p> 47<p>This document is focused on highlighting implementation details that are 48specific to subscriptions, along with some strategies for the associated billing 49and business models.</p> 50 51<h2 id="overview">Overview of Subscriptions</h2> 52<p>A <em>subscription</em> is a product type offered in In-app Billing that 53lets you sell content, services, or features to users from inside your app with 54recurring, automated billing at the interval you specify. You can sell subscriptions to almost 55any 56type of digital content, from any type of app or game.</p> 57 58<p>As with other in-app products, you configure and publish subscriptions using 59the Developer Console and then sell them from inside apps installed on 60Android devices. In the Developer console, you create subscription 61products and add them to a product list, then set a price and optional trial 62period for each, choose a billing interval, and then 63publish. For more information about using the Developer Console, see 64<a href="#administering">Configuring Subscription Items</a>.</p> 65 66<p>When users purchase subscriptions in your apps, Google Play handles all 67checkout details so your apps never have to directly process any financial 68transactions. Google Play processes all payments for subscriptions through 69Google Wallet, just as it does for standard in-app products and app purchases. 70This ensures a consistent and familiar purchase flow for your users.</p> 71 72<img src="{@docRoot}images/in-app-billing/v3/billing_subscription_v3.png" style="float:right; border:4px solid ddd;"> 73 74<p>After users have purchased subscriptions, they can view the subscriptions and 75cancel them from the <strong>My Apps</strong> screen in the Play Store app or 76from the app's product details page in the Play Store app. For more information 77about handling user cancellations, see <a href="#cancellation">Subscription Cancellation</a>.</p> 78 79<p>In addition to client-side API calls, you can use the server-side API for 80In-app Billing to provide subscription purchasers with extended access to 81content (for example, from your web site or another service). 82The server-side API lets you validate the status of a subscription when users 83sign into your other services. For more information about the API, see <a 84href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google Play Developer API</a>. </p> 85 86<p>You can also build on your existing external subscriber base from inside your 87Android apps.</p> 88<ul> 89<li>If you sell subscriptions on a web site, for example, you can add 90your own business logic to your Android app to determine whether the user has 91already purchased a subscription elsewhere, then allow access to your content if 92so or offer a subscription purchase from Google Play if not.</li> 93<li>You can implement your own solution for sharing subscriptions across as 94many different apps or products as you want. For example, you could sell a 95subscription that gives a subscriber access to an entire collection of apps, 96games, or other content for a monthly or annual fee. To implement this solution, 97you could add your own business logic to your app to determine whether the user 98has already purchased a given subscription and if so, allow access to your 99content.</li> 100</ul> 101</p> 102 103<p>In general the same basic policies and terms apply to subscriptions as to 104standard in-app products, however there are some differences. For complete 105information about the current policies and terms, please read the <a 106href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en 107&answer=140504">policies document</a>.</p> 108 109<p>To learn about the minimum system requirements for 110subscriptions, see the <a href="{@docRoot}google/play/billing/versions.html#Subs">Version Notes</a>.</p> 111 112<h2 id="administering">Configuring Subscription Items</h2> 113 114<p>To create and manage subscriptions, you can use the Developer Console to set 115up a 116product list for the app, then configure these attributes for each subscription 117product:</p> 118 119<ul> 120<li>Purchase Type: always set to <strong>Subscription</strong></li> 121<li>Subscription ID: An identifier for the subscription</li> 122<li>Publishing State: Unpublished/Published</li> 123<li>Language: The default language for displaying the subscription</li> 124<li>Title: The title of the subscription product</li> 125<li>Description: Details that tell the user about the subscription</li> 126<li>Price: Default price of subscription per recurrence</li> 127<li>Recurrence: Interval of billing recurrence</li> 128<li>Additional currency pricing (can be auto-filled)</li> 129</ul> 130 131<p>For details on how to add and configure products in the Developer Console, 132see <a href="{@docRoot}google/play/billing/billing_admin.html">Administering 133In-app Billing</a>.</p> 134 135<p>You can also create and manage subscriptions using the 136<a href="{@docRoot}google/play/billing/gp-purchase-status-api.html"> 137Google Play Developer API</a>.</p> 138 139<h3 id="pricing">Subscription pricing</h3> 140 141<p>When you create a subscription in the Developer Console, you can set a price 142for it in any available currencies. Each subscription must have a non-zero 143price. You can price multiple subscriptions for the same content differently 144— for example you could offer a discount on an annual subscription 145relative to the monthly equivalent. </p> 146 147<p class="caution"><strong>Important</strong>: To change the price of a 148subscription, you can publish a new subscription product ID at a new price, 149then offer it in your app instead of the original product. Users who have 150already purchased will continue to be charged at the 151original price, but new users will be charged at the new price.</p> 152 153<h3 id="user-billing">User billing</h3> 154 155<p>In the Developer Console, you can configure subscription products with 156automated recurring billing at your choice of intervals:</p> 157 158<ul> 159 <li>Monthly — Google Play bills the customer’s Google Wallet account at 160 the time of purchase and monthly subsequent to the purchase date (exact billing 161 intervals can vary slightly over time).</li> 162 <li>Annually — Google Play bills the customer's Google Wallet account at 163 the time of purchase and again on the same date in subsequent years.</li> 164 165 <li>Seasonal — Google Play bills the customer's Google Wallet account at 166 the beginning of each "season" (you specify the season beginning and end 167 dates). This 168 is intended for annual purchases of seasonal content (such as sports-related 169 content). The subscription runs through the end of the season, and restarts 170 the next year at the start of the season.</li> 171 172</ul> 173 174<p>Billing continues indefinitely at the interval and price specified for the 175subscription. At each subscription renewal, Google Play charges the user account 176automatically, then notifies the user of the charges afterward by email. For 177monthly and annual subscriptions, billing cycles will always match subscription 178cycles, based on the purchase date. (Seasonal subscriptions are charged 179annually, on the first day of the season.)</p> 180 181<p>Over the life of a subscription, the form of payment billed remains the same 182— Google Play always bills the same form of payment (such as credit card 183or by Direct Carrier Billing) that was originally used to purchase the 184subscription.</p> 185 186<p>When the subscription payment is approved by Google Wallet, Google Play 187provides a purchase token back to the purchasing app through the In-app Billing 188API. Your apps can store the token locally or pass it to your backend servers, 189which can then use it to validate or cancel the subscription remotely using the 190<a 191href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google Play Developer API</a>.</p> 192 193<p>If a recurring payment fails (for example, because the customer’s credit 194card has become invalid), the subscription does not renew. How your app is 195notified depends on the In-app Billing API version that you are using:</p> 196<ul> 197<li>With In-app Billing Version 3, the failed or expired subscription is no longer 198returned when you call {@code getPurchases}.</li> 199<li>With In-app Billing Version 2, Google Play notifies your app at the end of 200the active cycle that the purchase state of the subscription is now "Expired". 201</li> 202</ul> 203 204<p class="note"><strong>Recommendation</strong>: Include business logic in your 205app to notify your backend servers of subscription purchases, tokens, and any 206billing errors that may occur. Your backend servers can use the server-side API 207to query and update your records and follow up with customers directly, if needed.</p> 208 209<h3 id="deferred-billing">Deferred Billing</h3> 210 211<p>Using the 212<a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google 213Play Developer API</a>, you can defer the next billing date for a 214subscriber. The user continues to be subscribed to the content, and has full 215access to it, but is not charged during the deferral period. This allows you 216to do things like:</p> 217 218<ul> 219 <li>Give users free access as part of a bundle or a special offer (for 220 example, giving free access to web content to users who subscribe to a 221 print magazine)</li> 222 <li>Give free access to customers as a goodwill gesture</li> 223</ul> 224 225<p>The longest you can defer billing is for one year per call. Of course, you 226can call the API again before the year is up to defer billing further.</p> 227 228<p>For example, Darcy has a monthly subscription to online content for the 229<em>Fishing Gentleman</em> app. He is normally 230billed £1.25 on the first of each month. 231On March 10, he participates in an online survey for the app publisher. The 232publisher rewards him by deferring his next payment until June 1. Darcy is not 233charged on April 1 or May 1, but still has access to the content as normal. On 234June 1, he is charged his normal £1.25 subscription fee.</p> 235 236<p class="note"><strong>Note:</strong> The API always defers the billing date 237by a whole number of days. If you request a deferral period that includes a 238fractional number of days, the API rounds the period up to the next full day. 239For example, if a user's subscription is set to renew on 15 June 2015 at 24014:00:00 UTC, and you use the API to defer the renewal date to 15 August 2015 at 24102:00:00 UTC, the API will round up to the next full day and set the renewal 242date to 15 August 2015 14:00:00 UTC.</p> 243 244<p>You can also offer free trials to new subscribers, as described in 245<a href="#trials">Free trials</a>.</p> 246 247<h3 id="trials">Free trials</h3> 248 249<p>In the Developer Console, you can set up a free trial period that lets users 250try your subscription content before buying it. The trial period runs for the 251period of time that you set and then automatically converts to a full 252subscription managed according to the subscription's billing interval and 253price. Free trials are supported for monthly and annual subscriptions only, and are not supported for seasonal subscriptions.</p> 254 255<p>To take advantage of a free trial, a user must "purchase" the full 256subscription through the standard In-app Billing flow, providing a valid form of 257payment to use for billing and completing the normal purchase transaction. 258However, the user is not charged any money, because the initial period 259corresponds 260to the free trial. Instead, Google Play records a transaction of $0.00 and the 261subscription is marked as purchased for the duration of the trial period or 262until cancellation. When the transaction is complete, Google Play notifies users 263by email that they have purchased a subscription that includes a free trial 264period and that the initial charge was $0.00. </p> 265 266<p>When the trial period ends, Google Play automatically initiates billing 267against the credit card that the user provided during the initial purchase, at 268the amount set 269for the full subscription, and continuing at the subscription interval. If 270necessary, the user can cancel the subscription at any time during the trial 271period. In this case, Google Play <em>marks the subscription as expired immediately</em>, 272rather than waiting until the end of the trial period. The user has not 273paid for the trial period and so is not entitled to continued access after 274cancellation.</p> 275 276<p>You can set up a trial period for a subscription in the Developer Console, 277without needing to modify or update your APK. Just locate and edit the 278subscription in your product list, set a valid number of days for the trial 279(must be 7 days or longer), and publish. You can change the period any time, 280although note that Google Play does not apply the change to users who have 281already "purchased" a trial period for the subscription. Only new subscription 282purchases will use the updated trial period. You can create one free trial 283period per subscription product.</p> 284 285<h3 id="publishing">Subscription publishing</h3> 286 287<p>When you have finished configuring your subscription product details in the 288Developer Console or via the API, 289you can publish the subscription in the app product list.</p> 290 291<p>In the product list, you can add subscriptions, in-app products, or both. You 292can add multiple subscriptions that give access to different content or 293services, or you can add multiple subscriptions that give access to the same 294content but for different intervals or different prices, such as for a 295promotion. For example, a news outlet might decide to offer both monthly and 296annual subscriptions to the same content, with annual having a discount. You can 297also offer in-app purchase equivalents for subscription products, to ensure that 298your content is available to users of older devices that do not support 299subscriptions.</p> 300 301<p>After you add a subscription or in-app product to the product list, you must 302publish the product before Google Play can make it available for purchase. Note 303that you must also publish the app itself before Google Play will make the 304products available for purchase inside the app. </p> 305 306<p class="caution"><strong>Important</strong>: You can remove the subscription 307product from the product list offered in your app to prevent users from seeing 308or purchasing it.</p> 309 310<h2 id="cancellation">Subscription Cancellation</h2> 311 312<p>Users can view the status of all of their subscriptions and cancel them if 313necessary from the <strong>My Apps</strong> screen in the Play Store app. 314Currently, the In-app Billing API does not provide support for programatically 315canceling subscriptions from inside the purchasing app.</p> 316 317<p>When the user cancels a subscription, Google Play does not offer a refund for 318the current billing cycle. Instead, it allows the user to have access to the 319cancelled subscription until the end of the current billing cycle, at which time 320it terminates the subscription. For example, if a user purchases a monthly 321subscription and cancels it on the 15th day of the cycle, Google Play will 322consider the subscription valid until the end of the 30th day (or other day, 323depending on the month).</p> 324 325<p>In some cases, the user may contact you directly to request cancellation of a 326subscription. In this and similar cases, you can use the server-side API to 327query and directly cancel the user’s subscription from your servers. 328 329<p class="caution"><strong>Important:</strong> In all cases, you must continue 330to offer the content that your subscribers have purchased through their 331subscriptions, as long any user is able to access it. That is, you must 332not remove any content while any user still has an active 333subscription to it, even if that subscription will terminate at the end of the 334current billing cycle. Alternatively, you can use the <a href="#refunds">refund 335and revoke</a> API to revoke each subscriber's subscription (one by one) and 336refund their subscription payments. 337Removing content that any subscriber is entitled to access 338will result in penalties. Please see the <a 339href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies document</a> for more information. </p> 340 341<h3 id="uninstall">App uninstallation</h3> 342 343<p>When the user uninstalls an app that includes purchased subscriptions, the 344Play Store app will notify the user that there are active subscriptions. If the 345user chooses to continue with the uninstallation, the app is removed and the 346subscriptions remain active and recurring billing continues. The user can return 347to cancel the associated subscriptions at any time in the <strong>My Apps</strong> 348screen of the Play Store app. If the user chooses to cancel the uninstallation, 349the app and subscriptions remain as they were.</p> 350 351<h3 id="refunds">Refunding and revoking subscriptions</h3> 352 353<p>With subscriptions, Google Play does not provide a refund window, so users 354will need to request a refund. They can request a refund from the <strong>My 355Orders</strong> page in the Play Store, or by contacting you directly.</p> 356 357<p>If you receive requests for refunds, you can use the 358<a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google Play 359Developer API</a> or the Merchant Center to cancel the subscription, verify that it 360is already cancelled, or refund the user's payment without cancelling it. You 361can also use the 362<a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google 363Play Developer API</a> to <em>refund and revoke</em> a 364user's subscription. If you refund and revoke a subscription, the user's 365subscription is immediately cancelled, and the user's most recent subscription 366payment is refunded. (If you want to refund more than the most recent payment, 367you can process additional refunds through the Merchant Center.)</p> 368 369<p class="caution"><strong>Important:</strong> Partial refunds are not available 370at this time.</p> 371 372<h2 id="payment">Payment Processing and Policies</h2> 373 374<p>In general, the terms of Google Play allow you to sell in-app subscriptions 375only through the standard payment processor, Google Wallet. For purchases of 376any subscription products, the transaction fee is the same as the transaction 377fee for application purchases (30%).</p> 378 379<p>Apps published on Google Play that are selling subscriptions must use In-app 380Billing to handle the transaction and may not provide links to a purchase flow 381outside of the app and Google Play (such as to a web site).</p> 382 383<p>For complete details about terms and policies, see the <a 384href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies 385document</a>.</p> 386 387<h3 id="orderId">Subscription order numbers</h3> 388 389<p>To help you track transactions relating to a given subscription, Google 390Wallet provides a base Merchant Order Number for all recurrences of the 391subscription and denotes 392each recurring transaction by appending an integer as follows: </p> 393 394<p><span style="color:#777"><code style="color:#777">12999556515565155651.5565135565155651</code> (base order number)</span><br /> 395<code>12999556515565155651.5565135565155651..0</code> (first recurrence orderID)<br /> 396<code>12999556515565155651.5565135565155651..1</code> (second recurrence orderID)<br /> 397<code>12999556515565155651.5565135565155651..2</code> (third recurrence orderID)<br /> 398...<br /></p> 399 400<p>Google Play provides the order number as the value of the 401{@code orderId} field of the {@code INAPP_PURCHASE_DATA} JSON field (in V3) 402or the {@code PURCHASE_STATE_CHANGED} intent (in V2).</p> 403 404<h2 id="strategies">Purchase Verification Strategies</h2> 405 406<p>In a typical scenario, your app verifies the order status for new purchases 407to ensure that they are valid before granting access to the purchased 408content.</p> 409 410<p>To verify a purchase, the app passes the purchase token and other details up 411to your backend servers, which verifies them directly with Google Play using the 412Google Play Developer API. If the backend server determines that the purchase is 413valid, it notifies the app and grants access to the content.</p> 414 415<p>Keep in mind that users will want the ability to use your app at any time, 416including when there may be no network connection available. Make sure that your 417approach to purchase verification accounts for the offline use-case.</p> 418 419<h2 id="play-dev-api">Google Play Developer API</h2> 420 421<p>Google Play offers an HTTP-based API that lets you perform such tasks as:</p> 422 <ul> 423 <li>Remotely query the validity of a specific subscription at any time</li> 424 <li>Cancel a subscription</li> 425 <li>Defer a subscription's next billing date</li> 426 <li>Refund a subscription payment without cancelling the subscription</li> 427 <li>Refund and revoke a subscription</li> 428 </ul> 429 430<p>The API is designed to be used from your backend servers as a way of securely 431managing subscriptions, as well as extending and integrating subscriptions with 432other services.</p> 433 434<p>For complete information, see 435<a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google Play 436Developer API</a>.</p> 437
