play/billing/gp-purchase-status-api.jd

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="#quota">Quota</a></li>
      </ol>
    </li>
  </ol>

  <h2>See also</h2>
  <ol>
    <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>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>

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

<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 &mdash;
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 &mdash; 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
subscription expirations. You can also use the API to learn about cancelled
orders and confirm whether in-app products have been consumed, including
whether they were consumed before being cancelled.</p>

<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/">Google Play Developer
API</a> v. 2.0, available through the Google Developers Console.</p>

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

<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>To access the API, you'll need to:</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>

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

<h2 id="edits">Staged Edits</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>

<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>Once all the desired changes have been staged, they are all committed with a
single operation.</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 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 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 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>
  <li><em>Cache purchase details on your servers</em> &mdash; To the extent possible,
  cache the purchase details for in-app products and subscriptions on your backend
  servers. If your app contacts your backend servers at runtime to verify purchase
  validity, your server can verify the purchase based on the cached details, to
  minimize use of the Purchase Status API and to provide the fastest possible response
  (and best experience) for the user.</li>
  <li><em>Store subscription expiry on your servers</em> &mdash; Your servers should
  use the Purchase Status 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>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 expiring 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.</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>