Merge "docs: Updated In-app Billing docs to support subscriptions for V3." into jb-mr1-dev

11 files changed, 574 insertions, 634 deletions

diff --git a/docs/html/google/google_toc.cs b/docs/html/google/google_toc.cs
index 8b09fe6..81982a1 100644
--- a/docs/html/google/google_toc.cs
+++ b/docs/html/google/google_toc.cs
@@ -80,6 +80,9 @@
               <span class="en">Reference</span></a></li>
               </ul>
       </li>
+      <li><a href="<?cs var:toroot?>google/play/billing/billing_subscriptions.html">
+              <span class="en">Subscriptions</span></a>
+      </li>
       <li><a href="<?cs var:toroot?>google/play/billing/billing_best_practices.html">
               <span class="en">Security and Design</span></a>
       </li>
diff --git a/docs/html/google/play/billing/api.jd b/docs/html/google/play/billing/api.jd
index 9091f51..3d46715 100644
--- a/docs/html/google/play/billing/api.jd
+++ b/docs/html/google/play/billing/api.jd
@@ -11,12 +11,13 @@ parent.link=index.html
     <li><a href="#producttypes">Product Types</a>
        <ol>
        <li><a href="#managed">Managed In-app Products</a><li>
+       <li><a href="#subs">Subscriptions</a><li>
        </ol>
     </li>
     <li><a href="#purchase">Purchasing Items</a></li>
-    <li><a href="#consume">Consuming Items</a>
+    <li><a href="#consume">Consuming In-app Products</a>
        <ol>
-       <li><a href="#consumetypes">Non-consumable and Consumable Items</a><li>
+       <li><a href="#consumetypes">Non-consumable and Consumable In-app Products</a><li>
        <li><a href="#managingconsumables">Managing Consumable Purchases</a><li>
        </ol>
     </li>
@@ -40,11 +41,22 @@ parent.link=index.html
 
 <h2 id="producttypes">Product Types</h2>
 <p>You define your products using the Google Play Developer Console, including product type, SKU, price, description, and so on. For more information, see <a
-href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app Billing</a>. The Version 3 API only supports the managed in-app product type.</p>
+href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app Billing</a>. The Version 3 API supports managed in-app products and subscriptions.</p>
 <h3 id="managed">Managed In-app Products</h3>
 <p>Managed in-app products are items that have their ownership information tracked and managed by Google Play. When a user purchases a managed in-app item, Google Play stores the purchase information for each item on a per-user basis. This enables you to later query Google Play at any time to restore the state of the items a specific user has purchased. This information is persistent on the Google Play servers even if the user uninstalls the application or if they change devices.</p>
 <p>If you are using the Version 3 API, you can also consume managed items within your application. You would typically implement consumption for items that can be purchased multiple times (such as in-game currency, fuel, or magic spells). Once purchased, a managed item cannot be purchased again until you consume the item, by sending a consumption request to Google Play. To learn more about in-app product consumption, see <a href="#consume">Consuming Items</a></p>
 
+<h3 id="subs">Subscriptions</h3>
+<p>A subscription is a product type offered in In-app Billing that lets you sell 
+content, services, or features to users from inside your app with recurring 
+monthly or annual billing. You can sell subscriptions to almost any type of 
+digital content, from any type of app or game. To understand how  
+subscriptions work, see <a href="{@docRoot}google/play/billing/billing_subscriptions.html">In-app Billing Subscriptions</a>.</p>
+<p>With the Version 3 API, you can use the same purchase flow for buying 
+subscriptions and retrieving subscription purchase information as with in-app 
+products. For a code example, see <a href="{@docRoot}google/play/billing/billing_integrate.html#Subs">Implementing Subscriptions</a>.</p>
+<p class="caution"><strong>Important</strong>: Unlike in-app products, 
+subscriptions cannot be consumed.</p>
 
 <h2 id="purchase">Purchasing Items</h2>
 
@@ -72,29 +84,38 @@ href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app Bil
 </p>
 <p>To learn more about the Version 3 API calls and server responses, see <a href="{@docRoot}google/play/billing/billing_reference.html">In-app Billing Reference</a>.</p>
 
-<h2 id="consume">Consuming Items</h2>
-<p>You can use the consumption mechanism to track the user's ownership of in-app products.</p>
-<p>In Version 3, all in-app products are managed. This means that the user's ownership of all in-app item purchases is maintained by Google Play, and your application can query the user's purchase information when needed. When the user successfully purchases an item, that purchase is recorded in Google Play. Once an item is purchased, it is considered to be "owned". Items in the "owned" state cannot be purchased from Google Play. You must send a consumption request for the "owned" item before Google Play makes it available for purchase again. Consuming the item reverts it to the "unowned" state, and discards the previous purchase data.</p>
+<h2 id="consume">Consuming In-app Products</h2>
+<p>You can use the consumption mechanism to track the user's ownership of in-app 
+products.</p>
+<p>In Version 3, all in-app products are managed. This means that the user's 
+ownership of all in-app item purchases is maintained by Google Play, and your 
+application can query the user's purchase information when needed. When the user 
+successfully purchases an in-app product, that purchase is recorded in Google 
+Play. Once an in-app product is purchased, it is considered to be "owned". 
+In-app products in the "owned" state cannot be purchased from Google Play. You 
+must send a consumption request for the "owned" in-app product before Google 
+Play makes it available for purchase again. Consuming the in-app product reverts 
+it to the "unowned" state, and discards the previous purchase data.</p>
 <div class="figure" style="width:420px">
 <img src="{@docRoot}images/in-app-billing/v3/iab_v3_consumption_flow.png" id="figure2" height="300"/>
 <p class="img-caption">
   <strong>Figure 2.</strong> The basic sequence for a consumption request.
 </p>
 </div>
-<p>To retrieve the list of product's owned by the user, your application sends a {@code getPurchases} call to Google Play. Your application can make a consumption request by sending a {@code consumePurchase} call. In the request argument, you must specify the item's unique {@code purchaseToken} String that you obtained from Google Play when it was purchased. Google Play returns a status code indicating if the consumption was recorded successfully.</p>
+<p>To retrieve the list of product's owned by the user, your application sends a {@code getPurchases} call to Google Play. Your application can make a consumption request by sending a {@code consumePurchase} call. In the request argument, you must specify the in-app product's unique {@code purchaseToken} String that you obtained from Google Play when it was purchased. Google Play returns a status code indicating if the consumption was recorded successfully.</p>
 
-<h3 id="consumetypes">Non-consumable and Consumable Items</h3>
+<h3 id="consumetypes">Non-consumable and Consumable In-app Products</h3>
 <p>It's up to you to decide if you want to handle your in-app products as non-consumable or consumable items.</p>
 <dl>
 <dt>Non-consumable Items</dt>
-<dd>Typically, you would not implement consumption for items that can only be purchased once in your application and provide a permanent benefit. Once purchased, these items will be permanently associated to the user's Google account. An example of a non-consumable item is a premium upgrade or a level pack.</dd>
+<dd>Typically, you would not implement consumption for in-app products that can only be purchased once in your application and provide a permanent benefit. Once purchased, these items will be permanently associated to the user's Google account. An example of a non-consumable in-app product is a premium upgrade or a level pack.</dd>
 <dt>Consumable items</dt>
 <dd>In contrast, you can implement consumption for items that can be made available for purchase multiple times. Typically, these items provide certain temporary effects. For example, the user's in-game character might gain life points or gain extra gold coins in their inventory. Dispensing the benefits or effects of the purchased item in your application is called <em>provisioning</em> the in-app product. You are responsible for controlling and tracking how in-app products are provisioned to the users.
-<p class="note"><strong>Important:</strong> Before provisioning the consumable item in your application, you must send a consumption request to Google Play and receive a successful response indicating that the consumption was recorded.</p>
+<p class="note"><strong>Important:</strong> Before provisioning the consumable in-app product in your application, you must send a consumption request to Google Play and receive a successful response indicating that the consumption was recorded.</p>
 </dd>
 </dl>
 <h3 id="managingconsumables">Managing consumable purchases in your application</h3>
-<p>Here is the basic flow for purchasing a consumable item:</p>
+<p>Here is the basic flow for purchasing a consumable in-app product:</p>
 <ol>
 <li>Launch a purchase flow with a {@code getBuyIntent} call</li>
 <li>Get a response {@code Bundle}from Google Play indicating if the purchase completed successfully.</li>
@@ -102,10 +123,10 @@ href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app Bil
 <li>Get a response code from Google Play indicating if the consumption completed successfully.</li>
 <li>If the consumption was successful, provision the product in your application.</li>
 </ol>
-<p>Subsequently, when the user starts up or logs in to your application, you should check if the user owns any outstanding consumable items; if so, make sure to consume and provision those items. Here's the recommended application startup flow if you implement consumable items in your application:</p>
+<p>Subsequently, when the user starts up or logs in to your application, you should check if the user owns any outstanding consumable in-app products; if so, make sure to consume and provision those items. Here's the recommended application startup flow if you implement consumable in-app products in your application:</p>
 <ol>
-<li>Send a {@code getPurchases} request to query the owned items for the user.</li>
-<li>If there are any consumable items, consume the items by calling {@code consumePurchase}. This step is necessary because the application might have completed the purchase order for the consumable item, but stopped or got disconnected before the application had the chance to send a consumption request.</li>
+<li>Send a {@code getPurchases} request to query the owned in-app products for the user.</li>
+<li>If there are any consumable in-app products, consume the items by calling {@code consumePurchase}. This step is necessary because the application might have completed the purchase order for the consumable item, but stopped or got disconnected before the application had the chance to send a consumption request.</li>
 <li>Get a response code from Google Play indicating if the consumption completed successfully.</li>
 <li>If the consumption was successful, provision the product in your application.</li>
 </ol>
diff --git a/docs/html/google/play/billing/billing_integrate.jd b/docs/html/google/play/billing/billing_integrate.jd
index 315befa..297e906 100755
--- a/docs/html/google/play/billing/billing_integrate.jd
+++ b/docs/html/google/play/billing/billing_integrate.jd
@@ -16,6 +16,7 @@ parent.link=index.html
        <li><a href="#Purchase">Purchasing an Item</a></li>
        <li><a href="#QueryPurchases">Querying Purchased Items</a></li>
        <li><a href="#Consume">Consuming a Purchase</a><li>
+       <li><a href="#Subs">Implementing Subscriptions</a><li>
        </ol>
     </li>
   </ol>
@@ -176,7 +177,7 @@ if (response == 0) {
 </pre>
 
 <h3 id="Purchase">Purchasing an Item</h3>
-<p>To start a purchase request from your app, call the {@code getBuyIntent} method on the In-app Billing service. Pass in to the method the In-app Billing API version (“3”), the package name of your calling app, the product ID for the item to purchase, the purchase type (“inapp”), and a {@code developerPayload} String. The {@code developerPayload} String is used to  specify any additional arguments that you want Google Play to send back along with the purchase information.</p>
+<p>To start a purchase request from your app, call the {@code getBuyIntent} method on the In-app Billing service. Pass in to the method the In-app Billing API version (“3”), the package name of your calling app, the product ID for the item to purchase, the purchase type (“inapp” or "subs"), and a {@code developerPayload} String. The {@code developerPayload} String is used to  specify any additional arguments that you want Google Play to send back along with the purchase information.</p>
 
 <pre>
 Bundle buyIntentBundle = mService.getBuyIntent(3, getPackageName(),
@@ -238,7 +239,7 @@ protected void onActivityResult(int requestCode, int resultCode, Intent data) {
 <p class="note"><strong>Security Recommendation:</strong> When you send a purchase request, create a String token that uniquely identifies this purchase request and include this token in the {@code developerPayload}.You can use a randomly generated string as the token. When you receive the purchase response from Google Play, make sure to check the returned data signature, the {@code orderId}, and the {@code developerPayload} String. For added security, you should perform the checking on your own secure server. Make sure to verify that the {@code orderId} is a unique value that you have not previously processed, and the {@code developerPayload} String matches the token that you sent previously with the purchase request.</p>
 
 <h3 id="QueryPurchases">Querying for Purchased Items</h3>
-<p>To retrieve information about purchases made by a user from your app, call the {@code getPurchases} method on the In-app Billing Version 3 service. Pass in to the method the In-app Billing API version (“3”), the package name of your calling app, and the purchase type (“inapp”).</p>
+<p>To retrieve information about purchases made by a user from your app, call the {@code getPurchases} method on the In-app Billing Version 3 service. Pass in to the method the In-app Billing API version (“3”), the package name of your calling app, and the purchase type (“inapp” or "subs").</p>
 <pre>
 Bundle ownedItems = mService.getPurchases(3, getPackageName(), "inapp", null);
 </pre>
@@ -273,8 +274,26 @@ if (response == 0) {
 </pre>
 
 <h3 id="Consume">Consuming a Purchase</h3>
-<p>You can use the In-app Billing Version 3 API to track the ownership of purchased items in Google Play. Once an item is purchased, it is considered to be "owned" and cannot be purchased from Google Play. You must send a consumption request for the item before Google Play makes it available for purchase again. All managed in-app products are consumable.  How you use the consumption mechanism in your app is up to you. Typically, you would implement consumption for products with temporary benefits that users may want to purchase multiple times (for example, in-game currency or equipment). You would typically not want to implement consumption for products that are purchased once and provide a permanent effect (for example, a premium upgrade).</p>
-<p>To record a purchase consumption, send the {@code consumePurchase} method to the In-app Billing service and pass in the {@code purchaseToken} String value that identifies the purchase to be removed. The {@code purchaseToken} is part of the data returned in the {@code INAPP_PURCHASE_DATA} String by the Google Play service following a successful purchase request. In this example, you are recording the consumption of a product that is identified with the {@code purchaseToken} in the {@code token} variable.</p>
+<p>You can use the In-app Billing Version 3 API to track the ownership of 
+purchased in-app products in Google Play. Once an in-app product is purchased, 
+it is considered to be "owned" and cannot be purchased from Google Play. You 
+must send a consumption request for the in-app product before Google Play makes 
+it available for purchase again.</p>
+<p class="caution"><strong>Important</strong>: Managed in-app products are 
+consumable, but subscriptions are not.</p>
+<p>How you use the consumption mechanism in your app is up to you. Typically, 
+you would implement consumption for in-app products with temporary benefits that 
+users may want to purchase multiple times (for example, in-game currency or 
+equipment). You would typically not want to implement consumption for in-app 
+products that are purchased once and provide a permanent effect (for example, 
+a premium upgrade).</p>
+<p>To record a purchase consumption, send the {@code consumePurchase} method to 
+the In-app Billing service and pass in the {@code purchaseToken} String value 
+that identifies the purchase to be removed. The {@code purchaseToken} is part 
+of the data returned in the {@code INAPP_PURCHASE_DATA} String by the Google 
+Play service following a successful purchase request. In this example, you are 
+recording the consumption of a product that is identified with the 
+{@code purchaseToken} in the {@code token} variable.</p>
 <pre>
 int response = mService.consumePurchase(3, getPackageName(), token);
 </pre>
@@ -282,6 +301,33 @@ int response = mService.consumePurchase(3, getPackageName(), token);
 <p>It's your responsibility to control and track how the in-app product is provisioned to the user. For example, if the user purchased in-game currency, you should update the player's inventory with the amount of currency purchased.</p>
 <p class="note"><strong>Security Recommendation:</strong> You must send a consumption request before provisioning the benefit of the consumable in-app purchase to the user. Make sure that you have received a successful consumption response from Google Play before you provision the item.</p>
 
+<h3 id="Subs">Implementing Subscriptions</h3>
+<p>Launching a purchase flow for a subscription is similar to launching the 
+purchase flow for a product, with the exception that the product type must be set 
+to "subs". The purchase result is delivered to your Activity's 
+{@link android.app.Activity#onActivityResult onActivityResult} method, exactly 
+as in the case of in-app products.</p>
+<pre>
+Bundle bundle = mService.getBuyIntent(3, "com.example.myapp",
+   MY_SKU, "subs", developerPayload);
+
+PendingIntent pendingIntent = bundle.getParcelable(RESPONSE_BUY_INTENT);
+if (bundle.getInt(RESPONSE_CODE) == BILLING_RESPONSE_RESULT_OK) {
+   // Start purchase flow (this brings up the Google Play UI).
+   // Result will be delivered through onActivityResult().
+   startIntentSenderForResult(pendingIntent, RC_BUY, new Intent(),
+       Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0));
+}
+</pre>
+<p>To query for active subscriptions, use the {@code getPurchases} method, again 
+with the product type parameter set to "subs".</p>
+<pre>
+Bundle activeSubs = mService.getPurchases(3, "com.example.myapp",
+                   "subs", continueToken);
+</pre>
+<p>The call returns a {@code Bundle} with all the active subscriptions owned by 
+the user. Once a subscription expires without renewal, it will no longer appear 
+in the returned {@code Bundle}.</p>
 
 
 
diff --git a/docs/html/google/play/billing/billing_overview.jd b/docs/html/google/play/billing/billing_overview.jd
index aa48fc8..bda9237 100755
--- a/docs/html/google/play/billing/billing_overview.jd
+++ b/docs/html/google/play/billing/billing_overview.jd
@@ -7,9 +7,12 @@ parent.link=index.html
 <div id="qv">
   <h2>Quickview</h2>
   <ul>
-    <li>Use In-app Billing to sell digital goods, including one-time items and recurring subscriptions.</li>
-    <li>Supported for any app published on Google Play. You only need a Google Play publisher account and a Google Checkout Merchant account.</li>
-    <li>Checkout processing is automatically handled by Google Play, with the same look-and-feel as for app purchases.</li>
+    <li>Use In-app Billing to sell digital goods, including one-time items and 
+recurring subscriptions.</li>
+    <li>Supported for any app published on Google Play. You only need a Google 
+Play Developer Console account and a Google Checkout Merchant account.</li>
+    <li>Checkout processing is automatically handled by Google Play, with the 
+same look-and-feel as for app purchases.</li>
   </ul>
   <h2>In this document</h2>
   <ol>
@@ -21,14 +24,12 @@ parent.link=index.html
     </li>
     <li><a href="#console">Google Play Developer Console</a></li>
     <li><a href="#checkout">Google Play Purchase Flow</a></li>
-    <li><a href="#samples">Sample Apps</a></li> 
+    <li><a href="#samples">Sample App</a></li> 
     <li><a href="#migration">Migration Considerations</a></li>
   </ol>
    <h2>Related Samples</h2>
   <ol>
     <li><a href="{@docRoot}training/in-app-billing/preparing-iab-app.html#GetSample">Sample Application (V3)</a></li>
-    <li><a href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">Sample
-    Application (V2)</a></li>
   </ol> 
 </div>
 </div>
@@ -51,10 +52,12 @@ the Google Play server.</p>
 through Google Play. To complete in-app purchase requests, the Google Play app 
 must be able to access the Google Play server over the network.</p>
 
-<p>Currently, Google Play supports two versions of the In-app Billing API. 
-To determine which version you should use, see <a href="#migration">Migration 
-Considerations</a>.</p>
-<h4><a href="{@docRoot}google/play/billing/api.html">Version 3</a> (recommended)</h4>
+<p>In-app billing Version 3 is the latest version, and maintains very broad 
+compatibility across the range of Android devices. In-app Billing Version 3 is 
+supported on devices running Android 2.2 or higher that have the latest version 
+of the Google Play store installed (<a href="{@docRoot}about/dashboards/index.html">a vast majority</a> of active devices).</p>
+
+<h4>Version 3 features</h4>
 <ul>
 <li>Requests are sent through a streamlined API that allows you to easily request 
 product details from Google Play, order in-app products, and quickly restore 
@@ -66,21 +69,10 @@ ownership of in-app products). The user cannot own multiple copies of an in-app
 item; only one copy can be owned at any point in time</li>
 <li>Purchased items can be consumed. When consumed, the item reverts to the 
 "unowned" state and can be purchased again from Google Play</li>
+<li>Provides support for subscriptions</li>
 </ul>
-<h4><a href="{@docRoot}google/play/billing/v2/api.html">Version 2</a></h4>
-<ul>
-<li>Requests are sent via a single API interface ({@code sendBillingRequest})</li>
-<li>Responses from Google Play are asynchronous, in the form of broadcast intents</li>
-<li>No consumption model provided. You have to implement your own solution</li>
-<li>Provides support for subscriptions and unmanaged in-app purchase items, 
-as well as managed in-app products</li>
-</ul>
-<p>Both versions offer very broad compatibility across the range of Android 
-devices. In-app Billing Version 3 is supported on devices running Android 2.2 or 
-higher that have the latest version of the Google Play store installed 
-(over 90% of active devices). Version 2 offers similar compatibility. See 
-<a href="{@docRoot}google/play/billing/versions.html">Version Notes</a> for 
-more details.</p>
+<p>For details about other versions of In-app Billing, see the 
+<a href="{@docRoot}google/play/billing/versions.html">Version Notes</a>.</p>
 
 <h2 id="products">In-app Products</h2>
 <p>In-app products are the digital goods that you offer for sale from inside your 
@@ -102,12 +94,9 @@ published for another app, even if they are from the same developer.</p>
 how you monetize your application. In all cases, you define your products using 
 the Google Play Developer Console.</p>
 <p>You can specify these types of products for your In-app Billing application  
-— <em>managed in-app products</em>, <em>subscriptions</em>, and <em>unmanaged 
-in-app products</em>.  The term “managed” indicates that Google Play handles and 
-tracks ownership for in-app products on your application on a per user account 
-basis, while “unmanaged” indicates that you will manage the ownership  information yourself.</p>
-<p>To learn more about the product types supported by the different API versions, 
-see the related documentation for <a href="{@docRoot}google/play/billing/v2/api.html#billing-types">Version 2</a> and <a href="{@docRoot}google/play/billing/api.html#producttypes">Version 3</a>.</p>
+— <em>managed in-app products</em> and <em>subscriptions</em>. Google Play 
+handles and tracks ownership for in-app products and subscriptions on your 
+application on a per user account basis. <a href="{@docRoot}google/play/billing/api.html#producttypes">Learn more about the product types supported by In-app Billing Version 3</a>.</p>
 
 <h2 id="console">Google Play Developer Console</h2>
 <p>The Developer Console is where you can publish your 
@@ -148,70 +137,31 @@ providing the checkout user interface (middle screen). When checkout is
 complete, the application resumes.
 </p>
 
-<h2 id="samples">Sample Applications</h2>
+<h2 id="samples">Sample Application</h2>
 <p>To help you integrate In-app Billing into your application, the Android SDK 
-provides two sample applications that demonstrate how to sell in-app products 
+provides a sample application that demonstrates how to sell in-app products and subscriptions 
 from inside an app.</p>
 
-<dl>
-<dt><a href="{@docRoot}training/in-app-billing/preparing-iab-app.html#GetSample">TrivialDrive sample for the Version 3 API</a></dt>
-<dd>This sample shows how to use the In-app Billing Version 3 API to implement 
-in-app product purchases for a driving game. The application demonstrates how to 
-send In-app Billing requests, and handle synchronous responses from Google Play. 
-The application also shows how to record item consumption with the API. The 
-Version 3 sample includes convenience classes for processing In-app Billing 
-operations as well as perform automatic signature verification.</dd>
-
-<dt><a href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">Dungeons sample for the Version 2 API</a></dt>
-<dd>This sample demonstrates how to use the In-app Billing Version 2 API to sell 
-standard in-app products and subscriptions for an adventuring game. It also 
-contains examples of the database, user interface, and business logic you might 
-use to implement In-app Billing.</dd>
-</dl>
-<p class="caution"><strong>Important</strong>: It's <em>strongly recommended</em> 
-that you obfuscate the code in your application before you publish it. For 
-more information, see
+<p>The <a href="{@docRoot}training/in-app-billing/preparing-iab-app.html#GetSample">TrivialDrive sample for the Version 3 API</a> sample shows how to use the In-app Billing Version 3 API 
+to implement in-app product and subscription purchases for a driving game. The 
+application demonstrates how to send In-app Billing requests, and handle 
+synchronous responses from Google Play. The application also shows how to record 
+item consumption with the API. The Version 3 sample includes convenience classes 
+for processing In-app Billing operations as well as perform automatic signature 
+verification.</p>
+
+<p class="caution"><strong>Recommendation</strong>: Make sure to obfuscate the 
+code in your application before you publish it. For more information, see
 <a href="{@docRoot}google/play/billing/billing_best_practices.html">Security 
 and Design</a>.</p>
 
 <h2 id="migration">Migration Considerations</h2>
-<p>The following considerations may be applicable if you are planning to create a new 
-in-app biling application, or migrate your existing In-app Billing implementation 
-from the <a href="{@docRoot}google/play/billing/v2/api.html">Version 2</a> or 
-earlier API to the <a href="{@docRoot}google/play/billing/api.html">Version 3</a> API.</p>
-<p>Google Play will continue to support both the Version 2 and Version 3 APIs for 
-some time, so you can plan to migrate to Version 3 at your own pace. The Google 
-Play team will give advance notice of any upcoming changes to the support 
-status of In-app Billing Version 2.</p>
-<p>You can use the following table to decide which version of the API to use, 
-depending on the needs of your application.</p>
-<p class="table-caption" id="table1">
-  <strong>Table 1.</strong> Selecting the In-app Billing API Version for Your 
-Project</p>
-
-<table>
-<tr>
-<th scope="col">Choose Version 3 if ...</th>
-<th scope="col">Choose Version 2 if ...</th>
-</tr>
-<tr>
-<td>
-  <ul>
-  <li>You want to sell in-app products only (and not subscriptions)</li>
-  <li>You need synchronous order confirmations when purchases complete</li>
-  <li>You need to synchronously restore a user's current purchases</li>
-  </ul>
-</td>
-<td>
-  <ul>
-  <li>You want to sell subscriptions in your app</li>
-  </ul>
-</td>
-</tr>
-</table>
+<p>If you have an existing In-app Billing implementation that uses Version 2 or
+earlier, it is strongly recommended that you migrate to <a href="{@docRoot}google/play/billing/api.html">In-app Billing Version 3</a> at your earliest convenience.</p>
+
 <p>If you have published apps selling in-app products, note that:</p>
 <ul>
-<li>Managed items that you have previously defined in the Developer Console will 
+<li>Managed items and subscriptions that you have previously defined in the Developer Console will 
 work with Version 3 as before.</li>
 <li>Unmanaged items that you have defined for existing applications will be 
 treated as managed products if you make a purchase request for these items using 
diff --git a/docs/html/google/play/billing/billing_reference.jd b/docs/html/google/play/billing/billing_reference.jd
index 758e21d..ae41521 100755
--- a/docs/html/google/play/billing/billing_reference.jd
+++ b/docs/html/google/play/billing/billing_reference.jd
@@ -102,11 +102,13 @@ parent.link=index.html
   </tr>
   <tr>
     <td>{@code type}</td>
-    <td>Value must be “inapp” for an in-app purchase type.</td>
+    <td>Value must be “inapp” for an in-app product or "subs" for 
+subscriptions.</td>
   </tr>
   <tr>
     <td>{@code price}</td>
-    <td>Formatted price of the item, including its currency sign. The price does not include tax.</td>
+    <td>Formatted price of the item, including its currency sign. The price 
+does not include tax.</td>
   </tr>
   <tr>
     <td>{@code title}</td>
diff --git a/docs/html/google/play/billing/billing_subscriptions.jd b/docs/html/google/play/billing/billing_subscriptions.jd
new file mode 100644
index 0000000..2840dbc
--- /dev/null
+++ b/docs/html/google/play/billing/billing_subscriptions.jd
@@ -0,0 +1,414 @@
+page.title=Subscriptions
+parent.title=In-app Billing
+parent.link=index.html
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+  <h2>Quickview</h2>
+  <ul>
+     <li>Users purchase your subscriptions from inside your apps, rather than 
+directly from Google Play.</li>
+     <li>Subscriptions let you sell products with automated, recurring billing
+(monthly or annual).</li>
+     <li>You can offer a configurable trial period for any subscription.</li>
+
+  </ul>
+  <h2>In this document</h2>
+  <ol>
+    <li><a href="#overview">Overview</a></li>
+    <li><a href="#administering">Configuring Subscriptions Items</a></li>
+    <li><a href="#cancellation">Cancellation</a></li>
+    <li><a href="#payment">Payment Processing</a></li>
+    <li><a href="#play-dev-api">Google Play Android Developer API</a></li>
+  </ol>
+  <h2>See also</h2>
+  <ol>
+    <li><a href="{@docRoot}google/play/billing/billing_integrate.html#Subs">Implementing Subscriptions (V3)</a></li>
+  </ol>
+</div>
+</div>
+
+<p>Subscriptions let you sell content, services, or features in your app with
+automated, recurring billing. You can easily adapt an existing In-app Billing 
+implementation to sell subscriptions.</p>
+<p>This document is focused on highlighting implementation details that are 
+specific to subscriptions, along with some strategies for the associated billing 
+and business models.</p>
+
+<h2 id="overview">Overview of Subscriptions</h2>
+<p>A <em>subscription</em> is a product type offered in In-app Billing that 
+lets you sell content, services, or features to users from inside your app with 
+recurring monthly or annual billing. You can sell subscriptions to almost any 
+type of digital content, from any type of app or game.</p>
+
+<p>As with other in-app products, you configure and publish subscriptions using
+the Developer Console and then sell them from inside apps installed on 
+Android devices. In the Developer console, you create subscription
+products and add them to a product list, then set a price and optional trial
+period for each, choose a billing interval (monthly or annual), and then 
+publish. For more information about using the Developer Console, see 
+<a href="#administering">Configuring Subscription Items</a>.</p>
+
+<p>When users purchase subscriptions in your apps, Google Play handles all 
+checkout details so your apps never have to directly process any financial 
+transactions. Google Play processes all payments for subscriptions through 
+Google Checkout, just as it does for standard in-app products and app purchases. 
+This ensures a consistent and familiar purchase flow for your users.</p>
+
+<img src="{@docRoot}images/in-app-billing/v3/billing_subscription_v3.png" style="float:right; border:4px solid ddd;">
+
+<p>After users have purchase subscriptions, they can view the subscriptions and 
+cancel them from the <strong>My Apps</strong> screen in the Play Store app or 
+from the app's product details page in the Play Store app. For more information 
+about handling user cancellations, see <a href="#cancellation">Subscription Cancellation</a>.</p>
+
+<p>In adddition to client-side API calls, you can use the server-side API for 
+In-app Billing to provide subscription purchasers with extended access to 
+content (for example, from your web site or another service).
+The server-side API lets you validate the status of a subscription when users
+sign into your other services. For more information about the API, see <a
+href="#play-dev-api">Google Play Android Developer API</a>. </p>
+
+<p>You can also build on your existing external subscriber base from inside your
+Android apps.</p>
+<ul>
+<li>If you sell subscriptions on a web site, for example, you can add
+your own business logic to your Android app to determine whether the user has
+already purchased a subscription elsewhere, then allow access to your content if
+so or offer a subscription purchase from Google Play if not.</li>
+<li>You can implement your own solution for sharing subscriptions across as 
+many different apps or products as you want. For example, you could sell a 
+subscription that gives a subscriber access to an entire collection of apps, 
+games, or other content for a monthly or annual fee. To implement this solution, 
+you could add your own business logic to your app to determine whether the user 
+has already purchased a given subscription and if so, allow access to your 
+content.</li>
+</ul>
+</p>
+
+<p>In general the same basic policies and terms apply to subscriptions as to
+standard in-app products, however there are some differences. For complete
+information about the current policies and terms, please read the <a
+href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en
+&answer=140504">policies document</a>.</p>
+
+<p>To learn about the minimum system requirements for 
+subscriptions, see the <a href="{@docRoot}google/play/billing/versions.html#Subs">Version Notes</a>.</p>
+
+<h2 id="administering">Configuring Subscription Items</h2>
+<p>To create and manage subscriptions, use the Developer Console to set up a 
+product list for the app then configure these attributes for each subscription 
+product:</p>
+
+<ul>
+<li>Purchase Type: always set to <strong>Subscription</strong></li>
+<li>Subscription ID:  An identifier for the subscription</li>
+<li>Publishing State: Unpublished/Published</li>
+<li>Language: The default language for displaying the subscription</li>
+<li>Title: The title of the subscription product</li>
+<li>Description: Details that tell the user about the subscription</li>
+<li>Price: USD price of subscription per recurrence</li>
+<li>Recurrence: monthly or yearly</li>
+<li>Additional currency pricing (can be auto-filled)</li>
+</ul>
+
+<p>For details on how to add and configure products in the Developer Console, 
+see <a href="{@docRoot}google/play/billing/billing_admin.html">Administering
+In-app Billing</a>.</p>
+
+<h3 id="pricing">Subscription pricing</h3>
+
+<p>When you create a subscription in the Developer Console, you can set a price
+for it in any available currencies. Each subscription must have a non-zero
+price. You can price multiple subscriptions for the same content differently
+&mdash; for example you could offer a discount on an annual subscription
+relative to the monthly equivalent. </p>
+
+<p class="caution"><strong>Important</strong>: To change the price of a 
+subscription, you can publish a new subscription product ID at a new price, 
+then offer it in your app instead of the original product. Users who have 
+already purchased will continue to be charged at the 
+original price, but new users will be charged at the new price.</p>
+
+<h3 id="user-billing">User billing</h3>
+
+<p>In the Developer Console, you can configure subscription products with 
+automated recurring billing at either of two intervals:</p>
+
+<ul>
+  <li>Monthly &mdash; Google Play bills the customer’s Google Checkout account at
+  the time of purchase and monthly subsequent to the purchase date (exact billing
+  intervals can vary slightly over time)</li>
+  <li>Annually &mdash; Google Play bills the customer's Google Checkout account at
+  the time of purchase and again on the same date in subsequent years.</li>
+</ul>
+
+<p>Billing continues indefinitely at the interval and price specified for the
+subscription. At each subscription renewal, Google Play charges the user account
+automatically, then notifies the user of the charges afterward by email. Billing
+cycles will always match subscription cycles, based on the purchase date.</p>
+
+<p>Over the life of a subscription, the form of payment billed remains the same
+&mdash; Google Play always bills the same form of payment (such as credit card
+or by Direct Carrier Billing) that was originally used to purchase the
+subscription.</p>
+
+<p>When the subscription payment is approved by Google Checkout, Google Play
+provides a purchase token back to the purchasing app through the In-app Billing
+API. Your apps can store the token locally or pass it to your backend servers, 
+which can then use it to validate or cancel the subscription remotely using the <a
+href="#play-dev-api">Google Play Android Developer API</a>.</p>
+
+<p>If a recurring payment fails (for example, because the customer’s credit
+card has become invalid), the subscription does not renew. How your app is 
+notified depends on the In-app Billing API version that you are using:</p>
+<ul>
+<li>With In-app Billing Version 3, the failed or expired subscription is no longer 
+returned when you call {@code getPurchases}.</li>
+<li>With In-app Billing Version 2, Google Play notifies your app at the end of 
+the active cycle that the purchase state of the subscription is now "Expired". 
+</li>
+</ul>
+
+<p class="note"><strong>Recommendation</strong>: Include business logic in your 
+app to notify your backend servers of subscription purchases, tokens, and any 
+billing errors that may occur. Your backend servers can use the server-side API 
+to query and update your records and follow up with customers directly, if needed.</p>
+
+<h3 id="trials">Free trials</h3>
+
+<p>In the Developer Console, you can set up a free trial period that lets users
+try your subscription content before buying it. The trial period runs for the 
+period of time that you set and then automatically converts to a full 
+subscription managed according to the subscription's billing interval and 
+price.</p>
+
+<p>To take advantage of a free trial, a user must "purchase" the full
+subscription through the standard In-app Billing flow, providing a valid form of
+payment to use for billing and completing the normal purchase transaction.
+However, the user is not charged any money, since the initial period corresponds
+to the free trial. Instead, Google Play records a transaction of $0.00 and the
+subscription is marked as purchased for the duration of the trial period or
+until cancellation. When the transaction is complete, Google Play notifies users
+by email that they have purchased a subscription that includes a free trial
+period and that the initial charge was $0.00. </p>
+
+<p>When the trial period ends, Google Play automatically initiates billing
+against the credit card that the user provided during the initial purchase, at 
+the amount set
+for the full subscription, and continuing at the subscription interval. If
+necessary, the user can cancel the subscription at any time during the trial
+period. In this case, Google Play <em>marks the subscription as expired immediately</em>,
+rather than waiting until the end of the trial period. The user has not
+paid for the trial period and so is not entitled to continued access after
+cancellation.</p>
+
+<p>You can set up a trial period for a subscription in the Developer Console,
+without needing to modify or update your APK. Just locate and edit the
+subscription in your product list, set a valid number of days for the trial
+(must be 7 days or longer), and publish. You can change the period any time,
+although note that Google Play does not apply the change to users who have
+already "purchased" a trial period for the subscription. Only new subscription
+purchases will use the updated trial period. You can create one free trial
+period per subscription product.</p>
+
+<h3 id="publishing">Subscription publishing</h3>
+<p>When you have finished configuring your subscription product details in the
+Developer Console, you can publish the subscription in the app product list.</p>
+
+<p>In the product list, you can add subscriptions, in-app products, or both. You
+can add multiple subscriptions that give access to different content or
+services, or you can add multiple subscriptions that give access to the same
+content but for different intervals or different prices, such as for a
+promotion. For example, a news outlet might decide to offer both monthly and
+annual subscriptions to the same content, with annual having a discount. You can
+also offer in-app purchase equivalents for subscription products, to ensure that
+your content is available to users of older devices that do not support
+subscriptions.</p>
+
+<p>After you add a subscription or in-app product to the product list, you must
+publish the product before Google Play can make it available for purchase. Note
+that you must also publish the app itself before Google Play will make the
+products available for purchase inside the app. </p>
+
+<p class="caution"><strong>Important</strong>: You can remove the subscription 
+product from the product list offered in your app to prevent users from seeing 
+or purchasing it.</p>
+
+<h2 id="cancellation">Subscription Cancellation</h2>
+
+<p>Users can view the status of all of their subscriptions and cancel them if
+necessary from the <strong>My Apps</strong> screen in the Play Store app. 
+Currently, the In-app Billing API does not provide support for programatically 
+canceling subscriptions from inside the purchasing app.</p>
+
+<p>When the user cancels a subscription, Google Play does not offer a refund for
+the current billing cycle. Instead, it allows the user to have access to the
+cancelled subscription until the end of the current billing cycle, at which time
+it terminates the subscription. For example, if a user purchases a monthly
+subscription and cancels it on the 15th day of the cycle, Google Play will
+consider the subscription valid until the end of the 30th day (or other day,
+depending on the month).</p>
+
+<p>In some cases, the user may contact you directly to request cancellation of a
+subscription. In this and similar cases, you can use the server-side API to
+query and directly cancel the user’s subscription from your servers.
+
+<p class="caution"><strong>Important:</strong> In all cases, you must continue
+to offer the content that your subscribers have purchased through their
+subscriptions, for as long any users are able to access it. That is, you must
+not remove any subscriber’s content while any user still has an active
+subscription to it, even if that subscription will terminate at the end of the
+current billing cycle. Removing content that a subscriber is entitled to access
+will result in penalties. Please see the <a
+href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies document</a> for more information. </p>
+
+<h3 id="uninstall">App uninstallation</h3>
+
+<p>When the user uninstalls an app that includes purchased subscriptions, the 
+Play Store app will notify the user that there are active subscriptions. If the 
+user chooses to continue with the uninstallation, the app is removed and the 
+subscriptions remain active and recurring billing continues. The user can return 
+to cancel the associated subscriptions at any time in the <strong>My Apps</strong> 
+screen of the Play Store app. If the user chooses to cancel the uninstallation, 
+the app and subscriptions remain as they were.</p>
+
+<h3 id="refunds">Refunds</h3>
+
+<p>With subscriptions, Google Play does not provide a refund window, so users 
+will need to contact you directly to request a refund.
+
+<p>If you receive requests for refunds, you can use the server-side API to
+cancel the subscription or verify that it is already cancelled. However, keep in
+mind that Google Play considers cancelled subscriptions valid until the end of
+their current billing cycles, so even if you grant a refund and cancel the
+subscription, the user will still have access to the content.
+
+<p class="caution"><strong>Important:</strong> Partial refunds for canceled
+subscriptions are not available at this time.</p>
+
+<h2 id="payment">Payment Processing and Policies</h2>
+
+<p>In general, the terms of Google Play allow you to sell in-app subscriptions
+only through the standard payment processor, Google Checkout. For purchases of 
+any subscription products, the transaction fee is the same as the transaction 
+fee for application purchases (30%).</p>
+
+<p>Apps published on Google Play that are selling subscriptions must use In-app
+Billing to handle the transaction and may not provide links to a purchase flow
+outside of the app and Google Play (such as to a web site).</p>
+
+<p>For complete details about terms and policies, see the <a
+href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies
+document</a>.</p>
+
+<h3 id="orderId">Subscription order numbers</h3>
+
+<p>To help you track transactions relating to a given subscription, Google
+Checkout provides a base Merchant Order Number for all recurrences of the 
+subscription and denotes
+each recurring transaction by appending an integer as follows: </p>
+
+<p><span style="color:#777"><code style="color:#777">12999556515565155651.5565135565155651</code> (base order number)</span><br />
+<code>12999556515565155651.5565135565155651..0</code> (initial purchase orderID)<br />
+<code>12999556515565155651.5565135565155651..1</code> (first recurrence orderID)<br />
+<code>12999556515565155651.5565135565155651..2</code> (second recurrence orderID)<br />
+...<br /></p>
+
+<p>Google Play provides the order number as the value of the 
+{@code orderId} field of the {@code INAPP_PURCHASE_DATA} JSON field (in V3) 
+or the {@code PURCHASE_STATE_CHANGED} intent (in V2).</p>
+
+<h2 id="play-dev-api">Google Play Android Developer API</h2>
+
+<p>Google Play offers an HTTP-based API that you can use to remotely query the
+validity of a specific subscription at any time or cancel a subscription. The
+API is designed to be used from your backend servers as a way of securely
+managing subscriptions, as well as extending and integrating subscriptions with
+other services.</p>
+
+<h3 id="using">Using the API</h3>
+
+<p>To use the API, you must first register a project at the <a
+href="https://code.google.com/apis/console">Google APIs Console</a> and receive
+a Client ID and shared secret that  your app will present when calling the
+Google Play Android Developer API. All calls to the API are authenticated with
+OAuth 2.0.</p>
+
+<p>Once your app is registered, you can access the API directly, using standard
+HTTP methods to retrieve and manipulate resources, or you can use the Google
+APIs Client Libraries, which are extended to support the API.</p>
+
+<p>The Google Play Android Developer API is built on a RESTful design that uses
+HTTP and JSON, so any standard web stack can send requests and parse the
+responses. However, if you don’t want to send HTTP requests and parse responses
+manually, you can access the API using the client libraries, which provide
+better language integration, improved security, and support for making calls
+that require user authorization.</p>
+
+<p>For more information about the API and how to access it through the Google
+APIs Client Libraries, see the documentation at:</p> 
+
+<p style="margin-left:1.5em;"><a
+href="https://developers.google.com/android-publisher/v1/">https://developers.
+google.com/android-publisher/v1/</a></p>
+
+<h3 id="quota">Quota</h3>
+
+<p>Applications using the Google Play Android Developer API are limited to an
+initial courtesy usage quota of <strong>15000 requests per day</strong> (per
+application). This should provide enough access for normal
+subscription-validation needs, assuming that you follow the recommendation in
+this section.</p>
+
+<p>If you need to request a higher limit for your application, please use the
+“Request more” link in the <a
+href="https://code.google.com/apis/console/#:quotas">Google APIs Console</a>.
+Also, please read the section below on design best practices for minimizing your
+use of the API.</p>
+
+<h3 id="auth">Authorization</h3>
+
+<p>Calls to the Google Play Android Developer API require authorization. Google
+uses the OAuth 2.0 protocol to allow authorized applications to access user
+data. To learn more, see <a
+href="https://developers.google.com/android-publisher/authorization">Authorization</a>
+in the Google Play Android Developer API documentation.</p>
+
+<h3 id="practices">Using the API efficiently</h3>
+
+<p>Access to the Google Play Android Developer API is regulated to help ensure a
+high-performance environment for all applications that use it. While you can
+request a higher daily quota for your application, we highly recommend that you
+minimize your access using the technique(s) below. </p>
+
+<ul>
+  <li><em>Store subscription expiry on your servers</em> &mdash; your servers
+  should use the Google Play Android Developer API to query the expiration date
+  for new subscription tokens, then store the expiration date locally. This allows
+  you to check the status of subscriptions only at or after the expiration (see
+  below). </li>
+  <li><em>Cache expiration and purchaseState</em> &mdash; If your app contacts
+  your backend servers at runtime to verify subscription validity, your server
+  should cache the expiration and purchaseState to ensure the fastest possible
+  response (and best experience) for the user.</li>
+  <li><em>Query for subscription status only at expiration</em> &mdash; Once your
+  server has retrieved the expiration date of subscription tokens, it should not
+  query the Google Play servers for the subscription status again until the
+  subscription is reaching or has passed the expiration date. Typically, your
+  servers would run a batch query each day to check the status of
+  <em>expiring</em> subscriptions, then update the database. Note that: 
+  <ul>
+    <li>Your servers should not query all subscriptions every day</li>
+    <li>Your servers should never query subscription status dynamically, based on
+    individual requests from your Android application. </li>
+  </ul>
+  </li>
+</ul>
+
+<p>By following those general guidelines, your implementation will offer the
+best possible performance for users and minimize use of the Google Play Android
+Developer API.</p>
+
+
diff --git a/docs/html/google/play/billing/index.jd b/docs/html/google/play/billing/index.jd
index b0d1d13..44aa001 100755
--- a/docs/html/google/play/billing/index.jd
+++ b/docs/html/google/play/billing/index.jd
@@ -10,8 +10,8 @@ and features, and more. You can use In-app Billing to sell products as</p>
 <div class="sidebox">
   <h2><strong>New in In-App Billing</strong></h2>
   <ul>
-  <li><strong>In-app Billing Version 3</strong>&mdash;The <a href="{@docRoot}google/play/billing/api.html">latest version</a> of In-app Billing features a synchronous API that is easier to implement and lets you manage products and purchases more effectively.</li>
-  <li><strong>New order number format</strong>&mdash;Starting 5 December, orders are reported in Merchant Order Number format. See <a href="/google/play/billing/billing_admin.html#orderId">Working with Order Numbers</a> for an example.</li>
+  <li><strong>In-app Billing Version 3</strong>&mdash;The <a href="{@docRoot}google/play/billing/api.html">latest version</a> of In-app Billing features a synchronous API that is easier to implement and lets you manage in-app products and subscriptions more effectively.</li>
+  <li><strong>Subscriptions now supported in Version 3</strong>&mdash;You can query and launch purchase flows for subscription items using the V3 API.</li>
   <li><strong>Free trials</strong>&mdash;You can now offer users a configurable <a href="/google/play/billing/v2/billing_subscriptions.html#trials">free trial period</a> for your in-app subscriptions. You can set up trials with a simple change in the Developer Console&mdash;no change to your app code is needed.</li>
  </ul>
 </div>
@@ -30,7 +30,7 @@ is used for application purchases, so your users experience a consistent and
 familiar purchase flow.</p>
 
 <p>Any application that you publish through Google Play can implement In-app Billing. No special
-account or registration is required other than an Android Market publisher account and a Google
+account or registration is required other than a Google Play Developer Console account and a Google
 Checkout merchant account.</p>
 
 <p>To help you integrate in-app billing into your application, the Android SDK
diff --git a/docs/html/google/play/billing/v2/api.jd b/docs/html/google/play/billing/v2/api.jd
index 6b3b758..9d3a045 100644
--- a/docs/html/google/play/billing/v2/api.jd
+++ b/docs/html/google/play/billing/v2/api.jd
@@ -39,15 +39,6 @@ Version 2, rather than Version 3. </p>
 <p>If you do not need to sell subscriptions, you
 should implement In-app Billing Version 3 instead.</p>
 
-<div class="sidebox-wrapper">
-<div class="sidebox">
-  <h2>New in In-app Billing V2</h2>
-  <p><strong>Free trials</strong>—You can now offer users a configurable free trial period for
-  your in-app subscriptions. You can set up trials with a simple change in the Developer
-  Console—no change to your app code is needed.</p>
-</div>
-</div>
-
 <h2 id="billing-types">Product Types</h2>
 
 <p>In-app Billing Version supports three different product types
diff --git a/docs/html/google/play/billing/v2/billing_subscriptions.jd b/docs/html/google/play/billing/v2/billing_subscriptions.jd
index 82a662f..5e3bd28 100755
--- a/docs/html/google/play/billing/v2/billing_subscriptions.jd
+++ b/docs/html/google/play/billing/v2/billing_subscriptions.jd
@@ -1,4 +1,4 @@
-page.title=Subscriptions  <span style="font-size:16px;">(IAB Version 2)</span>
+page.title=Implementing Subscriptions  <span style="font-size:16px;">(IAB Version 2)</span>
 @jd:body
 
 <div style="background-color:#fffdeb;width:100%;margin-bottom:1em;padding:.5em;">In-app Billing Version 2 is superseded. Please <a href="{@docRoot}google/play/billing/billing_overview.html#migration">migrate to Version 3</a> at your earliest convenience.</div>
@@ -6,404 +6,26 @@ page.title=Subscriptions  <span style="font-size:16px;">(IAB Version 2)</span>
 <div id="qv">
   <h2>In this document</h2>
   <ol>
-    <li><a href="#overview">Overview of Subscriptions</a>
-    <!--<ol>
-        <li><a href="#publishing">Subscription publishing and unpublishing</a></li>
-        <li><a href="#pricing">Subscription pricing</a></li>
-        <li><a href="#user-billing">User billing</a></li>
-        <li><a href="#trials">Free trial period</a></li>
-        <li><a href="#cancellation">Subscription cancellation</a></li>
-        <li><a href="#uninstallation">App uninstallation</a></li>
-        <li><a href="#refunds">Refunds</a></li>
-        <li><a href="#payment">Payment processing and policies</a></li>
-        <li><a href="#requirements">System requirements for subscriptions</a></li>
-        <li><a href="#compatibility">Compatibility considerations</a></li>
-      </ol> -->
-    </li>
-    <li><a href="#implementing">Implementing Subscriptions</a>
-      <!-- <ol>
-        <li><a href="#sample">Sample application</a></li>
-        <li><a href="#model">Application model</a></li>
-        <li><a href="#token">Purchase token</a></li>
-        <li><a href="#version">Checking the In-app Billing API version</a></li>
-        <li><a href="purchase">Requesting purchase of a subscription</a></li>
-        <li><a href="#restore">Restoring transactions</a></li>
-        <li><a href="#validity">Checking subscription validity</a></li>
-        <li><a href="#viewstatus">Launching your product page to let the user cancel or view status</a></li>
-        <li><a href="#purchase-state-changes">Recurring billing and changes in purchase state</a></li>
-        <li><a href="modifying">Modifying your app for subscriptions</a></li>
-      </ol> -->
-    </li>
-    <li><a href="#administering">Administering Subscriptions</a></li>
-    
-    <li><a href="#play-dev-api">Google Play Android Developer API</a>
-      <!-- <ol>
-        <li><a href="#using">Using the API</a></li>
-        <li><a href="#quota">Quota</a></li>
-        <li><a href="#auth">Authorization</a></li>
-        <li><a href="#practices">Using the API efficiently</a></li>
-      </ol> -->
-    </li>
-</ol>
+        <li><a href="#sample">Sample Application</a></li>
+        <li><a href="#model">Application Model</a></li>
+        <li><a href="#token">Purchase Token</a></li>
+        <li><a href="#version">Checking the In-app Billing API Version</a></li>
+        <li><a href="purchase">Purchasing a Subscription</a></li>
+        <li><a href="#restore">Restoring Transactions</a></li>
+        <li><a href="#validity">Checking Subscription Validity</a></li>
+        <li><a href="#viewstatus">Letting Users Cancel or View Status</a></li>
+        <li><a href="#purchase-state-changes">Recurring Billing and Changes in Purchase State</a></li>
+        <li><a href="modifying">Modifying Your App for Subscriptions</a></li>
+   </ol>
 </div>
 </div>
 
-<p class="note"><strong>Important:</strong> This documentation describes how to implement subscriptions with the Version 2 API. Subscription support for the in-app billing <a href="{@docRoot}google/play/billing/api.html">Version 3 API</a> is coming soon.</p></li>
+<p>This document is focused on highlighting implementation details that are 
+specific to subscriptions with the Version 2 API. To understand how  
+subscriptions work, see <a href="{@docRoot}google/play/billing/billing_subscriptions.html">In-app Billing Subscriptions</a>.</p>
 
-<p>Subscriptions let you sell content, services, or features in your app with
-automated, recurring billing. Adding support for subscriptions is
-straightforward and you can easily adapt an existing In-app Billing
-implementation to sell subscriptions. </p>
 
-<p>If you have already implemented In-app Billing for one-time purchase
-products, you will find that you can add support for subscriptions with minimal
-impact on your code. If you are new to In-app Billing, you can implement
-subscriptions using the standard communication model, data structures, and user
-interactions as for other in-app products.subscriptions. Because the
-implementation of subscriptions follows the same path as for other in-app
-products, details are provided outside of this document, starting with the <a
-href="{@docRoot}google/play/billing/v2/api.html">In-app Billing
-Overview</a>. </p>
-
-<p>This document is focused on highlighting implementation details that are
-specific to subscriptions, along with some strategies for the associated billing
-and business models.</p>
-
-<p class="note"><strong>Note:</strong> Subscriptions are supported in In-app Billing Version 2 only. Support for subscriptions will be added to Version 3 in the weeks ahead.</p>
-
-<h2 id="overview">Overview of Subscriptions</h2>
-
-<p>A <em>subscription</em> is a new product type offered in In-app Billing that lets you
-sell content, services, or features to users from inside your app with recurring
-monthly or annual billing. You can sell subscriptions to almost any type of
-digital content, from any type of app or game.</p>
-
-<p>As with other in-app products, you configure and publish subscriptions using
-the Developer Console and then sell them from inside apps installed on an
-Android-powered devices. In the Developer console, you create subscription
-products and add them to a product list, then set a price and optional trial
-period for each, choose a billing interval (monthly or annual), and then publish.</p>
-
-<p>In your apps, it’s
-straightforward to add support for subscription purchases. The implementation
-extends the standard In-app Billing API to support a new product type but uses
-the same communication model, data structures, and user interactions as for
-other in-app products.</p>
-
-<p>When users purchase subscriptions in your apps, Google Play handles all
-checkout details so your apps never have to directly process any financial
-transactions. Google Play processes all payments for subscriptions through
-Google Checkout, just as it does for standard in-app products and app purchases.
-This ensures a consistent and familiar purchase flow for your users.</p>
-
-<img src="{@docRoot}images/billing_subscription_flow.png" style="border:4px solid ddd;">
-
-
-<p>After users have purchase subscriptions, they can view the subscriptions and
-cancel them, if necessary, from the My Apps screen in the Play Store app or
-from the app's product details page in the Play Store app.</p>
-
-<!--<img src="{@docRoot}images/billing_subscription_cancel.png" style="border:4px solid ddd;">-->
-
-<p>Once users have purchased a subscription through In-app Billing, you can
-easily give them extended access to additional content on your web site (or
-other service) through the use of a server-side API provided for In-app Billing.
-The server-side API lets you validate the status of a subscription when users
-sign into your other services. For more information about the API, see <a
-href="#play-dev-api">Google Play Android Developer API</a>, below. </p>
-
-<p>You can also build on your existing external subscriber base from inside your
-Android apps. If you sell subscriptions on a web site, for example, you can add
-your own business logic to your Android app to determine whether the user has
-already purchased a subscription elsewhere, then allow access to your content if
-so or offer a subscription purchase from Google Play if not.</p>
-
-<p>With the flexibility of In-app Billing, you can even implement your own
-solution for sharing subscriptions across as many different apps or products as
-you want. For example, you could sell a subscription that gives a subscriber
-access to an entire collection of apps, games, or other content for a monthly or
-annual fee. To implement this solution, you could add your own business logic to
-your app to determine whether the user has already purchased a given
-subscription and if so, allow access to your content. </p>
-
-<div class="sidebox-wrapper">
-<div class="sidebox">
-  <h2>Subscriptions at a glance</h2>
-  <ul>
-    <li>Subscriptions let you sell products with automated, recurring billing</li>
-    <li>You can set up subscriptions with either monthly or annual billing</li>
-    <li>You can sell multiple subscription items in an app with various billing
-    intervals or prices, such as for promotions</li>
-    <li>You can offer a configurable trial period for any subscription. <span class="new" style="font-size:.78em;">New!</span></li>
-    <li>Users purchase your subscriptions from inside your apps, rather than
-    directly from Google Play</li>
-    <li>Users manage their purchased subscriptions from the My Apps screen in
-    the Play Store app</li>
-    <li>Google Play uses the original form of payment for recurring billing</li>
-    <li>If a user cancels a subscription, Google Play considers the subscription valid
-    until the end of the current billing cycle. The user continues to enjoy the content
-    for the rest of the cycle and is not granted a refund.</li>
-  </ul>
-</div>
-</div>
-
-<p>In general the same basic policies and terms apply to subscriptions as to
-standard in-app products, however there are some differences. For complete
-information about the current policies and terms, please read the <a
-href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en
-&answer=140504">policies document</a>.</p>
-
-
-<h3 id="publishing">Subscription publishing and unpublishing</h3>
-
-<p>To sell a subscription in an app, you use the tools in the Developer Console
-to set up a product list for the app and then create and configure a new
-subscription. In the subscription, you set the price and billing interval and
-define a subscription ID, title, and description. When you are ready, you can
-then publish the subscription in the app product list.</p>
-
-<p>In the product list, you can add subscriptions, in-app products, or both. You
-can add multiple subscriptions that give access to different content or
-services, or you can add multiple subscriptions that give access to the same
-content but for different intervals or different prices, such as for a
-promotion. For example, a news outlet might decide to offer both monthly and
-annual subscriptions to the same content, with annual having a discount. You can
-also offer in-app purchase equivalents for subscription products, to ensure that
-your content is available to users of older devices that do not support
-subscriptions.</p>
-
-<p>After you add a subscription or in-app product to the product list, you must
-publish the product before Google Play can make it available for purchase. Note
-that you must also publish the app itself before Google Play will make the
-products available for purchase inside the app. </p>
-
-<p class="caution"><strong>Important:</strong> At this time, the capability to
-unpublish a subscription is not available. Support for unpublishing a
-subscription is coming to the Developer Console in the weeks ahead, so this is a
-temporary limitation. In the short term, instead of unpublishing,
-you can remove the subscription product from the product list offered in your
-app to prevent users from seeing or purchasing it.</p>
-
-<h3 id="pricing">Subscription pricing</h3>
-
-<p>When you create a subscription in the Developer Console, you can set a price
-for it in any available currencies. Each subscription must have a non-zero
-price. You can price multiple subscriptions for the same content differently
-&mdash; for example you could offer a discount on an annual subscription
-relative to the monthly equivalent. </p>
-
-<p class="caution"><strong>Important:</strong> At this time, once you publish a
-subscription product, you cannot change its price in any currency. Support for
-changing the price of published subscriptions is coming to the Developer Console
-in the weeks ahead. In the short term, you can work around this limitation by
-publishing a new subscription product ID at a new price, then offer it in your
-app instead of the original product. Users who have already purchased will
-continue to be charged at the original price, but new users will be charged at
-the new price.</p>
-
-<h3 id="user-billing">User billing</h3>
-
-<p>You can sell subscription products with automated recurring billing at
-either of two intervals:</p>
-
-<ul>
-  <li>Monthly &mdash; Google Play bills the customer’s Google Checkout account at
-  the time of purchase and monthly subsequent to the purchase date (exact billing
-  intervals can vary slightly over time)</li>
-  <li>Annually &mdash; Google Play bills the customer's Google Checkout account at
-  the time of purchase and again on the same date in subsequent years.</li>
-</ul>
-
-<p>Billing continues indefinitely at the interval and price specified for the
-subscription. At each subscription renewal, Google Play charges the user account
-automatically, then notifies the user of the charges afterward by email. Billing
-cycles will always match subscription cycles, based on the purchase date.</p>
-
-<p>Over the life of a subscription, the form of payment billed remains the same
-&mdash; Google Play always bills the same form of payment (such as credit card,
-Direct Carrier Billing) that was originally used to purchase the
-subscription.</p>
-
-<p>When the subscription payment is approved by Google Checkout, Google Play
-provides a purchase token back to the purchasing app through the In-app Billing
-API. For details, see <a href="#token">Purchase token</a>, below. Your apps can
-store the token locally or pass it to your backend servers, which can then use
-it to validate or cancel the subscription remotely using the <a
-href="#play-dev-api">Google Play Android Developer API</a>.</p>
-
-<p>If a recurring payment fails, such as could happen if the customer’s credit
-card has become invalid, the subscription does not renew. Google Play notifies your
-app at the end of the active cycle that the purchase state of the subscription is now "Expired".
-Your app does not need to grant the user further access to the subscription content.</p>
-
-<p>As a best practice, we recommend that your app includes business logic to
-notify your backend servers of subscription purchases, tokens, and any billing
-errors that may occur. Your backend servers can use the server-side API to query
-and update your records and follow up with customers directly, if needed.</p>
-
-<h3 id="trials">Free Trial Period</h3>
-
-<p>For any subscription, you can set up a free trial period that lets users
-try your subscription content before buying it. The trial period
-runs for the period of time that you set and then automatically converts to a full subscription
-managed according to the subscription's billing interval and price.</p>
-
-<p>To take advantage of a free trial, a user must "purchase" the full
-subscription through the standard In-app Billing flow, providing a valid form of
-payment to use for billing and completing the normal purchase transaction.
-However, the user is not charged any money, since the initial period corresponds
-to the free trial. Instead, Google Play records a transaction of $0.00 and the
-subscription is marked as purchased for the duration of the trial period or
-until cancellation. When the transaction is complete, Google Play notifies users
-by email that they have purchased a subscription that includes a free trial
-period and that the initial charge was $0.00. </p>
-
-<p>When the trial period ends, Google Play automatically initiates billing
-against the credit card that the user provided during the initial purchase, at the amount set
-for the full subscription, and continuing at the subscription interval. If
-necessary, the user can cancel the subscription at any time during the trial
-period. In this case, Google Play <em>marks the subscription as expired immediately</em>,
-rather than waiting until the end of the trial period. The user has not
-paid for the trial period and so is not entitled to continued access after
-cancellation.</p>
-
-<p>You can set up a trial period for a subscription in the Developer Console,
-without needing to modify or update your APK. Just locate and edit the
-subscription in your product list, set a valid number of days for the trial
-(must be 7 days or longer), and publish. You can change the period any time,
-although note that Google Play does not apply the change to users who have
-already "purchased" a trial period for the subscription. Only new subscription
-purchases will use the updated trial period. You can create one free trial
-period per subscription product.</p>
-
-<h3 id="cancellation">Subscription cancellation</h3>
-
-<p>Users can view the status of all of their subscriptions and cancel them if
-necessary from the My Apps screen in the Play Store app. Currently, the In-app
-Billing API does not provide support for canceling subscriptions direct from
-inside the purchasing app, although your app can broadcast an Intent to launch
-the Play Store app directly to the My Apps screen.</p>
-
-<p>When the user cancels a subscription, Google Play does not offer a refund for
-the current billing cycle. Instead, it allows the user to have access to the
-cancelled subscription until the end of the current billing cycle, at which time
-it terminates the subscription. For example, if a user purchases a monthly
-subscription and cancels it on the 15th day of the cycle, Google Play will
-consider the subscription valid until the end of the 30th day (or other day,
-depending on the month).</p>
-
-<p>In some cases, the user may contact you directly to request cancellation of a
-subscription. In this and similar cases, you can use the server-side API to
-query and directly cancel the user’s subscription from your servers.
-
-<p class="caution"><strong>Important:</strong> In all cases, you must continue
-to offer the content that your subscribers have purchased through their
-subscriptions, for as long any users are able to access it. That is, you must
-not remove any subscriber’s content while any user still has an active
-subscription to it, even if that subscription will terminate at the end of the
-current billing cycle. Removing content that a subscriber is entitled to access
-will result in penalties. Please see the <a
-href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies document</a> for more information. </p>
-
-<h3 id="uninstall">App uninstallation</h3>
-
-<p>When the user uninstalls an app that includes purchased subscriptions, the Play Store app will notify the user that there are active subscriptions. If the user chooses to continue with the 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>
-
-<h3 id="refunds">Refunds</h3>
-
-<p>As with other in-app products, Google Play does not provide a refund window
-for subscription purchases. For example, users who purchase an app can ask for a
-refund from Google Play within a 15-minute window. With subscriptions, Google
-Play does not provide a refund window, so users will need to contact you
-directly to request a refund.
-
-<p>If you receive requests for refunds, you can use the server-side API to
-cancel the subscription or verify that it is already cancelled. However, keep in
-mind that Google Play considers cancelled subscriptions valid until the end of
-their current billing cycles, so even if you grant a refund and cancel the
-subscription, the user will still have access to the content.
-
-<p class="note"><strong>Note:</strong> Partial refunds for canceled
-subscriptions are not available at this time.</p>
-
-<h3 id="payment">Payment processing and policies</h3>
-
-<p>In general, the terms of Google Play allow you to sell in-app subscriptions
-only through the standard payment processor, Google Checkout. For purchases of any
-subscription products, just as for other in-app products and apps, the
-transaction fee for subscriptions, just as for other in-app purchases, is the
-same as the transaction fee for application purchases (30%).</p>
-
-<p>Apps published on Google Play that are selling subscriptions must use In-app
-Billing to handle the transaction and may not provide links to a purchase flow
-outside of the app and Google Play (such as to a web site).</p>
-
-<p>For complete details about terms and policies, see the <a
-href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies
-document</a>.</p>
-
-<h3 id="orderId">Subscription Order Numbers</h3>
-
-<p>To help you track transactions relating to a given subscription, Google
-Checkout provides a base Merchant Order Number for all recurrences of the subscription and denotes
-each recurring transaction by appending an integer as follows: </p>
-
-<p><span style="color:#777"><code style="color:#777">12999556515565155651.5565135565155651</code> (base order number)</span><br />
-<code>12999556515565155651.5565135565155651..0</code> (initial purchase orderID)<br />
-<code>12999556515565155651.5565135565155651..1</code> (first recurrence orderID)<br />
-<code>12999556515565155651.5565135565155651..2</code> (second recurrence orderID)<br />
-...<br /></p>
-
-<p>Google Play provides that order number to as the value of the
-<code>orderId</code> field of the <code>PURCHASE_STATE_CHANGED</code>
-intent.</p>
-
-<h3 id="requirements">System requirements for subscriptions</h3>
-
-<p>In-app purchases of subscriptions are supported only on devices that meet
-these minimum requirements:</p>
-
-<ul>
-  <li>Must run Android 2.2 or higher</li>
-  <li>Google Play Store app, Version 3.5 or higher, must be installed</li>
-</ul>
-
-<p>Google Play 3.5 and later versions include support for the In-app Billing
-v2 API or higher, which is needed to support handling of subscription
-products.</p>
-
-<h3 id="compatibility">Compatibility considerations</h3>
-
-<p>As noted in the previous section, support for subscriptions is available only
-on devices that meet the system requirements. Not all devices will receive or
-install Google Play 3.5, so not all users who install your apps will have access
-to the In-app Billing API and subscriptions.</p>
-
-<p>If you are targeting older devices that run Android 2.1 or earlier, we
-recommend that you offer those users an alternative way buy the content that is
-available through subscriptions. For example, you could create standard in-app
-products (one-time purchases) that give access to similar content as your
-subscriptions, possibly for a longer interval such as a year. </p>
-
-
-<h2 id="implementing">Implementing Subscriptions</h2>
-
-<p>Subscriptions are a standard In-app Billing product type. If you have already
-implemented In-app Billing for one-time purchase products, you will find that
-adding support for subscriptions is straightforward, with minimal impact on your
-code. If you are new to In-app Billing, you can implement subscriptions using
-the standard communication model, data structures, and user interactions as for
-other in-app products.subscriptions. </p>
-
-<p>The full implementation details for In-app Billing are provided outside of
-this document, starting with the <a
-href="{@docRoot}google/play/billing/v2/api.html">In-app Billing
-Overview</a>. This document is focused on highlighting implementation details
-that are specific to subscriptions, along with some strategies for the
-associated billing and business models.</p>
-
-
-<h3 id="sample">Sample application</h3>
+<h2 id="sample">Sample Application</h2>
 
 <p>To help you get started with your In-app Billing implementation and
 subscriptions, an updated Version of the In-app Billing sample app is available.
@@ -412,7 +34,7 @@ Android SDK Manager. For details, see <a
 href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">
 Downloading the Sample Application</a>.</p>
 
-<h3 id="model">Application model</h3>
+<h2 id="model">Application Model</h2>
 
 <p>With subscriptions, your app uses the standard In-app Billing application
 model, sending billing requests to the Play Store application over interprocess
@@ -436,7 +58,7 @@ app will use the standard set of in-app billing requests and receive the same
 responses. Inside the requests and responses are two new fields described below.
 </p>
 
-<h3 id="token">Purchase token</h3>
+<h2 id="token">Purchase Token</h2>
 
 <p>Central to the end-to-end architecture for subscriptions is the purchase
 token, a string value that uniquely identifies (and associates) a user ID and a
@@ -476,7 +98,7 @@ href="{@docRoot}google/play/billing/billing_best_practices.html">Security and
 Design</a> document for best practices for maintaining the security of your
 data.</p>
 
-<h3 id="version">Checking the In-app Billing API version</h3>
+<h2 id="version">Checking the In-app Billing API Version</h2>
 
 <p>Subscriptions support is available only in versions of Google Play that
 support the In-app Billing v2 API (Google Play 3.5 and higher). For your app,
@@ -555,7 +177,7 @@ indicates that subscriptions are supported.</p>
    }
 </pre>
 
-<h3 id="purchase">Requesting a subscription purchase</h3>
+<h2 id="purchase">Requesting a Subscription Purchase</h2>
 
 <p>Once you’ve checked the API Version as described above and determined that
 subscriptions are supported, you can present subscription products to the user
@@ -630,7 +252,7 @@ BillingService.java).</p>
    }
 </pre>
 
-<h3 id="restoring">Restoring transactions</h3>
+<h2 id="restoring">Restoring Transactions</h2>
 
 <p>Subscriptions always use  the <em>managed by user account</em> purchase type,
 so that you can restore a record of subscription transactions on the device when
@@ -660,7 +282,7 @@ href="{@docRoot}google/play/billing/billing_best_practices.html">Security and
 Design</a> document for best practices for maintaining the security of your
 data.</p>
 
-<h3 id="validity">Checking subscription validity</h3>
+<h2 id="validity">Checking Subscription Validity</h2>
 
 <p>Subscriptions are time-bound purchases that require successful billing
 recurrences over time to remain valid. Your app should check the validity of
@@ -736,7 +358,7 @@ values for subscription purchases, as received with a
 </table>
 
 
-<h3 id="viewstatus">Launching your product page to let the user cancel or view subscriptions</h3>
+<h2 id="viewstatus">Letting the User Cancel or View Subscriptions</h2>
 
 <p>In-app Billing does not currently provide an API to let users directly view or cancel
 subscriptions from within the purchasing app. Instead, users can launch the Play
@@ -761,7 +383,7 @@ startActivity(intent);</pre>
 <p>For more information, see 
   <a href="{@docRoot}distribute/googleplay/promote/linking.html">Linking to Your Products</a>.</p>
 
-<h3 id="purchase-state-changes">Recurring billing, cancellation, and changes in purchase state</h3>
+<h2 id="purchase-state-changes">Recurring Billing, Cancellation, and Changes In Purchase State</h2>
 
 <p>Google Play notifies your app when the user completes the purchase of a
 subscription, but the purchase state does not change over time, provided that
@@ -786,7 +408,7 @@ purchase state has changed to "Expired".</p>
 a change to the same "Expired" purchase state. Once the purchase state has become "Expired",
 your app does not need to grant further access to the subscription content.</p>
 
-<h3 id="modifying">Modifying your app for subscriptions</h3>
+<h2 id="modifying">Modifying Your App for Subscriptions</h2>
 
 <p>For subscriptions, you make the same types of modifications to your app as
 are described in <a
@@ -798,118 +420,7 @@ purchase, you should add logic to check for purchased subscriptions and validate
 them. Your UI should not present subscriptions if the user has already purchased
 them.</p>
 
-<h2 id="administering">Administering Subscriptions</h2>
-
-<p>To create and manage subscriptions, you use the tools in the Developer
-Console, just as for other in-app products.</p>
-
-<p>At the Developer Console, you can configure these attributes for each
-subscription product:</p>
-
-<ul>
-<li>Purchase Type: always set to “subscription”</li>
-<li>Subscription ID:  An identifier for the subscription</li>
-<li>Publishing State: Unpublished/Published</li>
-<li>Language: The default language for displaying the subscription</li>
-<li>Title: The title of the subscription product</li>
-<li>Description: Details that tell the user about the subscription</li>
-<li>Price: USD price of subscription per recurrence</li>
-<li>Recurrence: monthly or yearly</li>
-<li>Additional currency pricing (can be auto-filled)</li>
-</ul>
-
-<p>For details, please see <a href="{@docRoot}google/play/billing/billing_admin.html">Administering
-In-app Billing</a>.</p>
-
-
-<h2 id="play-dev-api">Google Play Android Developer API</h2>
-
-<p>Google Play offers an HTTP-based API that you can use to remotely query the
-validity of a specific subscription at any time or cancel a subscription. The
-API is designed to be used from your backend servers as a way of securely
-managing subscriptions, as well as extending and integrating subscriptions with
-other services.</p>
-
-<h3 id="using">Using the API</h3>
 
-<p>To use the API, you must first register a project at the <a
-href="https://code.google.com/apis/console">Google APIs Console</a> and receive
-a Client ID and shared secret that  your app will present when calling the
-Google Play Android Developer API. All calls to the API are authenticated with
-OAuth 2.0.</p>
 
-<p>Once your app is registered, you can access the API directly, using standard
-HTTP methods to retrieve and manipulate resources, or you can use the Google
-APIs Client Libraries, which are extended to support the API.</p>
-
-<p>The Google Play Android Developer API is built on a RESTful design that uses
-HTTP and JSON, so any standard web stack can send requests and parse the
-responses. However, if you don’t want to send HTTP requests and parse responses
-manually, you can access the API using the client libraries, which provide
-better language integration, improved security, and support for making calls
-that require user authorization.</p>
-
-<p>For more information about the API and how to access it through the Google
-APIs Client Libraries, see the documentation at:</p> 
-
-<p style="margin-left:1.5em;"><a
-href="https://developers.google.com/android-publisher/v1/">https://developers.
-google.com/android-publisher/v1/</a></p>
-
-<h3 id="quota">Quota</h3>
-
-<p>Applications using the Google Play Android Developer API are limited to an
-initial courtesy usage quota of <strong>15000 requests per day</strong> (per
-application). This should provide enough access for normal
-subscription-validation needs, assuming that you follow the recommendation in
-this section.</p>
-
-<p>If you need to request a higher limit for your application, please use the
-“Request more” link in the <a
-href="https://code.google.com/apis/console/#:quotas">Google APIs Console</a>.
-Also, please read the section below on design best practices for minimizing your
-use of the API.</p>
-
-<h3 id="auth">Authorization</h3>
-
-<p>Calls to the Google Play Android Developer API require authorization. Google
-uses the OAuth 2.0 protocol to allow authorized applications to access user
-data. To learn more, see <a
-href="https://developers.google.com/android-publisher/authorization">Authorization</a>
-in the Google Play Android Developer API documentation.</p>
-
-<h3 id="practices">Using the API efficiently</h3>
-
-<p>Access to the Google Play Android Developer API is regulated to help ensure a
-high-performance environment for all applications that use it. While you can
-request a higher daily quota for your application, we highly recommend that you
-minimize your access using the technique(s) below. </p>
-
-<ul>
-  <li><em>Store subscription expiry on your servers</em> &mdash; your servers
-  should use the Google Play Android Developer API to query the expiration date
-  for new subscription tokens, then store the expiration date locally. This allows
-  you to check the status of subscriptions only at or after the expiration (see
-  below). </li>
-  <li><em>Cache expiration and purchaseState</em> &mdash; If your app contacts
-  your backend servers at runtime to verify subscription validity, your server
-  should cache the expiration and purchaseState to ensure the fastest possible
-  response (and best experience) for the user.</li>
-  <li><em>Query for subscription status only at expiration</em> &mdash; Once your
-  server has retrieved the expiration date of subscription tokens, it should not
-  query the Google Play servers for the subscription status again until the
-  subscription is reaching or has passed the expiration date. Typically, your
-  servers would run a batch query each day to check the status of
-  <em>expiring</em> subscriptions, then update the database. Note that: 
-  <ul>
-    <li>Your servers should not query all subscriptions every day</li>
-    <li>Your servers should never query subscription status dynamically, based on
-    individual requests from your Android application. </li>
-  </ul>
-  </li>
-</ul>
 
-<p>By following those general guidelines, your implementation will offer the
-best possible performance for users and minimize use of the Google Play Android
-Developer API.</p>
 
diff --git a/docs/html/google/play/billing/versions.jd b/docs/html/google/play/billing/versions.jd
index ac7761f..1271a15 100644
--- a/docs/html/google/play/billing/versions.jd
+++ b/docs/html/google/play/billing/versions.jd
@@ -15,9 +15,12 @@ page.title=In-app Billing Version Notes
 </ul>
 
 <h3 id="version_3">In-app Billing version 3</h3>
-<p><em>December 2012</em></p>
+<p><em>February 2013</em></p>
 <ul>
-<li>Requires Google Play client version 3.9.16 or higher.
+<li>Purchasing and querying managed in-app items requires Google Play client 
+version 3.9.16 or higher.</li>
+<li>Purchasing and querying subscription items requires Google Play client 
+version 3.10.10 or higher.</li>
 <li>Provides a new Android Interface Definition Language (AIDL) file named {@code IInAppBillingService.aidl}. The new interface offers these features:
 <ul>
 <li>Provides a new API to get details of in-app items published for the app including price, type, title and description.</li>
@@ -27,7 +30,6 @@ page.title=In-app Billing Version Notes
 <li>An API to get current purchases of the user immediately. This list will not contain any consumed purchases.</li>
 </ul>
 </li>
-<li>Subscriptions are not yet supported in this version of the API.</li>
 </ul>
 
 <h3 id="version_2">In-app Billing version 2</h3>
diff --git a/docs/html/images/in-app-billing/v3/billing_subscription_v3.png b/docs/html/images/in-app-billing/v3/billing_subscription_v3.png
new file mode 100644
index 0000000..0ba472e
--- /dev/null
+++ b/docs/html/images/in-app-billing/v3/billing_subscription_v3.png