quddusc | 8dcc99d | 2013-02-07 17:16:33 -0800 | [diff] [blame] | 1 | page.title=Subscriptions |
| 2 | parent.title=In-app Billing |
| 3 | parent.link=index.html |
| 4 | @jd:body |
| 5 | |
quddusc | 5319f31 | 2013-02-27 14:44:18 -0800 | [diff] [blame] | 6 | <div id="qv-wrapper"> |
quddusc | 8dcc99d | 2013-02-07 17:16:33 -0800 | [diff] [blame] | 7 | <div id="qv"> |
| 8 | <h2>Quickview</h2> |
| 9 | <ul> |
| 10 | <li>Users purchase your subscriptions from inside your apps, rather than |
| 11 | directly from Google Play.</li> |
| 12 | <li>Subscriptions let you sell products with automated, recurring billing |
| 13 | (monthly or annual).</li> |
| 14 | <li>You can offer a configurable trial period for any subscription.</li> |
| 15 | |
| 16 | </ul> |
| 17 | <h2>In this document</h2> |
| 18 | <ol> |
| 19 | <li><a href="#overview">Overview</a></li> |
| 20 | <li><a href="#administering">Configuring Subscriptions Items</a></li> |
| 21 | <li><a href="#cancellation">Cancellation</a></li> |
| 22 | <li><a href="#payment">Payment Processing</a></li> |
| 23 | <li><a href="#play-dev-api">Google Play Android Developer API</a></li> |
| 24 | </ol> |
| 25 | <h2>See also</h2> |
| 26 | <ol> |
| 27 | <li><a href="{@docRoot}google/play/billing/billing_integrate.html#Subs">Implementing Subscriptions (V3)</a></li> |
| 28 | </ol> |
| 29 | </div> |
| 30 | </div> |
| 31 | |
| 32 | <p>Subscriptions let you sell content, services, or features in your app with |
| 33 | automated, recurring billing. You can easily adapt an existing In-app Billing |
| 34 | implementation to sell subscriptions.</p> |
| 35 | <p>This document is focused on highlighting implementation details that are |
| 36 | specific to subscriptions, along with some strategies for the associated billing |
| 37 | and business models.</p> |
| 38 | |
| 39 | <h2 id="overview">Overview of Subscriptions</h2> |
| 40 | <p>A <em>subscription</em> is a product type offered in In-app Billing that |
| 41 | lets you sell content, services, or features to users from inside your app with |
| 42 | recurring monthly or annual billing. You can sell subscriptions to almost any |
| 43 | type of digital content, from any type of app or game.</p> |
| 44 | |
| 45 | <p>As with other in-app products, you configure and publish subscriptions using |
| 46 | the Developer Console and then sell them from inside apps installed on |
| 47 | Android devices. In the Developer console, you create subscription |
| 48 | products and add them to a product list, then set a price and optional trial |
| 49 | period for each, choose a billing interval (monthly or annual), and then |
| 50 | publish. For more information about using the Developer Console, see |
| 51 | <a href="#administering">Configuring Subscription Items</a>.</p> |
| 52 | |
| 53 | <p>When users purchase subscriptions in your apps, Google Play handles all |
| 54 | checkout details so your apps never have to directly process any financial |
| 55 | transactions. Google Play processes all payments for subscriptions through |
| 56 | Google Checkout, just as it does for standard in-app products and app purchases. |
| 57 | This ensures a consistent and familiar purchase flow for your users.</p> |
| 58 | |
| 59 | <img src="{@docRoot}images/in-app-billing/v3/billing_subscription_v3.png" style="float:right; border:4px solid ddd;"> |
| 60 | |
| 61 | <p>After users have purchase subscriptions, they can view the subscriptions and |
| 62 | cancel them from the <strong>My Apps</strong> screen in the Play Store app or |
| 63 | from the app's product details page in the Play Store app. For more information |
| 64 | about handling user cancellations, see <a href="#cancellation">Subscription Cancellation</a>.</p> |
| 65 | |
| 66 | <p>In adddition to client-side API calls, you can use the server-side API for |
| 67 | In-app Billing to provide subscription purchasers with extended access to |
| 68 | content (for example, from your web site or another service). |
| 69 | The server-side API lets you validate the status of a subscription when users |
| 70 | sign into your other services. For more information about the API, see <a |
| 71 | href="#play-dev-api">Google Play Android Developer API</a>. </p> |
| 72 | |
| 73 | <p>You can also build on your existing external subscriber base from inside your |
| 74 | Android apps.</p> |
| 75 | <ul> |
| 76 | <li>If you sell subscriptions on a web site, for example, you can add |
| 77 | your own business logic to your Android app to determine whether the user has |
| 78 | already purchased a subscription elsewhere, then allow access to your content if |
| 79 | so or offer a subscription purchase from Google Play if not.</li> |
| 80 | <li>You can implement your own solution for sharing subscriptions across as |
| 81 | many different apps or products as you want. For example, you could sell a |
| 82 | subscription that gives a subscriber access to an entire collection of apps, |
| 83 | games, or other content for a monthly or annual fee. To implement this solution, |
| 84 | you could add your own business logic to your app to determine whether the user |
| 85 | has already purchased a given subscription and if so, allow access to your |
| 86 | content.</li> |
| 87 | </ul> |
| 88 | </p> |
| 89 | |
| 90 | <p>In general the same basic policies and terms apply to subscriptions as to |
| 91 | standard in-app products, however there are some differences. For complete |
| 92 | information about the current policies and terms, please read the <a |
| 93 | href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en |
| 94 | &answer=140504">policies document</a>.</p> |
| 95 | |
| 96 | <p>To learn about the minimum system requirements for |
| 97 | subscriptions, see the <a href="{@docRoot}google/play/billing/versions.html#Subs">Version Notes</a>.</p> |
| 98 | |
| 99 | <h2 id="administering">Configuring Subscription Items</h2> |
| 100 | <p>To create and manage subscriptions, use the Developer Console to set up a |
| 101 | product list for the app then configure these attributes for each subscription |
| 102 | product:</p> |
| 103 | |
| 104 | <ul> |
| 105 | <li>Purchase Type: always set to <strong>Subscription</strong></li> |
| 106 | <li>Subscription ID: An identifier for the subscription</li> |
| 107 | <li>Publishing State: Unpublished/Published</li> |
| 108 | <li>Language: The default language for displaying the subscription</li> |
| 109 | <li>Title: The title of the subscription product</li> |
| 110 | <li>Description: Details that tell the user about the subscription</li> |
| 111 | <li>Price: USD price of subscription per recurrence</li> |
| 112 | <li>Recurrence: monthly or yearly</li> |
| 113 | <li>Additional currency pricing (can be auto-filled)</li> |
| 114 | </ul> |
| 115 | |
| 116 | <p>For details on how to add and configure products in the Developer Console, |
| 117 | see <a href="{@docRoot}google/play/billing/billing_admin.html">Administering |
| 118 | In-app Billing</a>.</p> |
| 119 | |
| 120 | <h3 id="pricing">Subscription pricing</h3> |
| 121 | |
| 122 | <p>When you create a subscription in the Developer Console, you can set a price |
| 123 | for it in any available currencies. Each subscription must have a non-zero |
| 124 | price. You can price multiple subscriptions for the same content differently |
| 125 | — for example you could offer a discount on an annual subscription |
| 126 | relative to the monthly equivalent. </p> |
| 127 | |
| 128 | <p class="caution"><strong>Important</strong>: To change the price of a |
| 129 | subscription, you can publish a new subscription product ID at a new price, |
| 130 | then offer it in your app instead of the original product. Users who have |
| 131 | already purchased will continue to be charged at the |
| 132 | original price, but new users will be charged at the new price.</p> |
| 133 | |
| 134 | <h3 id="user-billing">User billing</h3> |
| 135 | |
| 136 | <p>In the Developer Console, you can configure subscription products with |
| 137 | automated recurring billing at either of two intervals:</p> |
| 138 | |
| 139 | <ul> |
| 140 | <li>Monthly — Google Play bills the customer’s Google Checkout account at |
| 141 | the time of purchase and monthly subsequent to the purchase date (exact billing |
| 142 | intervals can vary slightly over time)</li> |
| 143 | <li>Annually — Google Play bills the customer's Google Checkout account at |
| 144 | the time of purchase and again on the same date in subsequent years.</li> |
| 145 | </ul> |
| 146 | |
| 147 | <p>Billing continues indefinitely at the interval and price specified for the |
| 148 | subscription. At each subscription renewal, Google Play charges the user account |
| 149 | automatically, then notifies the user of the charges afterward by email. Billing |
| 150 | cycles will always match subscription cycles, based on the purchase date.</p> |
| 151 | |
| 152 | <p>Over the life of a subscription, the form of payment billed remains the same |
| 153 | — Google Play always bills the same form of payment (such as credit card |
| 154 | or by Direct Carrier Billing) that was originally used to purchase the |
| 155 | subscription.</p> |
| 156 | |
| 157 | <p>When the subscription payment is approved by Google Checkout, Google Play |
| 158 | provides a purchase token back to the purchasing app through the In-app Billing |
| 159 | API. Your apps can store the token locally or pass it to your backend servers, |
| 160 | which can then use it to validate or cancel the subscription remotely using the <a |
| 161 | href="#play-dev-api">Google Play Android Developer API</a>.</p> |
| 162 | |
| 163 | <p>If a recurring payment fails (for example, because the customer’s credit |
| 164 | card has become invalid), the subscription does not renew. How your app is |
| 165 | notified depends on the In-app Billing API version that you are using:</p> |
| 166 | <ul> |
| 167 | <li>With In-app Billing Version 3, the failed or expired subscription is no longer |
| 168 | returned when you call {@code getPurchases}.</li> |
| 169 | <li>With In-app Billing Version 2, Google Play notifies your app at the end of |
| 170 | the active cycle that the purchase state of the subscription is now "Expired". |
| 171 | </li> |
| 172 | </ul> |
| 173 | |
| 174 | <p class="note"><strong>Recommendation</strong>: Include business logic in your |
| 175 | app to notify your backend servers of subscription purchases, tokens, and any |
| 176 | billing errors that may occur. Your backend servers can use the server-side API |
| 177 | to query and update your records and follow up with customers directly, if needed.</p> |
| 178 | |
| 179 | <h3 id="trials">Free trials</h3> |
| 180 | |
| 181 | <p>In the Developer Console, you can set up a free trial period that lets users |
| 182 | try your subscription content before buying it. The trial period runs for the |
| 183 | period of time that you set and then automatically converts to a full |
| 184 | subscription managed according to the subscription's billing interval and |
| 185 | price.</p> |
| 186 | |
| 187 | <p>To take advantage of a free trial, a user must "purchase" the full |
| 188 | subscription through the standard In-app Billing flow, providing a valid form of |
| 189 | payment to use for billing and completing the normal purchase transaction. |
| 190 | However, the user is not charged any money, since the initial period corresponds |
| 191 | to the free trial. Instead, Google Play records a transaction of $0.00 and the |
| 192 | subscription is marked as purchased for the duration of the trial period or |
| 193 | until cancellation. When the transaction is complete, Google Play notifies users |
| 194 | by email that they have purchased a subscription that includes a free trial |
| 195 | period and that the initial charge was $0.00. </p> |
| 196 | |
| 197 | <p>When the trial period ends, Google Play automatically initiates billing |
| 198 | against the credit card that the user provided during the initial purchase, at |
| 199 | the amount set |
| 200 | for the full subscription, and continuing at the subscription interval. If |
| 201 | necessary, the user can cancel the subscription at any time during the trial |
| 202 | period. In this case, Google Play <em>marks the subscription as expired immediately</em>, |
| 203 | rather than waiting until the end of the trial period. The user has not |
| 204 | paid for the trial period and so is not entitled to continued access after |
| 205 | cancellation.</p> |
| 206 | |
| 207 | <p>You can set up a trial period for a subscription in the Developer Console, |
| 208 | without needing to modify or update your APK. Just locate and edit the |
| 209 | subscription in your product list, set a valid number of days for the trial |
| 210 | (must be 7 days or longer), and publish. You can change the period any time, |
| 211 | although note that Google Play does not apply the change to users who have |
| 212 | already "purchased" a trial period for the subscription. Only new subscription |
| 213 | purchases will use the updated trial period. You can create one free trial |
| 214 | period per subscription product.</p> |
| 215 | |
| 216 | <h3 id="publishing">Subscription publishing</h3> |
| 217 | <p>When you have finished configuring your subscription product details in the |
| 218 | Developer Console, you can publish the subscription in the app product list.</p> |
| 219 | |
| 220 | <p>In the product list, you can add subscriptions, in-app products, or both. You |
| 221 | can add multiple subscriptions that give access to different content or |
| 222 | services, or you can add multiple subscriptions that give access to the same |
| 223 | content but for different intervals or different prices, such as for a |
| 224 | promotion. For example, a news outlet might decide to offer both monthly and |
| 225 | annual subscriptions to the same content, with annual having a discount. You can |
| 226 | also offer in-app purchase equivalents for subscription products, to ensure that |
| 227 | your content is available to users of older devices that do not support |
| 228 | subscriptions.</p> |
| 229 | |
| 230 | <p>After you add a subscription or in-app product to the product list, you must |
| 231 | publish the product before Google Play can make it available for purchase. Note |
| 232 | that you must also publish the app itself before Google Play will make the |
| 233 | products available for purchase inside the app. </p> |
| 234 | |
| 235 | <p class="caution"><strong>Important</strong>: You can remove the subscription |
| 236 | product from the product list offered in your app to prevent users from seeing |
| 237 | or purchasing it.</p> |
| 238 | |
| 239 | <h2 id="cancellation">Subscription Cancellation</h2> |
| 240 | |
| 241 | <p>Users can view the status of all of their subscriptions and cancel them if |
| 242 | necessary from the <strong>My Apps</strong> screen in the Play Store app. |
| 243 | Currently, the In-app Billing API does not provide support for programatically |
| 244 | canceling subscriptions from inside the purchasing app.</p> |
| 245 | |
| 246 | <p>When the user cancels a subscription, Google Play does not offer a refund for |
| 247 | the current billing cycle. Instead, it allows the user to have access to the |
| 248 | cancelled subscription until the end of the current billing cycle, at which time |
| 249 | it terminates the subscription. For example, if a user purchases a monthly |
| 250 | subscription and cancels it on the 15th day of the cycle, Google Play will |
| 251 | consider the subscription valid until the end of the 30th day (or other day, |
| 252 | depending on the month).</p> |
| 253 | |
| 254 | <p>In some cases, the user may contact you directly to request cancellation of a |
| 255 | subscription. In this and similar cases, you can use the server-side API to |
| 256 | query and directly cancel the user’s subscription from your servers. |
| 257 | |
| 258 | <p class="caution"><strong>Important:</strong> In all cases, you must continue |
| 259 | to offer the content that your subscribers have purchased through their |
| 260 | subscriptions, for as long any users are able to access it. That is, you must |
| 261 | not remove any subscriber’s content while any user still has an active |
| 262 | subscription to it, even if that subscription will terminate at the end of the |
| 263 | current billing cycle. Removing content that a subscriber is entitled to access |
| 264 | will result in penalties. Please see the <a |
| 265 | href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies document</a> for more information. </p> |
| 266 | |
| 267 | <h3 id="uninstall">App uninstallation</h3> |
| 268 | |
| 269 | <p>When the user uninstalls an app that includes purchased subscriptions, the |
| 270 | Play Store app will notify the user that there are active subscriptions. If the |
| 271 | user chooses to continue with the uninstallation, the app is removed and the |
| 272 | subscriptions remain active and recurring billing continues. The user can return |
| 273 | to cancel the associated subscriptions at any time in the <strong>My Apps</strong> |
| 274 | screen of the Play Store app. If the user chooses to cancel the uninstallation, |
| 275 | the app and subscriptions remain as they were.</p> |
| 276 | |
| 277 | <h3 id="refunds">Refunds</h3> |
| 278 | |
| 279 | <p>With subscriptions, Google Play does not provide a refund window, so users |
| 280 | will need to contact you directly to request a refund. |
| 281 | |
| 282 | <p>If you receive requests for refunds, you can use the server-side API to |
| 283 | cancel the subscription or verify that it is already cancelled. However, keep in |
| 284 | mind that Google Play considers cancelled subscriptions valid until the end of |
| 285 | their current billing cycles, so even if you grant a refund and cancel the |
| 286 | subscription, the user will still have access to the content. |
| 287 | |
| 288 | <p class="caution"><strong>Important:</strong> Partial refunds for canceled |
| 289 | subscriptions are not available at this time.</p> |
| 290 | |
| 291 | <h2 id="payment">Payment Processing and Policies</h2> |
| 292 | |
| 293 | <p>In general, the terms of Google Play allow you to sell in-app subscriptions |
| 294 | only through the standard payment processor, Google Checkout. For purchases of |
| 295 | any subscription products, the transaction fee is the same as the transaction |
| 296 | fee for application purchases (30%).</p> |
| 297 | |
| 298 | <p>Apps published on Google Play that are selling subscriptions must use In-app |
| 299 | Billing to handle the transaction and may not provide links to a purchase flow |
| 300 | outside of the app and Google Play (such as to a web site).</p> |
| 301 | |
| 302 | <p>For complete details about terms and policies, see the <a |
| 303 | href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies |
| 304 | document</a>.</p> |
| 305 | |
| 306 | <h3 id="orderId">Subscription order numbers</h3> |
| 307 | |
| 308 | <p>To help you track transactions relating to a given subscription, Google |
| 309 | Checkout provides a base Merchant Order Number for all recurrences of the |
| 310 | subscription and denotes |
| 311 | each recurring transaction by appending an integer as follows: </p> |
| 312 | |
| 313 | <p><span style="color:#777"><code style="color:#777">12999556515565155651.5565135565155651</code> (base order number)</span><br /> |
| 314 | <code>12999556515565155651.5565135565155651..0</code> (initial purchase orderID)<br /> |
| 315 | <code>12999556515565155651.5565135565155651..1</code> (first recurrence orderID)<br /> |
| 316 | <code>12999556515565155651.5565135565155651..2</code> (second recurrence orderID)<br /> |
| 317 | ...<br /></p> |
| 318 | |
| 319 | <p>Google Play provides the order number as the value of the |
| 320 | {@code orderId} field of the {@code INAPP_PURCHASE_DATA} JSON field (in V3) |
| 321 | or the {@code PURCHASE_STATE_CHANGED} intent (in V2).</p> |
| 322 | |
| 323 | <h2 id="play-dev-api">Google Play Android Developer API</h2> |
| 324 | |
| 325 | <p>Google Play offers an HTTP-based API that you can use to remotely query the |
| 326 | validity of a specific subscription at any time or cancel a subscription. The |
| 327 | API is designed to be used from your backend servers as a way of securely |
| 328 | managing subscriptions, as well as extending and integrating subscriptions with |
| 329 | other services.</p> |
| 330 | |
| 331 | <h3 id="using">Using the API</h3> |
| 332 | |
| 333 | <p>To use the API, you must first register a project at the <a |
| 334 | href="https://code.google.com/apis/console">Google APIs Console</a> and receive |
| 335 | a Client ID and shared secret that your app will present when calling the |
| 336 | Google Play Android Developer API. All calls to the API are authenticated with |
| 337 | OAuth 2.0.</p> |
| 338 | |
| 339 | <p>Once your app is registered, you can access the API directly, using standard |
| 340 | HTTP methods to retrieve and manipulate resources, or you can use the Google |
| 341 | APIs Client Libraries, which are extended to support the API.</p> |
| 342 | |
| 343 | <p>The Google Play Android Developer API is built on a RESTful design that uses |
| 344 | HTTP and JSON, so any standard web stack can send requests and parse the |
| 345 | responses. However, if you don’t want to send HTTP requests and parse responses |
| 346 | manually, you can access the API using the client libraries, which provide |
| 347 | better language integration, improved security, and support for making calls |
| 348 | that require user authorization.</p> |
| 349 | |
| 350 | <p>For more information about the API and how to access it through the Google |
| 351 | APIs Client Libraries, see the documentation at:</p> |
| 352 | |
| 353 | <p style="margin-left:1.5em;"><a |
| 354 | href="https://developers.google.com/android-publisher/v1/">https://developers. |
| 355 | google.com/android-publisher/v1/</a></p> |
| 356 | |
| 357 | <h3 id="quota">Quota</h3> |
| 358 | |
| 359 | <p>Applications using the Google Play Android Developer API are limited to an |
| 360 | initial courtesy usage quota of <strong>15000 requests per day</strong> (per |
| 361 | application). This should provide enough access for normal |
| 362 | subscription-validation needs, assuming that you follow the recommendation in |
| 363 | this section.</p> |
| 364 | |
| 365 | <p>If you need to request a higher limit for your application, please use the |
| 366 | “Request more” link in the <a |
| 367 | href="https://code.google.com/apis/console/#:quotas">Google APIs Console</a>. |
| 368 | Also, please read the section below on design best practices for minimizing your |
| 369 | use of the API.</p> |
| 370 | |
| 371 | <h3 id="auth">Authorization</h3> |
| 372 | |
| 373 | <p>Calls to the Google Play Android Developer API require authorization. Google |
| 374 | uses the OAuth 2.0 protocol to allow authorized applications to access user |
| 375 | data. To learn more, see <a |
| 376 | href="https://developers.google.com/android-publisher/authorization">Authorization</a> |
| 377 | in the Google Play Android Developer API documentation.</p> |
| 378 | |
| 379 | <h3 id="practices">Using the API efficiently</h3> |
| 380 | |
| 381 | <p>Access to the Google Play Android Developer API is regulated to help ensure a |
| 382 | high-performance environment for all applications that use it. While you can |
| 383 | request a higher daily quota for your application, we highly recommend that you |
| 384 | minimize your access using the technique(s) below. </p> |
| 385 | |
| 386 | <ul> |
| 387 | <li><em>Store subscription expiry on your servers</em> — your servers |
| 388 | should use the Google Play Android Developer API to query the expiration date |
| 389 | for new subscription tokens, then store the expiration date locally. This allows |
| 390 | you to check the status of subscriptions only at or after the expiration (see |
| 391 | below). </li> |
| 392 | <li><em>Cache expiration and purchaseState</em> — If your app contacts |
| 393 | your backend servers at runtime to verify subscription validity, your server |
| 394 | should cache the expiration and purchaseState to ensure the fastest possible |
| 395 | response (and best experience) for the user.</li> |
| 396 | <li><em>Query for subscription status only at expiration</em> — Once your |
| 397 | server has retrieved the expiration date of subscription tokens, it should not |
| 398 | query the Google Play servers for the subscription status again until the |
| 399 | subscription is reaching or has passed the expiration date. Typically, your |
| 400 | servers would run a batch query each day to check the status of |
| 401 | <em>expiring</em> subscriptions, then update the database. Note that: |
| 402 | <ul> |
| 403 | <li>Your servers should not query all subscriptions every day</li> |
| 404 | <li>Your servers should never query subscription status dynamically, based on |
| 405 | individual requests from your Android application. </li> |
| 406 | </ul> |
| 407 | </li> |
| 408 | </ul> |
| 409 | |
| 410 | <p>By following those general guidelines, your implementation will offer the |
| 411 | best possible performance for users and minimize use of the Google Play Android |
| 412 | Developer API.</p> |
| 413 | |
| 414 | |