1 page.title=Subscriptions 2 parent.title=In-app Billing 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 <ol> 10 <li><a href="#overview">Overview of Subscriptions</a> 11 <!--<ol> 12 <li><a href="#publishing">Subscription publishing and unpublishing</a></li> 13 <li><a href="#pricing">Subscription pricing</a></li> 14 <li><a href="#user-billing">User billing</a></li> 15 <li><a href="#cancellation">Subscription cancellation</a></li> 16 <li><a href="#uninstallation">App uninstallation</a></li> 17 <li><a href="#refunds">Refunds</a></li> 18 <li><a href="#payment">Payment processing and policies</a></li> 19 <li><a href="#requirements">System requirements for subscriptions</a></li> 20 <li><a href="#compatibility">Compatibility considerations</a></li> 21 </ol> --> 22 </li> 23 <li><a href="#implementing">Implementing Subscriptions</a> 24 <!-- <ol> 25 <li><a href="#sample">Sample application</a></li> 26 <li><a href="#model">Application model</a></li> 27 <li><a href="#token">Purchase token</a></li> 28 <li><a href="#version">Checking the In-app Billing API version</a></li> 29 <li><a href="purchase">Requesting purchase of a subscription</a></li> 30 <li><a href="#restore">Restoring transactions</a></li> 31 <li><a href="#validity">Checking subscription validity</a></li> 32 <li><a href="#viewstatus">Launching your product page to let the user cancel or view status</a></li> 33 <li><a href="#purchase-state-changes">Recurring billing and changes in purchase state</a></li> 34 <li><a href="modifying">Modifying your app for subscriptions</a></li> 35 </ol> --> 36 </li> 37 <li><a href="#administering">Administering Subscriptions</a></li> 38 39 <li><a href="#play-dev-api">Google Play Android Developer API</a> 40 <!-- <ol> 41 <li><a href="#using">Using the API</a></li> 42 <li><a href="#quota">Quota</a></li> 43 <li><a href="#auth">Authorization</a></li> 44 <li><a href="#practices">Using the API efficiently</a></li> 45 </ol> --> 46 </li> 47 </ol> 48 <h2>Downloads</h2> 49 <ol> 50 <li><a href="{@docRoot}guide/google/play/billing/billing_integrate.html#billing-download">Sample Application</a></li> 51 </ol> 52 <h2>See also</h2> 53 <ol> 54 <li><a href="{@docRoot}guide/google/play/billing/billing_overview.html">Overview of In-app 55 Billing</a></li> 56 <li><a href="{@docRoot}guide/google/play/billing/billing_best_practices.html">Security and 57 Design</a></li> 58 <li><a href="{@docRoot}guide/google/play/billing/billing_testing.html">Testing In-app 59 Billing</a></li> 60 <li><a href="{@docRoot}guide/google/play/billing/billing_admin.html">Administering In-app 61 Billing</a></li> 62 <li><a href="{@docRoot}guide/google/play/billing/billing_reference.html">In-app Billing 63 Reference</a></li> 64 </ol> 65 </div> 66 </div> 67 68 <p>Subscriptions let you sell content, services, or features in your app with 69 automated, recurring billing. Adding support for subscriptions is 70 straightforward and you can easily adapt an existing In-app Billing 71 implementation to sell subscriptions. </p> 72 73 <p>If you have already implemented In-app Billing for one-time purchase 74 products, you will find that you can add support for subscriptions with minimal 75 impact on your code. If you are new to In-app Billing, you can implement 76 subscriptions using the standard communication model, data structures, and user 77 interactions as for other in-app products.subscriptions. Because the 78 implementation of subscriptions follows the same path as for other in-app 79 products, details are provided outside of this document, starting with the <a 80 href="{@docRoot}guide/google/play/billing/billing_overview.html">In-app Billing 81 Overview</a>. </p> 82 83 <p>This document is focused on highlighting implementation details that are 84 specific to subscriptions, along with some strategies for the associated billing 85 and business models.</p> 86 87 <h2 id="overview">Overview of Subscriptions</h2> 88 89 <p>A <em>subscription</em> is a new product type offered in In-app Billing that lets you 90 sell content, services, or features to users from inside your app with recurring 91 monthly or annual billing. You can sell subscriptions to almost any type of 92 digital content, from any type of app or game.</p> 93 94 <p>As with other in-app products, you configure and publish subscriptions using 95 the Developer Console and then sell them from inside apps installed on an 96 Android-powered devices. In the Developer console, you create subscription 97 products and add them to a product list, setting a price for each, choosing a 98 billing interval of monthly or annually, and then publishing. In your apps, its 99 straightforward to add support for subscription purchases. The implementation 100 extends the standard In-app Billing API to support a new product type but uses 101 the same communication model, data structures, and user interactions as for 102 other in-app products.</p> 103 104 <p>When users purchase subscriptions in your apps, Google Play handles all 105 checkout details so your apps never have to directly process any financial 106 transactions. Google Play processes all payments for subscriptions through 107 Google Wallet, just as it does for standard in-app products and app purchases. 108 This ensures a consistent and familiar purchase flow for your users.</p> 109 110 <img src="{@docRoot}images/billing_subscription_flow.png" style="border:4px solid ddd;"> 111 112 113 <p>After users have purchase subscriptions, they can view the subscriptions and 114 cancel them, if necessary, from the My Apps screen in the Play Store app or 115 from the app's product details page in the Play Store app.</p> 116 117 <!--<img src="{@docRoot}images/billing_subscription_cancel.png" style="border:4px solid ddd;">--> 118 119 <p>Once users have purchased a subscription through In-app Billing, you can 120 easily give them extended access to additional content on your web site (or 121 other service) through the use of a server-side API provided for In-app Billing. 122 The server-side API lets you validate the status of a subscription when users 123 sign into your other services. For more information about the API, see <a 124 href="#play-dev-api">Google Play Android Developer API</a>, below. </p> 125 126 <p>You can also build on your existing external subscriber base from inside your 127 Android apps. If you sell subscriptions on a web site, for example, you can add 128 your own business logic to your Android app to determine whether the user has 129 already purchased a subscription elsewhere, then allow access to your content if 130 so or offer a subscription purchase from Google Play if not.</p> 131 132 <p>With the flexibility of In-app Billing, you can even implement your own 133 solution for sharing subscriptions across as many different apps or products as 134 you want. For example, you could sell a subscription that gives a subscriber 135 access to an entire collection of apps, games, or other content for a monthly or 136 annual fee. To implement this solution, you could add your own business logic to 137 your app to determine whether the user has already purchased a given 138 subscription and if so, allow access to your content. </p> 139 140 <div class="sidebox-wrapper"> 141 <div class="sidebox"> 142 <h2>Subscriptions at a glance</h2> 143 <ul> 144 <li>Subscriptions let you sell products with automated, recurring billing</li> 145 <li>You can set up subscriptions with either monthly or annual billing</li> 146 <li>You can sell multiple subscription items in an app with various billing 147 intervals or prices, such as for promotions</li> 148 <li>Users purchase your subscriptions from inside your apps, rather than 149 directly from Google Play</li> 150 <li>Users manage their purchased subscriptions from the My Apps screen in 151 the Play Store app</li> 152 <li>Google Play uses the original form of payment for recurring billing</li> 153 <li>If a user cancels a subscription, Google Play considers the subscription valid 154 until the end of the current billing cycle. The user continues to enjoy the content 155 for the rest of the cycle and is not granted a refund.</li> 156 </ul> 157 </div> 158 </div> 159 160 <p>In general the same basic policies and terms apply to subscriptions as to 161 standard in-app products, however there are some differences. For complete 162 information about the current policies and terms, please read the <a 163 href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en 164 &answer=140504">policies document</a>.</p> 165 166 167 <h3 id="publishing">Subscription publishing and unpublishing</h3> 168 169 <p>To sell a subscription in an app, you use the tools in the Developer Console 170 to set up a product list for the app and then create and configure a new 171 subscription. In the subscription, you set the price and billing interval and 172 define a subscription ID, title, and description. When you are ready, you can 173 then publish the subscription in the app product list.</p> 174 175 <p>In the product list, you can add subscriptions, in-app products, or both. You 176 can add multiple subscriptions that give access to different content or 177 services, or you can add multiple subscriptions that give access to the same 178 content but for different intervals or different prices, such as for a 179 promotion. For example, a news outlet might decide to offer both monthly and 180 annual subscriptions to the same content, with annual having a discount. You can 181 also offer in-app purchase equivalents for subscription products, to ensure that 182 your content is available to users of older devices that do not support 183 subscriptions.</p> 184 185 <p>After you add a subscription or in-app product to the product list, you must 186 publish the product before Google Play can make it available for purchase. Note 187 that you must also publish the app itself before Google Play will make the 188 products available for purchase inside the app. </p> 189 190 <p class="caution"><strong>Important:</strong> At this time, the capability to 191 unpublish a subscription is not available. Support for unpublishing a 192 subscription is coming to the Developer Console in the weeks ahead, so this is a 193 temporary limitation. In the short term, instead of unpublishing, 194 you can remove the subscription product from the product list offered in your 195 app to prevent users from seeing or purchasing it.</p> 196 197 <h3 id="pricing">Subscription pricing</h3> 198 199 <p>When you create a subscription in the Developer Console, you can set a price 200 for it in any available currencies. Each subscription must have a non-zero 201 price. You can price multiple subscriptions for the same content differently 202 — for example you could offer a discount on an annual subscription 203 relative to the monthly equivalent. </p> 204 205 <p class="caution"><strong>Important:</strong> At this time, once you publish a 206 subscription product, you cannot change its price in any currency. Support for 207 changing the price of published subscriptions is coming to the Developer Console 208 in the weeks ahead. In the short term, you can work around this limitation by 209 publishing a new subscription product ID at a new price, then offer it in your 210 app instead of the original product. Users who have already purchased will 211 continue to be charged at the original price, but new users will be charged at 212 the new price.</p> 213 214 <h3 id="user-billing">User billing</h3> 215 216 <p>You can sell subscription products with automated recurring billing at 217 either of two intervals:</p> 218 219 <ul> 220 <li>Monthly — Google Play bills the customers Google Wallet account at 221 the time of purchase and monthly subsequent to the purchase date (exact billing 222 intervals can vary slightly over time)</li> 223 <li>Annually — Google Play bills the customer's Google Wallet account at 224 the time of purchase and again on the same date in subsequent years.</li> 225 </ul> 226 227 <p>Billing continues indefinitely at the interval and price specified for the 228 subscription. At each subscription renewal, Google Play charges the user account 229 automatically, then notifies the user of the charges afterward by email. Billing 230 cycles will always match subscription cycles, based on the purchase date.</p> 231 232 <p>Over the life of a subscription, the form of payment billed remains the same 233 — Google Play always bills the same form of payment (such as credit card, 234 Direct Carrier Billing) that was originally used to purchase the 235 subscription.</p> 236 237 <p>When the subscription payment is approved by Google Wallet, Google Play 238 provides a purchase token back to the purchasing app through the In-app Billing 239 API. For details, see <a href="#token">Purchase token</a>, below. Your apps can 240 store the token locally or pass it to your backend servers, which can then use 241 it to validate or cancel the subscription remotely using the <a 242 href="#play-dev-api">Google Play Android Developer API</a>.</p> 243 244 <p>If a recurring payment fails, such as could happen if the customers credit 245 card has become invalid, the subscription does not renew. Google Play notifies your 246 app at the end of the active cycle that the purchase state of the subscription is now "Expired". 247 Your app does not need to grant the user further access to the subscription content.</p> 248 249 <p>As a best practice, we recommend that your app includes business logic to 250 notify your backend servers of subscription purchases, tokens, and any billing 251 errors that may occur. Your backend servers can use the server-side API to query 252 and update your records and follow up with customers directly, if needed.</p> 253 254 <h3 id="cancellation">Subscription cancellation</h3> 255 256 <p>Users can view the status of all of their subscriptions and cancel them if 257 necessary from the My Apps screen in the Play Store app. Currently, the In-app 258 Billing API does not provide support for canceling subscriptions direct from 259 inside the purchasing app, although your app can broadcast an Intent to launch 260 the Play Store app directly to the My Apps screen.</p> 261 262 <p>When the user cancels a subscription, Google Play does not offer a refund for 263 the current billing cycle. Instead, it allows the user to have access to the 264 cancelled subscription until the end of the current billing cycle, at which time 265 it terminates the subscription. For example, if a user purchases a monthly 266 subscription and cancels it on the 15th day of the cycle, Google Play will 267 consider the subscription valid until the end of the 30th day (or other day, 268 depending on the month).</p> 269 270 <p>In some cases, the user may contact you directly to request cancellation of a 271 subscription. In this and similar cases, you can use the server-side API to 272 query and directly cancel the users subscription from your servers. 273 274 <p class="caution"><strong>Important:</strong> In all cases, you must continue 275 to offer the content that your subscribers have purchased through their 276 subscriptions, for as long any users are able to access it. That is, you must 277 not remove any subscribers content while any user still has an active 278 subscription to it, even if that subscription will terminate at the end of the 279 current billing cycle. Removing content that a subscriber is entitled to access 280 will result in penalties. Please see the <a 281 href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies document</a> for more information. </p> 282 283 <h3 id="uninstall">App uninstallation</h3> 284 285 <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 uninstalltion, 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.</p> 286 287 <h3 id="refunds">Refunds</h3> 288 289 <p>As with other in-app products, Google Play does not provide a refund window 290 for subscription purchases. For example, users who purchase an app can ask for a 291 refund from Google Play within a 15-minute window. With subscriptions, Google 292 Play does not provide a refund window, so users will need to contact you 293 directly to request a refund. 294 295 <p>If you receive requests for refunds, you can use the server-side API to 296 cancel the subscription or verify that it is already cancelled. However, keep in 297 mind that Google Play considers cancelled subscriptions valid until the end of 298 their current billing cycles, so even if you grant a refund and cancel the 299 subscription, the user will still have access to the content. 300 301 <p class="note"><strong>Note:</strong> Partial refunds for canceled 302 subscriptions are not available at this time.</p> 303 304 <h3 id="payment">Payment processing and policies</h3> 305 306 <p>In general, the terms of Google Play allow you to sell in-app subscriptions 307 only through the standard payment processor, Google Wallet. For purchases of any 308 subscription products, just as for other in-app products and apps, the 309 transaction fee for subscriptions, just as for other in-app purchases, is the 310 same as the transaction fee for application purchases (30%).</p> 311 312 <p>Apps published on Google Play that are selling subscriptions must use In-app 313 Billing to handle the transaction and may not provide links to a purchase flow 314 outside of the app and Google Play (such as to a web site).</p> 315 316 <p>For complete details about terms and policies, see the <a 317 href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies 318 document</a>.</p> 319 320 <h3 id="requirements">System requirements for subscriptions</h3> 321 322 <p>In-app purchases of subscriptions are supported only on devices that meet 323 these minimum requirements:</p> 324 325 <ul> 326 <li>Must run Android 2.2 or higher</li> 327 <li>Google Play Store app, version 3.5 or higher, must be installed</li> 328 </ul> 329 330 <p>Google Play 3.5 and later versions include support for the In-app Billing 331 v2 API or higher, which is needed to support handling of subscription 332 products.</p> 333 334 <h3 id="compatibility">Compatibility considerations</h3> 335 336 <p>As noted in the previous section, support for subscriptions is available only 337 on devices that meet the system requirements. Not all devices will receive or 338 install Google Play 3.5, so not all users who install your apps will have access 339 to the In-app Billing API and subscriptions.</p> 340 341 <p>If you are targeting older devices that run Android 2.1 or earlier, we 342 recommend that you offer those users an alternative way buy the content that is 343 available through subscriptions. For example, you could create standard in-app 344 products (one-time purchases) that give access to similar content as your 345 subscriptions, possibly for a longer interval such as a year. </p> 346 347 348 <h2 id="implementing">Implementing Subscriptions</h2> 349 350 <p>Subscriptions are a standard In-app Billing product type. If you have already 351 implemented In-app Billing for one-time purchase products, you will find that 352 adding support for subscriptions is straightforward, with minimal impact on your 353 code. If you are new to In-app Billing, you can implement subscriptions using 354 the standard communication model, data structures, and user interactions as for 355 other in-app products.subscriptions. </p> 356 357 <p>The full implementation details for In-app Billing are provided outside of 358 this document, starting with the <a 359 href="{@docRoot}guide/google/play/billing/billing_overview.html">In-app Billing 360 Overview</a>. This document is focused on highlighting implementation details 361 that are specific to subscriptions, along with some strategies for the 362 associated billing and business models.</p> 363 364 365 <h3 id="sample">Sample application</h3> 366 367 <p>To help you get started with your In-app Billing implementation and 368 subscriptions, an updated version of the In-app Billing sample app is available. 369 You can download the sample app from the Android SDK repository using the 370 Android SDK Manager. For details, see <a 371 href="{@docRoot}guide/google/play/billing/billing_integrate.html#billing-download"> 372 Downloading the Sample Application</a>.</p> 373 374 <h3 id="model">Application model</h3> 375 376 <p>With subscriptions, your app uses the standard In-app Billing application 377 model, sending billing requests to the Play Store application over interprocess 378 communication (IPC) and receiving purchase responses from the Play Store app in 379 the form of asynchronous broadcast intents. Your application does not manage any 380 network connections between itself and the Google Play server or use any special 381 APIs from the Android platform.</p> 382 383 <p>Your app also uses the standard In-app Billing components — a billing 384 Service for sending requests, a BroadcastReceiver for receiving the responses, 385 and a security component for verifying that the response was sent by Google 386 Play. Also recommended are a response Handler for processing notifications, 387 errors, and status messages, and an observer for sending callbacks to your 388 application as needed. All of these components and their interactions are 389 described in full in the <a 390 href="{@docRoot}guide/google/play/billing/billing_overview.html">In-app Billing 391 Overview</a> and related documents.</p> 392 393 <p>To initiate different types of billing communication with Google Play, your 394 app will use the standard set of in-app billing requests and receive the same 395 responses. Inside the requests and responses are two new fields described below. 396 </p> 397 398 <h3 id="token">Purchase token</h3> 399 400 <p>Central to the end-to-end architecture for subscriptions is the purchase 401 token, a string value that uniquely identifies (and associates) a user ID and a 402 subscription ID. Google Play generates the purchase token when the user 403 completes the purchase of a subscription product (and payment is approved by 404 Google Wallet) and then sends it to the purchasing app on the device through the 405 In-app Billing API. </p> 406 407 <p>At the conclusion of a <code>PURCHASE_REQUEST</code> message flow, your app 408 can retrieve the purchase token and other transaction details by initiating a 409 <code>GET_PURCHASE_INFORMATION</code> request. The Bundle returned by the call 410 contains an JSON array of order objects. In the order corresponding to the 411 subscription purchase, the token is available in the <code>purchaseToken</code> 412 field. </p> 413 414 <p>An example of a JSON order object that includes a subscription purchase token 415 is shown below. </p> 416 417 <pre class="no-pretty-print" style="color:black">{ "nonce" : 1836535032137741465, 418 "orders" : 419 [{ "notificationId" : "android.test.purchased", 420 "orderId" : "transactionId.android.test.purchased", 421 "packageName" : "com.example.dungeons", 422 "productId" : "android.test.purchased", 423 "developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ", 424 "purchaseTime" : 1290114783411, 425 "purchaseState" : 0, 426 "purchaseToken" : "rojeslcdyyiapnqcynkjyyjh" }] 427 } 428 </pre> 429 430 <p>After receiving a purchase token, your apps can store the token locally or 431 pass it to your backend servers, which can then use it to query the billing 432 status or cancel the subscription remotely. If your app will store the token 433 locally, please read the <a 434 href="{@docRoot}guide/google/play/billing/billing_best_practices.html">Security and 435 Design</a> document for best practices for maintaining the security of your 436 data.</p> 437 438 <h3 id="version">Checking the In-app Billing API version</h3> 439 440 <p>Subscriptions support is available only in versions of Google Play that 441 support the In-app Billing v2 API (Google Play 3.5 and higher). For your app, 442 an essential first step at launch is to check whether the version of Google Play 443 installed on the device supports the In-app Billing v2 API and 444 subscriptions.</p> 445 446 <p>To do this, create a CHECK_BILLING_SUPPORTED request Bundle that includes the 447 required key-value pairs, together with</p> 448 449 <ul> 450 <li>The <code>API_VERSION</code> key, assigning a value of 2.</li> 451 <li>The <code>BILLING_REQUEST_ITEM_TYPE</code> key, assigning a value of subs</li> 452 </ul> 453 454 <p>Send the request using <code>sendBillingRequest(Bundle)</code> and receive 455 the response Bundle. You can extract the response from the 456 <code>BILLING_RESPONSE_RESPONSE_CODE</code> key of the response. RESULT_OK 457 indicates that subscriptions are supported.</p> 458 459 <p>The sample app declares constants for the accepted 460 <code>BILLING_REQUEST_ITEM_TYPE</code> values (from Consts.java):</p> 461 462 <pre class="pretty-print"> // These are the types supported in the IAB v2 463 public static final String ITEM_TYPE_INAPP = "inapp"; 464 public static final String ITEM_TYPE_SUBSCRIPTION = "subs"; 465 </pre> 466 467 <p>It sets up a convenience method for building the request bundle (from BillingService.java):</p> 468 469 <pre class="pretty-print"> protected Bundle makeRequestBundle(String method) { 470 Bundle request = new Bundle(); 471 request.putString(Consts.BILLING_REQUEST_METHOD, method); 472 request.putInt(Consts.BILLING_REQUEST_<code>API_VERSION</code>, 2); 473 request.putString(Consts.BILLING_REQUEST_PACKAGE_NAME, getPackageName()); 474 return request; 475 } 476 </pre> 477 478 <p>Heres an example of how to test support for In-App Billing v2 and subscriptions 479 (from BillingService.java):</p> 480 481 <pre class="pretty-print"> /** 482 * Wrapper class that checks if in-app billing is supported. 483 */ 484 class CheckBillingSupported extends BillingRequest { 485 public String mProductType = null; 486 public CheckBillingSupported() { 487 // This object is never created as a side effect of starting this 488 // service so we pass -1 as the startId to indicate that we should 489 // not stop this service after executing this request. 490 super(-1); 491 } 492 493 public CheckBillingSupported(String type) { 494 super(-1); 495 mProductType = type; 496 } 497 498 @Override 499 protected long run() throws RemoteException { 500 Bundle request = makeRequestBundle("CHECK_BILLING_SUPPORTED"); 501 if (mProductType != null) { 502 request.putString(Consts.<code>BILLING_REQUEST_ITEM_TYPE</code>, mProductType); 503 } 504 Bundle response = mService.sendBillingRequest(request); 505 int responseCode = response.getInt(Consts.<code>BILLING_RESPONSE_RESPONSE_CODE</code>); 506 if (Consts.DEBUG) { 507 Log.i(TAG, "CheckBillingSupported response code: " + 508 ResponseCode.valueOf(responseCode)); 509 } 510 boolean billingSupported = (responseCode == ResponseCode.RESULT_OK.ordinal()); 511 ResponseHandler.checkBillingSupportedResponse(billingSupported, mProductType); 512 return Consts.BILLING_RESPONSE_INVALID_REQUEST_ID; 513 } 514 } 515 </pre> 516 517 <h3 id="purchase">Requesting a subscription purchase</h3> 518 519 <p>Once youve checked the API version as described above and determined that 520 subscriptions are supported, you can present subscription products to the user 521 for purchase. When the user has selected a subscription product and initiated a 522 purchase, your app handles the purchase just as it would for other in-app 523 products — by sending a REQUEST_PURCHASE request. You can then launch 524 Google Play to display the checkout user interface and handle the financial 525 transaction.. 526 527 <p>The REQUEST_PURCHASE includes a Bundle containing the item details, as 528 described in the <a 529 href="{@docRoot}guide/google/play/billing/billing_overview.html">In-app Billing 530 Overview</a>. For a subscription, the Bundle must also specify:</p> 531 532 <ul> 533 <li>The <code>ITEM_ID</code> key, with a value that specifies a valid, published 534 subscription product.</li> 535 <li>The <code>ITEM_TYPE</code> key, with a value of subs 536 (<code>ITEM_TYPE_SUBSCRIPTION</code> in the sample app). If the request does not 537 specify the subscription's <code>ITEM_TYPE</code>, Google Play attempts to 538 handle the request as a standard in-app purchase (one-time purchase).</li> 539 </ul> 540 541 <p>Google Play synchronously returns a response bundle that includes 542 <code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, and 543 <code>REQUEST_ID</code>. Your app uses the <code>PURCHASE_INTENT</code> to 544 launch the checkout UI and the message flow proceeds exactly as described in <a 545 href="{@docRoot}guide/google/play/billing/billing_overview.html#billing-message- 546 sequence">Messaging sequence</a>.</p> 547 548 <p>Heres how the sample app initiates a purchase for a subscription, where 549 <code>mProductType</code> is <code>ITEM_TYPE_SUBSCRIPTION</code> (from 550 BillingService.java).</p> 551 552 <pre class="pretty-print"> /** 553 * Wrapper class that requests a purchase. 554 */ 555 class RequestPurchase extends BillingRequest { 556 public final String mProductId; 557 public final String mDeveloperPayload; 558 public final String mProductType; 559 560 . . . 561 562 @Override 563 protected long run() throws RemoteException { 564 Bundle request = makeRequestBundle("REQUEST_PURCHASE"); 565 request.putString(Consts.BILLING_REQUEST_ITEM_ID, mProductId); 566 request.putString(Consts.<code>BILLING_REQUEST_ITEM_TYPE</code>, mProductType); 567 // Note that the developer payload is optional. 568 if (mDeveloperPayload != null) { 569 request.putString(Consts.BILLING_REQUEST_DEVELOPER_PAYLOAD, mDeveloperPayload); 570 } 571 Bundle response = mService.sendBillingRequest(request); 572 PendingIntent pendingIntent 573 = response.getParcelable(Consts.BILLING_RESPONSE_PURCHASE_INTENT); 574 if (pendingIntent == null) { 575 Log.e(TAG, "Error with requestPurchase"); 576 return Consts.BILLING_RESPONSE_INVALID_REQUEST_ID; 577 } 578 579 Intent intent = new Intent(); 580 ResponseHandler.buyPageIntentResponse(pendingIntent, intent); 581 return response.getLong(Consts.BILLING_RESPONSE_REQUEST_ID, 582 Consts.BILLING_RESPONSE_INVALID_REQUEST_ID); 583 } 584 585 @Override 586 protected void responseCodeReceived(ResponseCode responseCode) { 587 ResponseHandler.responseCodeReceived(BillingService.this, this, responseCode); 588 } 589 } 590 </pre> 591 592 <h3 id="restoring">Restoring transactions</h3> 593 594 <p>Subscriptions always use the <em>managed by user account</em> purchase type, 595 so that you can restore a record of subscription transactions on the device when 596 needed. When a user installs your app onto a new device, or when the user 597 uninstalls/reinstalls the app on the original device, your app should restore 598 the subscriptions that the user has purchased.</p> 599 600 <p>The process for restoring subscriptions transactions is the same as described 601 in <a 602 href="{@docRoot}guide/google/play/billing/billing_overview.html#billing-message- 603 sequence">Messaging sequence</a>. Your app sends a 604 <code>RESTORE_TRANSACTIONS</code> request to Google Play. Google Play sends two 605 broadcast intents as asynchronous responses — a <code>RESPONSE_CODE</code> 606 intent and a <code>PURCHASE_STATE_CHANGED</code> intent.</p> 607 608 <p>The <code>PURCHASE_STATE_CHANGED</code> intent contains a notification ID 609 that your app can use to retrieve the purchase details, including the purchase 610 token, by sending a standard <code>GET_PURCHASE_INFORMATION</code> request. The 611 <code>Bundle</code> returned in the call includes an JSON array of order objects 612 corresponding to subscription (and in-app product) purchases that you can 613 restore locally.</p> 614 615 <p>Your app can store the restored purchase state and other transaction details 616 in the way that best meets your needs. Your app can use it later to check the 617 subscription validity, although please read the <a 618 href="{@docRoot}guide/google/play/billing/billing_best_practices.html">Security and 619 Design</a> document for best practices for maintaining the security of your 620 data.</p> 621 622 <h3 id="validity">Checking subscription validity</h3> 623 624 <p>Subscriptions are time-bound purchases that require successful billing 625 recurrences over time to remain valid. Your app should check the validity of 626 purchased subscriptions at launch or prior to granting access to subscriber 627 content.</p> 628 629 <p>With In-app Billing, you validate a subscription by keeping track of its 630 purchase state and then checking the state whenever needed. Google Play 631 provides two ways to let you know when the purchase 632 state of a subscription changes:</p> 633 634 <ul> 635 <li><em>In-app Billing Notifications</em>. Google Play pushes a notification 636 to your app to indicate a change in the purchase state of a subscription. Your app can 637 store the most recent purchase state for a given purchase token and then check 638 that state at run time, as needed.</li> 639 <li><em>Google Play Android Developer API</em>. You can use this HTTP-based 640 API to poll Google Play for the current purchase state of a subscription. You 641 can store the purchased state for each <code>purchaseToken</code> on your 642 backend servers. For more information, see <a href="#play-dev-api">Google Play 643 Android Developer API</a>, below.</li> 644 </ul> 645 646 <p>For most use-cases, especially those where backend servers are already keeping 647 track of subscribed users, implementing a combination of both methods is the 648 recommended approach. A typical implementation might work like this:</p> 649 650 <ul> 651 <li>When the user successfully purchases a new subscription, your app notifies a 652 backend server, which stores the purchase token, user name, and other 653 information in a secure location.</li> 654 <li>Since your app cannot know the expiration date, your server can poll Google 655 Play to get the expiration and store it with the purchase token and other 656 data.</li> 657 <li>Because your server now knows the expiration date, it does not need to poll 658 Google Play again until after the expiration date, at which time it can confirm 659 that the subscription was not cancelled.</li> 660 <li>On the client side, your app can continue to update the server whenever the 661 purchase state changes, storing the state locally.</li> 662 </ul> 663 664 <p>If you are using both notifications and the Google Play Android Developer API to validate subscriptions, we recommend the following:</p> 665 666 <ul> 667 <li>If your app wants to check validity but you cant reach your server (or 668 you dont have a server), use the latest purchase state received by 669 notification.</li> 670 <li>If you have a server and its reachable, always give preference to the 671 purchase state obtained from your server over the state received in 672 notifications.</li> 673 </ul> 674 675 <p>If necessary, you can also use a <code>RESTORE_TRANSACTIONS</code> request to retrieve a record of all managed and in-app products purchased by the user, which you can then store locally. However, using <code>RESTORE_TRANSACTIONS</code> on a regular basis is not recommended because of performance impacts.</p> 676 677 <p>Regardless of the approach you choose, your app should check subscriptions 678 and validity at launch, such as prior to accessing subscriber content, game 679 levels, and so on.</p> 680 681 <p class="table-caption"><strong>Table 1.</strong> Summary of purchaseState 682 values for subscription purchases, as received with a 683 <code>PURCHASE_STATE_CHANGED</code> intent.</p> 684 685 <table> 686 <tr> 687 <th>State</th><th>purchaseState Value</th><th>Comments</th> 688 </tr> 689 <tr> 690 <td>Purchased successfully</td><td><code>0</code></td><td>Sent at original purchase only (not at recurring billing cycles).</td></tr> 691 <td>Cancelled</td><td><code>1</code></td><td>Sent at original purchase only if the purchase has failed for some reason. </td></tr> 692 <td>Refunded</td><td><code>2</code></td><td>The purchase was refunded.</code></td></tr> 693 <td>Subscription expired</td><td><code>3</code></td><td>Sent at the end of a billing cycle to indicate that the subscription expired without renewal because of non-payment or user-cancellation. Your app does not need to grant continued access to the subscription content. 694 </td></tr> 695 </table> 696 697 698 <h3 id="viewstatus">Launching your product page to let the user cancel or view subscriptions</h3> 699 700 <p>In-app Billing does not currently provide an API to let users directly view or cancel 701 subscriptions from within the purchasing app. Instead, users can launch the Play 702 Store app on their devices and go to the My Apps screen to manage subscriptions. In My Apps, 703 users can see a list of their subscriptions organized by application. Tapping one of the 704 subscriptions loads the app's product page, from which users can see active subscriptions 705 and billing status and cancel subscriptions as needed.</p> 706 707 <p>To make it easier for users to find and manage their subscriptions from inside your app, 708 we recommend that you offer a "View My Subscriptions" or "Manage Subscriptions" option in 709 your UI that directly loads your app's product page in the Play Store app.</p> 710 711 <p>To do this, create an intent with the <a 712 href="{@docRoot}reference/android/content/Intent.html#ACTION_VIEW">ACTION_VIEW</a> 713 action and include the <code>market://</code> URI (rather than the <code>http://</code> 714 URI) of your app's details page. Heres an example:</p> 715 716 <pre style="pretty-print">Intent intent = new Intent(Intent.ACTION_VIEW); 717 intent.setData(Uri.parse("market://details?id=com.example.app")); 718 startActivity(intent);</pre> 719 720 <p>For more information, see 721 <a href="{@docRoot}distribute/googleplay/promote/linking.html">Linking to Your Products</a>.</p> 722 723 <h3 id="purchase-state-changes">Recurring billing, cancellation, and changes in purchase state</h3> 724 725 <p>Google Play notifies your app when the user completes the purchase of a 726 subscription, but the purchase state does not change over time, provided that 727 recurring billing takes place successfully. Google Play does not notify your app 728 of a purchase state change <em>until the subscription expires because of 729 non-payment or user cancellation</em>. </p> 730 731 <p>Over the life of a subscription, your app does not need to initiate any 732 recurring billing events — those are all handled by Google Play and they 733 are transparent to your application if billing is successful.</p> 734 735 <p>When the user cancels a subscription during an active billing cycle, Google 736 Play <em>does not</em> notify your app immediately of the change in purchase 737 state. Instead, it waits until the end of the active billing cycle and then 738 notifies your app that the purchase state has changed to "Expired". </p> 739 740 <p>Similarly, if payment for the next billing cycle fails, Google Play waits 741 until the end of the active billing cycle and then notifies your app at that time that the 742 purchase state has changed to "Expired".</p> 743 744 <p>Your app can handle user cancellation and non-payment in the same way, since both cause 745 a change to the same "Expired" purchase state. Once the purchase state has become "Expired", 746 your app does not need to grant further access to the subscription content.</p> 747 748 <h3 id="modifying">Modifying your app for subscriptions</h3> 749 750 <p>For subscriptions, you make the same types of modifications to your app as 751 are described in <a 752 href="{@docRoot}guide/google/play/billing/billing_integrate.html#billing-implement"> 753 Modifying your Application Code</a>.</p> 754 755 <p>Note that, in your UI that lets users view and select subscriptions for 756 purchase, you should add logic to check for purchased subscriptions and validate 757 them. Your UI should not present subscriptions if the user has already purchased 758 them.</p> 759 760 <h2 id="administering">Administering Subscriptions</h2> 761 762 <p>To create and manage subscriptions, you use the tools in the Developer 763 Console, just as for other in-app products.</p> 764 765 <p>At the Developer Console, you can configure these attributes for each 766 subscription product:</p> 767 768 <ul> 769 <li>Purchase Type: always set to subscription</li> 770 <li>Subscription ID: An identifier for the subscription</li> 771 <li>Publishing State: Unpublished/Published</li> 772 <li>Language: The default language for displaying the subscription</li> 773 <li>Title: The title of the subscription product</li> 774 <li>Description: Details that tell the user about the subscription</li> 775 <li>Price: USD price of subscription per recurrence</li> 776 <li>Recurrence: monthly or yearly</li> 777 <li>Additional currency pricing (can be auto-filled)</li> 778 </ul> 779 780 <p>For details, please see <a href="{@docRoot}guide/google/play/billing/billing_admin.html">Administering 781 In-app Billing</a>.</p> 782 783 784 <h2 id="play-dev-api">Google Play Android Developer API</h2> 785 786 <p>Google Play offers an HTTP-based API that you can use to remotely query the 787 validity of a specific subscription at any time or cancel a subscription. The 788 API is designed to be used from your backend servers as a way of securely 789 managing subscriptions, as well as extending and integrating subscriptions with 790 other services.</p> 791 792 <h3 id="using">Using the API</h3> 793 794 <p>To use the API, you must first register a project at the <a 795 href="https://code.google.com/apis/console">Google APIs Console</a> and receive 796 a Client ID and shared secret that your app will present when calling the 797 Google Play Android Developer API. All calls to the API are authenticated with 798 OAuth 2.0.</p> 799 800 <p>Once your app is registered, you can access the API directly, using standard 801 HTTP methods to retrieve and manipulate resources, or you can use the Google 802 APIs Client Libraries, which are extended to support the API.</p> 803 804 <p>The Google Play Android Developer API is built on a RESTful design that uses 805 HTTP and JSON, so any standard web stack can send requests and parse the 806 responses. However, if you dont want to send HTTP requests and parse responses 807 manually, you can access the API using the client libraries, which provide 808 better language integration, improved security, and support for making calls 809 that require user authorization.</p> 810 811 <p>For more information about the API and how to access it through the Google 812 APIs Client Libraries, see the documentation at:</p> 813 814 <p style="margin-left:1.5em;"><a 815 href="https://developers.google.com/android-publisher/v1/">https://developers. 816 google.com/android-publisher/v1/</a></p> 817 818 <h3 id="quota">Quota</h3> 819 820 <p>Applications using the Google Play Android Developer API are limited to an 821 initial courtesy usage quota of <strong>15000 requests per day</strong> (per 822 application). This should provide enough access for normal 823 subscription-validation needs, assuming that you follow the recommendation in 824 this section.</p> 825 826 <p>If you need to request a higher limit for your application, please use the 827 Request more link in the <a 828 href="https://code.google.com/apis/console/#:quotas">Google APIs Console</a>. 829 Also, please read the section below on design best practices for minimizing your 830 use of the API.</p> 831 832 <h3 id="auth">Authorization</h3> 833 834 <p>Calls to the Google Play Android Developer API require authorization. Google 835 uses the OAuth 2.0 protocol to allow authorized applications to access user 836 data. To learn more, see <a 837 href="https://developers.google.com/android-publisher/authorization">Authorization</a> 838 in the Google Play Android Developer API documentation.</p> 839 840 <h3 id="practices">Using the API efficiently</h3> 841 842 <p>Access to the Google Play Android Developer API is regulated to help ensure a 843 high-performance environment for all applications that use it. While you can 844 request a higher daily quota for your application, we highly recommend that you 845 minimize your access using the technique(s) below. </p> 846 847 <ul> 848 <li><em>Store subscription expiry on your servers</em> — your servers 849 should use the Google Play Android Developer API to query the expiration date 850 for new subscription tokens, then store the expiration date locally. This allows 851 you to check the status of subscriptions only at or after the expiration (see 852 below). </li> 853 <li><em>Cache expiration and purchaseState</em> — If your app contacts 854 your backend servers at runtime to verify subscription validity, your server 855 should cache the expiration and purchaseState to ensure the fastest possible 856 response (and best experience) for the user.</li> 857 <li><em>Query for subscription status only at expiration</em> — Once your 858 server has retrieved the expiration date of subscription tokens, it should not 859 query the Google Play servers for the subscription status again until the 860 subscription is reaching or has passed the expiration date. Typically, your 861 servers would run a batch query each day to check the status of 862 <em>expiring</em> subscriptions, then update the database. Note that: 863 <ul> 864 <li>Your servers should not query all subscriptions every day</li> 865 <li>Your servers should never query subscription status dynamically, based on 866 individual requests from your Android application. </li> 867 </ul> 868 </li> 869 </ul> 870 871 <p>By following those general guidelines, your implementation will offer the 872 best possible performance for users and minimize use of the Google Play Android 873 Developer API.</p> 874 875