am 574690b1: Merge "docs: Add weekly subscriptions and grace period information to IAB docs" into lmp-mr1-ub-docs

* commit '574690b13c8f0d4835c6d86b8e26fc4c9b914037':
  docs: Add weekly subscriptions and grace period information to IAB docs

docs/html/google/play/billing/billing_reference.jd

@@ -197,7 +197,13 @@ RSASSA-PKCS1-v1_5 scheme.</td>
       lose access at that time unless they re-enable automatic renewal
       (or manually renew, as described in
       <a href="{@docRoot}google/play/billing/billing_subscriptions.html#manual-renewal">Manual
-      Renewal</a>).</td>
+      Renewal</a>).
+      If you offer a <a href="{@docRoot}google/play/billing/billing_subscriptions.html#grace-period"
+      >grace period</a>, this value remains set to <code>true</code> for all
+      subscriptions, as long as the grace period has not lapsed. The next billing date
+      is extended dynamically every day until the end of the grace period or until the
+      user fixes their payment method.
+    </td>
   </tr>
   <tr>
     <td>{@code orderId}</td>

docs/html/google/play/billing/billing_subscriptions.jd

@@ -161,6 +161,8 @@ original price, but new users will be charged at the new price.</p>
 automated recurring billing at your choice of intervals:</p>
 
 <ul>
+  <li>Weekly &mdash; Google Play bills the customer’s Google Wallet account at
+  the time of purchase and every week after the original purchase date.</li>
   <li>Monthly &mdash; Google Play bills the customer’s Google Wallet account at
   the time of purchase and monthly subsequent to the purchase date (exact billing
   intervals can vary slightly over time).</li>
@@ -183,12 +185,7 @@ monthly and annual subscriptions, billing cycles will always match subscription
 cycles, based on the purchase date. (Seasonal subscriptions are charged
 annually, on the first day of the season.)</p>
 
-<p>Over the life of a subscription, the form of payment billed remains the same
+<p>When the subscription payment is approved, Google Play
-&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 Wallet, Google Play
 provides a purchase token back to the purchasing app through the In-app Billing
 API. Your apps can store the token locally or pass it to your backend servers,
 which can then use it to validate or cancel the subscription remotely using the
@@ -220,8 +217,8 @@ is active, it is extended by the appropriate period at the current rate.</p>
 
 <p>For example, Achilles has a subscription to the <em>Modern Hoplite</em> app.
 His subscription is currently due to expire on August 1. On July 10, he
-purchases a 3-month subscription at the current rate. Those three months are
+purchases a 1-month subscription at the current rate. This one month is
-added to his existing subscription, so the subscription now expires on November
+added to his existing subscription, so the subscription now expires on September
 1.</p>
 
 <p>It is up to the app to convey this with an appropriate UI. For example, if a
@@ -465,6 +462,25 @@ each recurring transaction by appending an integer as follows: </p>
 {@code orderId} field of the {@code INAPP_PURCHASE_DATA} JSON field (in V3)
 or the {@code PURCHASE_STATE_CHANGED} intent (in V2).</p>
 
+<h3 id="grace-period">Grace period for declined payments</h3>
+
+<p>
+  The Developer Console allows you to set a grace period for subscriptions, so you can give
+  your subscribers a chance to update their payment method if a recurring payment is declined.
+  This setting is useful if your subscribers have an expired credit card, subscribed using a
+  prepaid card, or canceled a card without updating their payment information. For
+  information about setting a grace period for subscriptions, see the Developer Console Help
+  topic <a href="https://support.google.com/googleplay/android-developer/answer/140504"
+  class="external-link">Add subscriptions &amp; recurring charges</a>.
+</p>
+
+</p>
+  For information on how setting a grace period affects data returned from the
+  {@code getBuyIntent()} method, see the
+  <a href="{@docRoot}google/play/billing/billing_reference.html#purchase-data-table"
+  >{@code INAPP_PURCHASE_DATA}</a> fields table.
+</p>
+
 <h2 id="strategies">Purchase Verification Strategies</h2>
 
 <p>In a typical scenario, your app verifies the order status for new purchases

docs/html/google/play/billing/index.jd

@@ -34,17 +34,14 @@ and features, and more. You can use In-app Billing to sell products as</p>
     <a href="billing_subscriptions.html#deferred-billing">defer</a> a
     subscriber's next billing date until the date you choose. The user still has
     access to the content but is not charged during the deferral period.</li>
-  <li><strong>Google Play Developer API</strong>&mdash;The
+  <li><strong>Weekly subscriptions</strong>&mdash;You can now set up a
-    <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google
+    recurring <a href="billing_subscriptions.html#user-billing">subscription</a>
-    Play Developer API</a> allows you to perform a number of publishing and
+    that bills the user every week.</li>
-    app-management tasks. It includes the functionality previously known as the
+  <li><strong>Payment grace period</strong>&mdash;If a subscriber misses a
-    <em>Purchase Status API.</em> </li>
+    subscription payment due to an expired credit card, you can define a
-  <li><strong>Refund/Revoke subscription</strong>&mdash;You can use the
+    <a href="billing_subscriptions.html#grace-period">grace period</a>
-    Google Play Developer API to <a href="billing_subscriptions.html#refunds">refund
+    to the continue the subscription until payment is successful.</li>
-    and revoke</a> a user's subscription. If you do this, the user's
+
-    subscription ends
-    immediately, and his or her most recent subscription payment is
-    refunded.</li>
  </ul>
 </div>
 </div>