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

page.title=In-app Subscriptions
parent.title=In-app Billing
parent.link=index.html
page.metaDescription=Create a steady revenue stream by selling subscriptions to your content.
page.image=/images/play_dev.jpg
page.tags="subscriptions, billing, inapp, iap"
meta.tags="monetization, inappbilling, subscriptions"
@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>Quickview</h2>
  <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">Subscription Cancellation</a></li>
    <li><a href="#payment">Payment Processing and Policies</a></li>
    <li><a href="#strategies">Purchase Verification Strategies</a></li>
    <li><a href="#play-dev-api">Google Play 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>
    <li><a href="https://developers.google.com/android-publisher/">Google Play Developer API</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>

  <ul>
    <li>Subscriptions let you sell products with automated, recurring billing
        at a variety of intervals.</li>
    <li>You can offer a configurable trial period for monthly and
        annual subscriptions.</li>
    <li>You can manage subscriptions through the Developer Console, or by using
        the
        <a href="https://developers.google.com/android-publisher/">Google Play
        Developer API</a>.</li>
    <li>Users purchase your subscriptions from inside your apps, rather than
        directly from Google Play.</li>
    <li>Users can renew their subscriptions while a current subscription is
        active.</li>
    <li>Users can upgrade or downgrade a subscription in the middle of a
        subscription period. The old subscription's cost is pro-rated, and the
        unused portion is applied to the replacement subscription.</li>
    <li>You can defer billing for a particular user's subscription, to manage
        accounts or offer rewards.</li>
  </ul>

<h2 id="overview">Overview</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, automated billing at the interval you specify. 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, 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 payments, 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 purchased 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 addition 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="{@docRoot}google/play/developer-api.html">Google Play 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, you can 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: Default price of subscription per recurrence</li>
<li>Recurrence: Interval of billing recurrence</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>

<p>You can also create and manage subscriptions using the
<a href="{@docRoot}google/play/developer-api.html">
Google Play Developer API</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 your choice of intervals:</p>

<ul>
  <li>Weekly &mdash; Google Play bills the customer’s Google payments 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 payments 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 payments account at
  the time of purchase and again on the same date in subsequent years.</li>

  <li>Seasonal &mdash; Google Play bills the customer's Google payments account at
  the beginning of each "season" (you specify the season beginning and end
  dates). This
  is intended for annual purchases of seasonal content (such as sports-related
  content). The subscription runs through the end of the season, and restarts
  the next year at the start of the season.</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. For
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>When the subscription payment is approved, 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="{@docRoot}google/play/developer-api.html">Google Play 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="manual-renewal">Manual Renewal</h3>

<p>With version 3 of the In-app Billing API, users can renew a subscription
during its active period even if the subscription is not set to
automatically renew. If the user purchases a subscription while the subscription
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 1-month subscription at the current rate. This one month is
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
user does not have an active subscription, the app might have a
<strong>buy</strong> button, but if the user has a subscription the button might
say <strong>renew</strong>.</p>

<h3 id="upgrade">Subscription Upgrade/Downgrade</h3>

<p>
  With version 3 of the In-app Billing API, users can upgrade or downgrade a
  subscription during its active period. When the user does this, the active
  subscription is canceled and a new subscription is created. The unused
  balance of the old subscription is applied on a pro-rated basis to the new
  subscription. The first billing period for the new subscription begins after
  that balance is used up. (The new subscription does not need to have a period
  of the same length as the old one.)
</p>

<p>For example, Samwise has a subscription to online content from the
<em>Country Gardener</em> app. He currently has a monthly subscription to the
Tier 1
version of the content (which has text-only content). This subscription costs
him £2/month, and renews on the first of the month. On April
15, he chooses to upgrade to the Tier 2 subscription (which includes video
updates), costing £3/month. His Tier 1 subscription is immediately ended.
Since he paid for a full month (April 1-30), but only used half of it, half of a
month's subscription (£1) is applied to his new subscription. However, since
that new subscription costs £3/month, the £1 credit balance only pays for ten
days. So Samwise's credit pays for his subscription from April 15-25. On April
26, he is charged £3 for his new subscription, and another £3 on the 26th of
each month following.</p>

<p class="note">
  <strong>Note:</strong> The new subscription's billing date depends on when
  the subscriber's pro-rated credit runs out, so the subscriber cannot upgrade
  or downgrade to a seasonal subscription, which has fixed and predetermined
  beginning and end dates.
</p>

<p>When a user upgrades or downgrades a subscription, your app calls
<a href="{@docRoot}google/play/billing/billing_reference.html#upgrade-getBuyIntentToReplaceSkus">
<code>getBuyIntentToReplaceSkus()</code></a>.
This method is passed the new SKU the user wants to buy, and all
the old SKUs that are superseded by it. The remaining portions of the old SKUs
are used to pay for the new subscription, and billing begins when this credit
is used up.</p>

<h3 id="deferred-billing">Deferred Billing</h3>

<p>Using the
<a href="{@docRoot}google/play/developer-api.html">Google
Play Developer API</a>, you can defer the next billing date for a
subscriber. The user continues to be subscribed to the content, and has full
access to it, but is not charged during the deferral period. This allows you
to do things like:</p>

<ul>
  <li>Give users free access as part of a bundle or a special offer (for
    example, giving free access to web content to users who subscribe to a
    print magazine)</li>
  <li>Give free access to customers as a goodwill gesture</li>
</ul>

<p>The longest you can defer billing is for one year per call. Of course, you
can call the API again before the year is up to defer billing further.</p>

<p>For example, Darcy has a monthly subscription to online content for the
<em>Fishing Gentleman</em> app. He is normally
billed £1.25 on the first of each month.
On March 10, he participates in an online survey for the app publisher. The
publisher rewards him by deferring his next payment until June 1. Darcy is not
charged on April 1 or May 1, but still has access to the content as normal. On
June 1, he is charged his normal £1.25 subscription fee.</p>

<p class="note"><strong>Note:</strong> The API always defers the billing date
by a whole number of days. If you request a deferral period that includes a
fractional number of days, the API rounds the period up to the next full day.
For example, if a user's subscription is set to renew on 15 June 2015 at
14:00:00 UTC, and you use the API to defer the renewal date to 15 August 2015 at
02:00:00 UTC, the API will round up to the next full day and set the renewal
date to 15 August 2015 14:00:00 UTC.</p>

<p>You can also offer free trials to new subscribers, as described in
<a href="#trials">Free trials</a>.</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. Free trials are supported for monthly and annual subscriptions only, and are not supported for seasonal subscriptions.</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, because 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 or via the API,
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
canceled 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, as long any user is able to access it. That is, you must
not remove any 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. Alternatively, you can use the <a href="#refunds">refund
and revoke</a> API to revoke each subscriber's subscription (one by one) and
refund their subscription payments.
Removing content that any 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">Refunding and revoking subscriptions</h3>

<p>With subscriptions, Google Play does not provide a refund window, so users
will need to request a refund. They can request a refund from the <strong>My
Orders</strong> page in the Play Store, or by contacting you directly.</p>

<p>If you receive requests for refunds, you can use the
<a href="{@docRoot}google/play/developer-api.html">Google Play
Developer API</a> or the Merchant Center to cancel the subscription, verify that it
is already canceled, or refund the user's payment without canceling it. You
can also use the
<a href="{@docRoot}google/play/developer-api.html">Google
Play Developer API</a> to <em>refund and revoke</em> a
user's subscription. If you refund and revoke a subscription, the user's
subscription is immediately canceled, and the user's most recent subscription
payment is refunded. (If you want to refund more than the most recent payment,
you can process additional refunds through the Merchant Center.)</p>

<p class="caution"><strong>Important:</strong> Partial refunds 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 payments. 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
payments 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> (first recurrence orderID)<br />
<code>12999556515565155651.5565135565155651..1</code> (second recurrence orderID)<br />
<code>12999556515565155651.5565135565155651..2</code> (third 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>

<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
to ensure that they are valid before granting access to the purchased
content.</p>

<p>To verify a purchase, the app passes the purchase token and other details up
to your backend servers, which verifies them directly with Google Play using the
Google Play Developer API.  If the backend server determines that the purchase is
valid, it notifies the app and grants access to the content.</p>

<p>Keep in mind that users will want the ability to use your app at any time,
including when there may be no network connection available. Make sure that your
approach to purchase verification accounts for the offline use-case.</p>

<h2 id="play-dev-api">Google Play Developer API</h2>

<p>Google Play offers an HTTP-based API that lets you perform such tasks as:</p>
  <ul>
    <li>Remotely query the validity of a specific subscription at any time</li>
    <li>Cancel a subscription</li>
    <li>Defer a subscription's next billing date</li>
    <li>Refund a subscription payment without canceling the subscription</li>
    <li>Refund and revoke a subscription</li>
  </ul>

<p>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>

<p>For complete information, see
<a href="{@docRoot}google/play/developer-api.html">Google Play
Developer API</a>.</p>