path: root/docs/html/google/play/billing/billing_admin.jd

page.title=Administering In-app Billing
parent.title=In-app Billing
parent.link=index.html
@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>In this document</h2>
  <ol>
    <li><a href="#billing-list-setup">Creating a Product List</a></li>
    <li><a href="#billing-purchase-type">Choosing a Product Type</a></li>
    <li><a href="#billing-testing-setup">Setting up Test Accounts</a></li>
    <li><a href="#billing-refunds">Handling Refunds</a></li>
    <li><a href="#billing-refunds">Working with Order Numbers</a></li>
    <li><a href="#billing-support">Where to Get Support</a></li>
  </ol>

  </ol>
  <h2>See also</h2>
  <ol>
    <li><a href="{@docRoot}google/play/billing/billing_overview.html">Overview of In-app
    Billing</a></li>
  </ol>
</div>
</div>

<p>In-app billing frees you from processing financial transactions, but you still need to perform a
few administrative tasks, including setting up and maintaining your product list on the Google Play
Developer Console, registering test accounts, and handling refunds when necessary.</p>

<p>You must have a Google Play publisher account to register test accounts. And you must have a
Google Wallet merchant account to create a product list and issue refunds to your users. If you
already have a publisher account on Google Play, you can use your existing account. You do not
need to register for a new account to support in-app billing.</p>

<p>If you do not have a publisher account, you can register as a Google Play
developer and set up a publisher account at the <a
href="http://play.google.com/apps/publish">Google Play Developer Console</a>. If you do not
have a Google Wallet merchant account, you can register for one through the
Developer Console.</p>

<h2 id="billing-list-setup">Creating a Product List</h2>

<p>The Google Play Developer Console provides a product list for each of your published
applications. You can sell an item using Google Play's in-app billing feature only if the item is
listed on an application's product list. Each application has its own product list; you cannot sell
items that are listed in another application's product list.</p>

<p>You can access an application's product list by clicking the <strong>In-App Products</strong>
link in applications listed in your developer account (see
figure 1). The <strong>In-App Products</strong> link appears only if you have a Google Wallet
merchant account and the application's manifest includes the <code>com.android.vending.BILLING</code>
permission.</p>

<p>A product list specifies items you are selling in an application &mdash; in-app products,
subscriptions, or a combination of both. For each item, the product list contains information such as a product id,
product description, and price. The product list stores only metadata about the items
you are selling in your application. It does not store any digital content. You are responsible for
storing and delivering the digital content that you sell in your applications.</p>

<div style="margin:1em;">
<img style="border:1px solid #ddd;padding-bottom:.5em" src="{@docRoot}images/in-app-billing/billing_product_list.png" xheight="548" id="figure1" />
<p class="img-caption" style="padding-left:.5em;">
  <strong>Figure 1.</strong> You can access an application's product list by clicking the
  <strong>In-App Products</strong> link in the main Apps navigation.
</p>
</div>

<p>You can create a product list for any published application or any draft application that's been
uploaded and saved to the Developer Console. However, you must have a Google Wallet merchant
account and the application's manifest must include the <code>com.android.vending.BILLING</code>
permission. If an application's manifest does not include this permission, you will be able to edit
existing items in the product list but you will not be able to add new items to the list. For more
information about this permission, see
<a href="{@docRoot}google/play/billing/billing_integrate.html#billing-permission">Updating Your
Application's Manifest</a>.</p>

<p>In addition, an application package can have only one product list. If you create a product
list for an application, and you use the <a
href="{@docRoot}google/play/publishing/multiple-apks.html">multiple APK feature</a> to distribute
more than one APK for that application, the product list applies to all APK versions that are
associated with the application listing. You cannot create individual product lists for each APK if
you are using the multiple APK feature.</p>

<p>You can add items to a product list two ways: you can add items one at a time by using the In-app
Products UI (see figure 2), or you can add a batch of items by importing the items from a
comma-separated values (CSV) file. Adding items one at a time is useful if your
application has only a few in-app items or you are adding only a few items to a
product list for testing purposes. The CSV file method is useful if your application has a large
number of in-app items.</p>

<p class="note"><strong>Note:</strong> Batch upload of product lists containing subscriptions is not yet supported.</p>

<h3 id="billing-form-add">Adding items one at a time to a product list</h3>

<p>To add an item to a product list using the In-app Products UI, follow these steps:</p>

<ol>
  <li><a href="http://play.google.com/apps/publish">Log in</a> to your publisher account.</li>
  <li>In the <strong>All Google Play listings</strong> panel, under the application name, click
  <strong>In-app Products</strong>.</li>
  <li>Click <strong>Add new product</strong> (see figure 2) and provide details about the item you are
  selling and then click <strong>Save</strong> or <strong>Publish</strong>.</li>
</ol>

<div style="margin:1em;">
<img style="border:1px solid #ddd;padding-bottom:.5em;" src="{@docRoot}images/in-app-billing/billing_add.png" height="300" id="figure2" />
<p class="img-caption" style="padding-left:.5em;">
  <strong>Figure 2.</strong> The Add New Product page lets you add items to an
  application's product list.
</p>
</div>

<p>You must enter the following information for each item in a product list:</p>
<ul>
  <li><strong>In-app Product ID</strong>
    <p>Product IDs are unique across an application's namespace. A product ID must start with a
    lowercase letter or a number, and must be composed using only lowercase letters (a-z), numbers
    (0-9), underlines (_), and dots (.). The product ID "android.test" is reserved, as are all
    product IDs that start with "android.test."</p>
    <p>In addition, you cannot modify an item's product ID after it is created, and you cannot reuse
    a product ID.</p>
  </li>
  <li><strong>Product Type</strong>
    <p>The product type can be <strong>Managed per user account</strong>, <strong>Unmanaged</strong>,
    or <strong>Subscription</strong>. You can never change an item's product type after you set it. For more
    information, see <a href="#billing-purchase-type">Choosing a product type</a> later in this
    document.</p>
  </li>
  <li><strong>Publishing State</strong>
    <p>An item's publishing state can be <strong>Published</strong> or <strong>Unpublished
    </strong>. To be visible to a user during checkout, an item's publishing state must be set to
    <strong>Published</strong> and the item's application must be published on Google Play.</p>
    <p class="note"><strong>Note:</strong> This is not true for test accounts. An item is visible to
    a test account if the application is not published and the item is published. See <a
    href="{@docRoot}google/play/billing/billing_testing.html#billing-testing-real">Testing In-app
    Billing</a> for more information.</p>
  </li>
  <li><strong>Languages and Translations</strong>
    <p>You can provide localized titles and descriptions for your in-app
    products using the Add Translations button. If you want Google Play to translate
    your title and description for you, based on the title and description in the
    default language, just click the languages that you want to offer. If you want
    to provide custom translations in specific languages, you can also do that. By
    default, an in-app product inherits its default language from the parent
    application.</p>
  </li>
  <li><strong>Title</strong>
    <p>The title is a short descriptor for the item. For example, "Sleeping potion." Titles must be
    unique across an application's namespace. Every item must have a title. The title is visible to
    users during checkout. For optimum appearance, titles should be no longer than 25 characters;
    however, titles can be up to 55 characters in length.</p>
  </li>
  <li><strong>Description</strong>
    <p>The description is a long descriptor for the item. For example, "Instantly puts creatures to
    sleep. Does not work on angry elves." Every item must have a description. The description is
    visible to users during checkout. Descriptions can be up to 80 characters in length.</p>
  </li>
  <li><strong>Price</strong>
    <p>You must provide a default price in your home currency. You can also provide prices in other
    currencies, but you can do this only if a currency's corresponding country is listed as a
    target country for your application. You can specify target countries on the Edit Application
    page in the Google Play developer console.</p>
    <p>To specify prices in other currencies, you can manually enter the price for each
    currency or you can click <strong>Auto Fill</strong> and let Google Play do a one-time
    conversion from your home currency to the currencies you are targeting (see figure 3).</p>
    <p>For subscription items, note that you can not change the item's price once you have published it. </p>
  </li>
</ul>

<div style="margin:1em;">
<img style="border:1px solid #ddd;padding-bottom:.5em" src="{@docRoot}images/in-app-billing/billing_list_form_2.png" xheight="1226" id="figure3" />
<p class="img-caption" style="padding-left:.5em;">
  <strong>Figure 3.</strong> Specifying additional currencies for an in-app product.
</p>
</div>

<p>For more information about product IDs and product lists, see <a
href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1072599">Creating In-App Product
IDs</a>. For more information about pricing, see <a
href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1153485">In-App Billing
Pricing</a>.</p>

<p class="note"><strong>Note</strong>: Be sure to plan your product ID namespace. You cannot reuse
or modify product IDs after you save them.</p>

<h3 id="billing-bulk-add">Adding a batch of items to a product list</h3>

<p>To add a batch of items to a product list using a CSV file, you first need to create your CSV
file. The data values that you specify in the CSV file represent the same data values you specify
manually through the In-app Products UI (see <a href="#billing-form-add">Adding items one at a time
to a product list</a>). 

<p>If you are importing and exporting CSV files with in-app products, please
keep tax-inclusive pricing in mind. If you use auto-fill, you can provide a
tax-exclusive default price and tax-inclusive prices will be auto-filled. If you
do not use auto-fill, prices you provide must include tax.</p>

<p class="note"><strong>Note:</strong> Batch upload of product lists containing subscriptions is not yet supported.</p>

The CSV file uses commas (,) and semi-colons (;) to separate data values.
Commas are used to separate primary data values, and semi-colons are used to separate subvalues. For
example, the syntax for the CSV file is as follows:</p>

<p>"<em>product_id</em>","<em>publish_state</em>","<em>purchase_type</em>","<em>autotranslate</em>
","<em>locale</em>; <em>title</em>; <em>description</em>","<em>autofill</em>","<em>country</em>;
<em>price</em>"
</p>

<p>Descriptions and usage details are provided below.</p>

<ul>
  <li><em>product_id</em>
    <p>This is equivalent to the In-app Product ID setting in the In-app Products UI. If you specify
    a <em>product_id</em> that already exists in a product list, and you choose to overwrite
    the product list while importing the CSV file, the data for the existing item is overwritten with
    the values specified in the CSV file. The overwrite feature does not delete items that are on a
    product list but not present in the CSV file.</p>
  </li>
  <li><em>publish_state</em>
    <p>This is equivalent to the Publishing State setting in the In-app Products UI. Can be <code>
    published</code> or <code>unpublished</code>.</p>
  </li>
  <li><em>purchase_type</em>
    <p>This is equivalent to the Product Type setting in the In-app Products UI. Can be <code>
    managed_by_android</code>, which is equivalent to <strong>Managed per user account
    </strong> in the In-app Products UI, or <code>managed_by_publisher</code>, which is equivalent
    to <strong>Unmanaged</strong> in the In-app Products UI.</p>
  </li>
  <li><em>autotranslate</em>
    <p>This is equivalent to selecting the <strong>Fill fields with auto translation</strong>
    checkbox in the In-app Products UI. Can be <code>true</code> or <code>false</code>.</p>
  </li>
  <li><em>locale</em>
    <p>This is equivalent to the Language setting in the In-app Products UI. You must have an entry
    for the default locale. The default locale must be the first entry in the list of
    locales, and it must include a <em>title</em> and <em>description</em>. If you want to provide
    translated versions of the <em>title</em> and <em>description</em> in addition to the default,
    you must use the following syntax rules:</p>
    <p>If <em>autotranslate</em> is <code>true</code>, you must specify the default locale,
    default title, default description, and other locales using the following format:</p>
    <p>"true,"<em>default_locale</em>; <em>default_locale_title</em>;
    <em>default_locale_description</em>; <em>locale_2</em>;    <em>locale_3</em>, ..."</p>
    <p>If <em>autotranslate</em> is <code>false</code>, you must specify the default locale,
    default title, and default description as well as the translated titles and descriptions using
    the following format:</p>
    <p>"false,"<em>default_locale</em>; <em>default_locale_title</em>;
    <em>default_locale_description</em>; <em>locale_2</em>; <em>locale_2_title</em>;
    <em>local_2_description</em>; <em>locale_3</em>; <em>locale_3_title</em>;
     <em>locale_3_description</em>; ..."</p>
    <p>See table 1 for a list of the language codes you can use with the <em>locale</em> field.</p>
  </li>
  <li><em>title</em>
    <p>This is equivalent to the Title setting in the In-app Products UI. If the <em>title</em>
    contains a semicolon, it must be escaped with a backslash (for example, "\;"). A backslash
    should also be escaped with a backslash (for example, "\\">.</p>
  </li>
  <li><em>description</em>
    <p>This is equivalent to the Description in the In-app Products UI. If the <em>description</em>
    contains a semicolon, it must be escaped with a backslash (for example, "\;"). A backslash
    should also be escaped with a backslash (for example, "\\">.</p>
  </li>
  <li><em>autofill</em>
    <p>This is equivalent to clicking <strong>Auto Fill</strong> in the In-app Products UI. Can be
    <code>true</code> or <code>false</code>. The syntax for specifying the <em>country</em>
    and <em>price</em> varies depending on which <em>autofill</em> setting you use.</p>
    <p>If <em>autofill</em> is set to <code>true</code>, you need to specify only the default
    price in your home currency and you must use this syntax:</p>
    <p>"true","<em>default_price_in_home_currency</em>"
    <p>If <em>autofill</em> is set to <code>false</code>, you need to specify a <em>country</em>
    and a <em>price</em> for each currency and you must use the following syntax:</p>
    <p>"false", "<em>home_country</em>; <em>default_price_in_home_currency</em>; <em>country_2</em>;
    <em>country_2_price</em>; <em>country_3</em>; <em>country_3_price</em>; ..."</p>
  </li>
  <li><em>country</em>
    <p>The country for which you are specifying a price. You can only list countries that your
    application is targeting. The country codes are two-letter uppercase
    ISO country codes (such as "US") as defined by
    <a href="http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166-2</a>.</p>
  </li>
  <li><em>price</em>
    <p>This is equivalent to the Price in the In-app Products UI. The price must be specified in
    micro-units. To convert a currency value to micro-units, you multiply the real value by 1,000,000.
    For example, if you want to sell an in-app item for $1.99 you specify 1990000 in the
    <em>price</em> field.</p>
  </li>
</ul>

<p class="table-caption" id="language-table"><strong>Table 1.</strong> Language codes you can use
with the <em>locale</em> field.</p>

<table>

<tr>
<th>Language</th>
<th>Code</th>
<th>Language</th>
<th>Code</th>
</tr>
<tr>
<td>Chinese</td>
<td>zh_TW</td>
<td>Italian</td>
<td>it_IT</td>
</tr>
<tr>
<td>Czech</td>
<td>cs_CZ</td>
<td>Japanese</td>
<td>ja_JP</td>
</tr>
<tr>
<td>Danish</td>
<td>da_DK</td>
<td>Korean</td>
<td>ko_KR</td>
</tr>
<tr>
<td>Dutch</td>
<td>nl_NL</td>
<td>Norwegian</td>
<td>no_NO</td>
</tr>
<tr>
<td>English</td>
<td>en_US</td>
<td>Polish</td>
<td>pl_PL</td>
</tr>
<tr>
<td>French</td>
<td>fr_FR</td>
<td>Portuguese</td>
<td>pt_PT</td>
</tr>
<tr>
<td>Finnish</td>
<td>fi_FI</td>
<td>Russian</td>
<td>ru_RU</td>
</tr>
<tr>
<td>German</td>
<td>de_DE</td>
<td>Spanish</td>
<td>es_ES</td>
</tr>
<tr>
<td>Hebrew</td>
<td>iw_IL</td>
<td>Swedish</td>
<td>sv_SE</td>
</tr>
<tr>
<td>Hindi</td>
<td>hi_IN</td>
<td>--</td>
<td>--</td>
</tr>
</table>

<p>To import the items that are specified in your CSV file, do the following:</p>

<ol>
  <li><a href="http://play.google.com/apps/publish">Log in</a> to your publisher account.</li>
  <li>In the <strong>All Google Play listings</strong> panel, under the application name, click
  <strong>In-app Products</strong>.</li>
  <li>On the In-app Products List page, click <strong>Choose File</strong> and select your CSV
file.
    <p>The CSV file must be on your local computer or on a local disk that is connected to your
    computer.</p>
  </li>
  <li>Select the <strong>Overwrite</strong> checkbox if you want to overwrite existing items in
  your product list.
    <p>This option overwrites values of existing items only if the value of the <em>product_id</em>
    in the CSV file matches the In-app Product ID for an existing item in the product list.
    Overwriting does not delete items that are on a product list but not present in the CSV
    file.</p>
  </li>
  <li>On the In-app Products List page, click <strong>Import from CSV</strong>.</li>
</ol>

<p>You can also export an existing product list to a CSV file by clicking <strong>Export to CSV
</strong> on the In-app Product List page. This is useful if you have manually added items to
a product list and you want to start managing the product list through a CSV file.</p>

<h3 id="billing-purchase-type">Choosing a Product Type</h3>

<p>An item's product type controls how Google Play manages the purchase of the item. There are
several product types, including "managed per user account", "unmanaged," and "subscription." However,
note that the product types supported vary
across In-app Billing Version, so you should always choose a product type that's valid for the
version of In-app BIlling that your app uses. </p>

<p>For details, refer to the documentation for <a
href="{@docRoot}google/play/billing/api.html#producttype">In-app Billing Version
3</a> or <a href="{@docRoot}google/play/billing/v2/api.html#producttype">In-app
Billing Version 2</a>.

<h2 id="billing-refunds">Handling Refunds</h2>

<p>In-app billing does not allow users to send a refund request to Google Play. Refunds for
in-app purchases must be directed to you (the application developer). You can then process the
refund through your Google Wallet merchant account. When you do this, Google Play receives a
refund notification from Google Wallet, and Google Play sends a refund message to your
application. For more information, see <a
href="{@docRoot}google/play/billing/v2/api.html#billing-action-notify">Handling
IN_APP_NOTIFY messages</a> and <a
href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1153485">In-app Billing
Pricing</a>.</p>

<p class="caution"><strong>Important:</strong> You cannot use the Google Wallet API to issue
refunds or cancel In-app Billing transactions. You must do this manually through your Google
Wallet merchant account. However, you can use the Google Wallet API to retrieve order
information.</p>

<h2 id="orderId">Working with Order Numbers</h2>

<p>When a user purchases an in-app item, Google Wallet assigns the transaction
a unique and permanent order number. Google Play provides that order number to
you at the conclusion of the purchase flow, as the value of the
<code>orderId</code> field of the <code>PURCHASE_STATE_CHANGED</code>
intent.</p>

<p>In your app, you can use the order number as a general-purpose identifier for
the in-app purchase transaction. After the purchase, you can use the order
number as a means of tracking the transaction in reconciliation reports and for
customer support.</p>

<p>The order number itself is a string consisting of numbers only, with a format
assigned and managed by Google Wallet.</p>

<p>For transactions dated 5 December 2012 or later, Google Wallet assigns a
Merchant Order Number (rather than a Google Order Number) and reports the Merchant
Order Number as the value of <code>orderID</code>. Here's an
example:</p>

<pre>"orderId" : "12999556515565155651.5565135565155651"</pre>

<p>For transactions dated previous to 5 December 2012, Google checkout assigned
a Google Order Number and reported that number as the value of
<code>orderID</code>. Here's an example of an <code>orderID</code> holding a
Google Order Number:</p>

<pre>"orderId" : "556515565155651"</pre>

<h2 id="billing-testing-setup">Setting Up Test Accounts</h2>

<p>The Google Play Developer Console lets you set up one or more test accounts. A test account is a
regular Google account that you register on the Developer Console as a test account. Test accounts are
authorized to make in-app purchases from applications that you have uploaded to the Google Play
Developer Console but have not yet published.</p>

<p>You can use any Google account as a test account. Test accounts are useful if you want to let
multiple people test In-app Billing on applications without giving them access to your publisher
account's sign-in credentials. If you want to own and control the test accounts, you can create the
accounts yourself and distribute the credentials to your developers or testers.</p>

<p>Test accounts have three limitations:</p>

<ul>
  <li>Test account users can make purchase requests only within applications that are already
  uploaded to your publisher account (although the application doesn't need to be published).</li>
  <li>Test accounts can only be used to purchase items that are listed (and published) in an
  application's product list.</li>
  <li>Test account users do not have access to your publisher account and cannot upload applications
  to your publisher account.</li>
</ul>

<p>To add test accounts to your publisher account, follow these steps:</p>

<ol>
  <li><a href="http://play.google.com/apps/publish">Log in</a> to your publisher account.</li>
  <li>Click the <strong>Settings</strong> icon. (If you are using the old Developer Console UI, click
  <strong>Edit profile</strong> in the upper left part of the page, under your name,)</li>
  <li>Locate the License Testing panel. (In the old UI, scroll down to the Licensing &amp; In-app Billing panel.)</li>
  <li>Add the email addresses for the test accounts you want to register,
  separating each account with a comma.</li>
  <li>Click <strong>Save</strong> to save your profile changes.</li>
</ol>

<h3 id="license_key">Getting an app's license key</h3>

<p>The Google Play Developer Console provides a public licensing key for each app. To get the key for an app,
load the app's publishing details in the Developer Console and click the <strong>Settings</strong> icon. The key
for the app is available for copy/paste in License Key for this Application field, as shown in the figure below.</p>

<p>Previously, the Developer Console provided a single public key per developer account. To transition apps to the
new per-app public key, the Developer Console set the app-specific key as the former developer key. This ensures
compatibility for apps that depend on the (former) developer key. </p>

<div style="margin:1em;">
<img style="border:1px solid #ddd;padding-bottom:.5em" src="{@docRoot}images/in-app-billing/billing_app_key.png" xheight="510" id="figure4" />
<p class="img-caption" style="padding-left:.5em;">
  <strong>Figure 4.</strong> You can find the license key for each app in the <strong>Services &amp; APIs</strong> panel.
</p>
</div>

<h2 id="billing-support">Where to Get Support</h2>

<p>If you have questions or encounter problems while implementing In-app Billing, contact the
support resources listed in the following table (see table 2). By directing your queries to the
correct forum, you can get the support you need more quickly.</p>

<p class="table-caption" id="support-table"><strong>Table 2.</strong> Developer support resources
for Google Play In-app Billing.</p>

<table>

<tr>
<th>Support Type</th>
<th>Resource</th>
<th>Range of Topics</th>
</tr>
<tr>
<td rowspan="2">Development and testing issues</td>
<td>Google Groups: <a
href="http://groups.google.com/group/android-developers">android-developers</a> </td>
<td rowspan="2">In-app billing integration questions, user experience ideas, handling of responses,
obfuscating code, IPC, test environment setup.</td>
</tr>
<tr>
<td>Stack Overflow: <a
href="http://stackoverflow.com/questions/tagged/android">http://stackoverflow.com/questions/tagged/
android</a></td>
</tr>
<tr>
<td>Billing issue tracker</td>
<td><a href="http://code.google.com/p/marketbilling/issues/">Billing
project issue tracker</a></td>
<td>Bug and issue reports related specifically to In-app Billing sample code.</td>
</tr>
</table>

<p>For general information about how to post to the groups listed above, see <a
href="{@docRoot}resources/community-groups.html">Developer Forums</a> document in the Resources
tab.</p>