am 4d58740b: am a5e5d455: Merge "resolved conflicts for merge of 60e7f541 to lmp-dev" into lmp-dev

      <li><a href="<?cs var:toroot?>google/play/billing/billing_admin.html">

              <span class="en">Administering In-app Billing</span></a>

      </li>

      <li><a href="<?cs var:toroot?>google/play/billing/gp-purchase-status-api.html">

              <span class="en">Purchase Status API</span></a>

      </li>

      <li><a href="<?cs var:toroot?>google/play/billing/versions.html">

              <span class="en">Version Notes</span></a>

      </li>

      <li><a href="<?cs var:toroot ?>google/play/filters.html">

          <span class="en">Filters on Google Play</span></a>

      </li>

      <li><a href="<?cs var:toroot?>google/play/billing/gp-purchase-status-api.html">

              <span class="en">Google Play Developer API</span></a>

      </li>

      <li><a href="<?cs var:toroot ?>google/play/publishing/multiple-apks.html">

          <span class="en">Multiple APK Support</span></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="#strategies">Purchase Verification Strategies</a></li>

  </ol>

  <h2>See also</h2>

  <ol>

{@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="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

Purchase Status 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 Android Developer API</h2>

<p>Google Play offers an HTTP-based API that lets you remotely query the

page.title=Purchase Status API

page.tags=In-app Billing,Google Play,inapp billing,in app billing,iab,billing

page.title=Google Play Developer API

page.tags="In-app Billing", "Google Play", "inapp billing", "in app billing", "iab", "billing", "publishing"

@jd:body

<div id="qv-wrapper">

<div id="qv">

  <h2>In this document</h2>

  <!-- TODO: Update TOC -->

  <ol>

    <li><a href="#publishing_api_overview">Publishing API</a>

    <li><a href="#subscriptions_api_overview">Subscriptions and In-App

          Purchases API</a></li>

    <li><a href="#using">Using the API</a>

    <li><a href="#edits">Staged Edits</a></li>

    <li><a href="#practices">Using the API Efficiently</a>

      <ol>

    <li><a href="#overview">Overview</a></li>

    <li><a href="#using">Using the API</a></li>

        <li><a href="#strategies">Verification Strategies</a></li>

            <li><a href="#practices">Using the API Efficiently</a></li>

        <li><a href="#quota">Quota</a></li>

      </ol>

    </li>

  </ol>

  <h2>See also</h2>

  <ol>

    <li><a href="https://developers.google.com/android-publisher/v1_1/">Google Play Android Developer API</a></li>

    <li><a href="https://developers.google.com/android-publisher/">Google Play

        Developer API</a> documentation</li>

    <li><a href="https://support.google.com/googleplay/android-developer/answer/6071616">Google

        Help Center</a> overview of the Google Play Developer API</li>

  </ol>

</div>

</div>

<p>Google Play provides an HTTP-based Purchase Status API that lets

you remotely query the status of a specific in-app product or subscription,

or cancel an active subscription. The API is designed to be used from your

backend servers as a way of securely managing in-app products and

subscriptions, as well as extending and integrating them with other services.</p>

<p>The Google Play Developer API is a REST-based web service that allows you to perform publishing

and app-management tasks. You can use this API to integrate your publishing

operations with your release-management process.</p>

<h2 id="overview">Overview</h2>

<p>Not all developers will need to use these APIs&mdash;in most cases you will

continue to manage your apps directly using the Google Play Developer Console.

However, if you have a large number of APKs to manage, or have to track user

purchases and subscriptions, you may find this API very useful.</p>

<p>Using the Google Play Developer API, you can automate a variety of

app-management tasks, including:</p>

<ul>

<li>Uploading and releasing new versions of your app</li>

<li>Editing your app Google Play Store listings, including localized text and

    graphics</li>

<li>Managing your in-app product catalog, your products purchase status and your

    app subscriptions</li>

</li>

</ul>

<p>The Google Play Developer API lets you focus on designing and developing your

app, while spending less time and effort managing your releases, even as you

grow to new markets.</p>

<p>The Google Play Developer API includes two components:</p>

<ul>

<li>The <a href="#publishing_api_overview">Publishing API</a> lets you upload and publish

  apps, and perform other publishing-related tasks.</li>

<li>The <a href="#subscriptions_api_overview">Subscriptions and In-App Purchases

  API</a> lets you manage in-app purchases and subscriptions. (This was

  previously known as the "Purchase Status API".)</li>

</ul>

<p>With the Purchase Status API you can quickly retrieve the details of any

purchase using a standard GET request. In the request you supply information

about the purchase — app package name, purchase or subscription ID,

and the purchase token. The server responds with a JSON object describing

the associated purchase details, order status, developer payload, and other

information.</p>

<h2 id="publishing_api_overview">Publishing API</h2>

<p>

The Google Play Developer Publishing API allows you to automate frequent tasks

having to do with app distribution. This provides functions

similar to those available to a developer through the Google Play

Developer Console, such

as:

</p>

<ul><li>Uploading new versions of an app</li>

<li>Releasing apps, by assigning APKs to various <em>Tracks</em> (alpha, beta,

  staged rollout, or production)</li>

<li>Creating and modifying Google Play Store listings, including localized text

  and graphics and multi-device screenshots</li></ul>

<p>Those tasks are performed using the

<a href="#edits">edits</a>

functionality, which takes a transactional approach to making changes —

you bundle several changes into a single draft edit, then commit the changes all

at once. (None of the changes take effect until the edit is committed.)</p>

<p class="note"><strong>Note:</strong> Not all developers will need to use this

API. All the functionality provided by the API is also available through the

Google Play

Developer Console. However, this API lets you integrate your app and listing

update process with your existing tools, which will be very useful for some

developers. In particular, if you have a large number of APKs to manage, or

localized listings in many different locales, you may find this API invaluable.

</p>

<h2 id="subscriptions_api_overview">Subscriptions and In-App Purchases API</h2>

<p>The API allows you to manage your app's catalog of in-app products and

subscriptions. In addition, with the Subscriptions and In-App Purchases API you

can quickly retrieve the

details of any purchase using a standard GET request. In the request you supply

information about the purchase — app package name, purchase or

subscription ID, and the purchase token. The server responds with a JSON object

describing the associated purchase details, order status, developer payload, and

other information.</p>

<p>You can use the Purchase Status API in several ways, such as for reporting

and reconciliation of individual orders and for verifying purchases and

orders and confirm whether in-app products have been consumed, including

whether they were consumed before being cancelled.</p>

<p>For subscriptions, in addition to querying for order status and expiration,

you can use the Purchase Status API to remotely cancel a subscription. This is a

convenient way to manage cancellations on behalf of customers, without

requiring them to manage the cancellation themselves on their Android devices.</p>

<p>If you plan to use the Purchase Status API, keep in mind that:</p>

<ul><li>You can use the API to check the status of individual items only

&mdash; bulk requests for order status are not supported at this time.</li>

<li>You can query for the details of orders placed on or after 12 June 2013,

but not for orders placed earlier.</li>

<li>You can query purchases of any item type made with the In-app

Billing v3 API, or purchases of managed items made with In-app Billing v1 and

v2. You can not use the Purchase Status API to query purchases of unmanaged items

made with In-app Billing v1 or v2.</li>

</ul>

<p class="note"><strong>Note:</strong> The Subscriptions and In-App

Purchases API does not use the new, transactional "edits" functionality used by

the <a href="#publishing_api_overview">Publishing API</a>. Methods for the

<a href="https://developers.google.com/android-publisher/api-ref/inappproducts">Inappproducts</a>,

<a href="https://developers.google.com/android-publisher/api-ref/purchases/products">Purchases.products</a>,

and <a href="https://developers.google.com/android-publisher/api-ref/purchases/subscriptions">Purchases.subscriptions</a>

resources take effect immediately. Each resource's API reference page notes

specifically whether the methods for that resource use the "edits"

model.</p>

<p>The Purchase Status API is part of the <a

href="https://developers.google.com/android-publisher/v1_1/">Google Play Android

Developer API v1.1</a>, available through the Google Developers Console. The new version

of the API supersedes the v1 API, which is deprecated. If you are using the v1

API, please migrate your operations to the v1.1 API as soon as possible.</p>

href="https://developers.google.com/android-publisher/">Google Play Developer

API</a> v. 2.0, available through the Google Developers Console.</p>

<h2 id="using">Using the API</h2>

<p>To use the API, you must first register a project at the <a

href="https://cloud.google.com/console">Google Developers Console</a> and receive

a Client ID and shared secret that  your app will present when calling the

API. All calls 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. The 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 Google APIs 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>To start making API calls, you’ll set up and manage the Google Play Developer

API directly from the <a href="https://play.google.com/apps/publish/">Google

Play Developer Console</a>. The API can only be managed by the owner of your

Google Play Developer account.</p>

<p style="margin-left:1.5em;"><a

href="https://developers.google.com/android-publisher/v1_1/">https://developers.

google.com/android-publisher/v1_1/</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>200,000 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>To access the API, you'll need to:</p>

<p>If you need to request a higher limit for your application, see the

instructions in the <a

href="https://developers.google.com/console/help/new/#trafficcontrols">Google Developers

Console Help</a>.

Also, please read the section below on design best practices for minimizing your

use of the API.</p>

<ol><li>Set up a new or existing API project</li>

<li>Set up one or more authorized clients, which can be either:

<ul>

  <li><a href="https://developers.google.com/accounts/docs/OAuth2">OAuth

      clients</a></li>

  <li><a href="https://developers.google.com/accounts/docs/OAuth2ServiceAccount">

      service account</a></li>

</ul></li></ol>

<h3 id="auth">Authorization</h3>

<p>For full details, see the Google Play Developer API

<a href="https://developers.google.com/android-publisher/getting_started">Getting

Started</a> page.</p>

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

<h2 id="edits">Staged Edits</h2>

<h2 id="strategies">Purchase Verification Strategies</h2>

<p>The Google Play Developer Publishing API Edits methods allow you to prepare

and commit changes to your Google Play apps. Once your update is ready to go,

you can deploy it with a single operation. The changes you can make include:</p>

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

<ul>

  <li>Uploading one or more APKs</li>

  <li>Assigning different APKs to different “tracks”: alpha, beta, staged

      rollout, and production</li>

  <li>Creating and modifying localized store listings for the app</li>

  <li>Uploading screenshots and other images for the app’s store listings</li>

</ul>

<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

Purchase Status API. For security reasons, the app should not normally attempt to verify

the purchase itself using the Purchase Status API.</p>

<p>Once all the desired changes have been staged, they are all committed with a

single operation.</p>

<p>If the backend server determines that the purchase is valid, it notifies the

app and grants access to the content. For improved performance, the backend servers

should store the purchase details and order status in a local database, updated at

intervals or as-needed.</p>

<p>For full details on staged edits, see the Google Play Developer API

<a href="https://developers.google.com/android-publisher/edits/">Edits</a>

page.</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>

<p class="note"><strong>Note:</strong> The new, transactional "edits"

functionality is only used by the <a href="#publishing_api_overview">Publishing

API</a>. Methods for the <a href="#subscriptions_api_overview">Subscriptions and

In-App Purchases API</a> take effect immediately. Each resource's API reference

page notes specifically whether the methods for that resource use the "edits"

model.</p>

<h2 id="practices">Using the API Efficiently</h2>

<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

<p>Access to the Google Play Developer API is regulated to help ensure a

high-performance environment for all applications that use it (as described in

<a href="#quota">Quota</a>). While you can

request a higher daily quota for your application, we highly recommend that you

minimize your access using the techniques below. </p>

minimize your access using these techniques: </p>

<ul>

  <li><em>Limit the number of app updates</em> &mdash; Do not publish alpha or beta

  updates more frequently than once a day. (Production apps should be updated

  even less frequently than that.) Every update costs your users time and

  possibly money. If you update too frequently, users will start ignoring

  updates, or even uninstall the product. (Of course, if there's a major problem

  with your app, go ahead and fix it.)</li>

  <li><em>Query the Purchase Status API for new purchases only</em> &mdash; At

  purchase, your app can pass the purchase token and other details to your backend

  servers, which can use the Purchase Status API to verify the purchase.</li>

</ul>

<p>By following those general guidelines, your implementation will offer the

best possible performance for users and minimize use of the <a

href="https://developers.google.com/android-publisher/v1_1/">Google Play Android

Developer API</a>.</p>

best possible performance for users.</p>

<h3 id="quota">Quota</h3>

<p>Applications using the Google Play Developer API are limited to an

initial courtesy usage quota of <strong>200,000 requests per day</strong> (per

application). This should provide enough access for publishing activities and

normal subscription-validation needs.</p>

<p>If you need to request a higher limit for your application, use the "Request

more" link on the <strong>Quotas</strong>

pane of the Google Developers Console.</p>

<div class="sidebox">

  <h2><strong>New in In-App Billing</strong></h2>

  <ul>

  <li><strong>Purchase Status API</strong>&mdash;The <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Purchase Status API</a> lets you query the status of in-app product or subscription purchases. </li>

  <li><strong>Google Play Developer API</strong>&mdash;The

    <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google

    Play Developer API</a> allows you to perform a number of publishing and

    app-management tasks. It includes the functionality previously known as the

    <em>Purchase Status API.</em> </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>

    <p>Protect your revenue streams and integrate policies for usage into your app.

    </p><a href="{@docRoot}google/play/licensing/index.html">Learn more &raquo;</a>

  </div>

  <div class="layout-content-col span-6">

    <h4>

      Google Play Developer API

    </h4>

    <p>Integrate your publishing operations with your release-management

      process.

    </p><a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Learn more &raquo;</a>

  </div>

</div>