In-app billing frees you from processing financial transactions, but you still need to perform a few administrative tasks. These tasks include the following:
To register a test account, you must have a Google Play publisher account. 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. If you don't have a publisher account, you can register as a Google Play developer and set up a publisher account through the Google Play Developer Console.
If you want to create a product list and issue refunds to your users, you must have a Google payments merchant account. If you don't have a merchant account, you can register for one through the Developer Console.
The Google Play Developer Console provides a product list for each of your published apps. You can sell an item using Google Play's in-app billing feature only if the item is listed on an app's product list. Each app has its own product list; you cannot sell items that appear on another app's product list.
You can access an app's product list by opening the In-app Products
page for an app that is listed in your developer account. The link to the
In-app Products page appears only if you have a Google payments merchant
account and the app's manifest includes the
com.android.vending.BILLING permission. For more information about this
permission, see
Updating Your App's Manifest.
A product list specifies items you are selling in an app: in-app products, subscriptions, or a combination of both. For each item, the product list contains information such as product ID, product description, and price. You can create a product list for any published app, including apps published to the alpha and beta channels.
The product list stores only metadata about the items you are selling in your app. It does not store any digital content. You are responsible for storing and delivering the digital content that you sell in your apps.
Note: Previously, you could test an app by uploading an unpublished draft version. This functionality is no longer supported; instead, you must publish it to the alpha or beta distribution channel. For more information, see Draft Apps are No Longer Supported.
In addition, an app package can have only one product list. If you create a product list for an app, and you use the multiple APK feature to distribute more than one APK for that app, the product list applies to all APK versions that are associated with the app listing. You cannot create individual product lists for each APK if you are using the multiple APK feature.
You can add items to a product list two ways: you can add items one at a time on the In-app Products page, 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 app 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 app has a large number of in-app items.
Note: Batch upload of product lists containing subscriptions is not supported. Also, when updating existing items in a batch upload, you cannot include changes to in-app products that are linked to a pricing template.
To add an item to a product list using the Developer Console UI, follow these steps:
Click Add new product. After you provide the product type and ID for the item you are selling, click Continue.
The product type can be "Managed product" or "Subscription." You cannot change an item's product type after you create the item. For more information, see Choosing a Product Type.
Note: For subscription items, you cannot change the item's price once you have published the item.
Product IDs are unique across an app's namespace. A product ID must start with a
lowercase letter or a number and must be composed of only lowercase letters (a-z), numbers
(0-9), underscores (_), and periods (.). The product ID android.test is reserved, as are all
product IDs that start with android.test.
Note: Be sure to plan your product ID namespace carefully. You cannot modify an item's product ID after the item is created, and you cannot reuse a product ID within an app.
Enter additional information about the item. If you're adding a subscription, also include subscription-specific details. After you've provided this information, click Save.
An item's publishing state can be Active or Inactive. To be visible to a user during checkout, an item's publishing state must be set to Active, and the item's app must be published on Google Play.
Note: If you're using a test account, users can see active items within unpublished apps, as well. For more information, see Testing In-app Billing.
By default, in-app products inherit their default language from the parent app.
You can provide localized titles and descriptions for your in-app products by selecting Add Translations. If you want Google Play to translate your title and description for you, based on the title and description in the default language, just choose the languages that you want to offer. You can also provide custom translations in specific languages.
Provide a price in your home currency, or link the price to an existing pricing template. Based on the price you enter or the prices from the pricing template, the system autofills country-specific prices for different currencies. These generated prices use current exchange rates and locally relevant pricing patterns (see figure 1).
You can also change prices for other currencies manually, but you can do this only if a currency is used in one of the target countries for your app. You can specify target countries for your app on the Pricing & Distribution page in the Google Play Developer Console.
When you add a subscription to a product list, you must define its billing period. All other settings related to subscriptions are optional. The following list shows each property that you can set:
Sets the frequency at which a user is charged while their subscription is active.
If the billing period for the new subscription is Seasonal, you must specify when the season starts and ends using the Start date and End date options. The subscription is active only between these two dates.
To allow users to activate a seasonal subscription for a discounted price after the season begins, you can provide prorated pricing by selecting Add Prorated Price. In the text boxes that appear after you select this option, specify a discounted price for your subscription, as well as the first date during the season when users can activate the subscription for the discounted price. You can set multiple prorated prices for a single subscription, with each price point taking effect on a different start date.
Note: After you activate a subscription, you cannot change the subscription's billing period. For a seasonal subscription, this restriction means that you also cannot change the season's start and end dates. However, you can still add, change, and remove the prorated prices that you've associated with a seasonal subscription.
To learn more about how you can manage subscriptions using the In-app Billing service, see the In-app Subscriptions guide.
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 options that you set when adding in-app products to a product list using the Google Play Developer Console UI. For more information about using this UI, see Adding items one at a time to a product list.
Note: Batch upload of in-app product lists containing subscriptions is not supported. Also, when updating existing items in a batch upload, you cannot include changes to in-app products that are linked to a pricing template.
To import the in-app products that are specified in your CSV file, do the following:
On the In-app Products page, click Import/Export > Import in-app products from CSV file to open the Import In-app Products dialog.
If you want to overwrite existing in-app products in your product list during the import process, select the Overwrite existing products checkbox.
This option overwrites values of existing items only if the value of the
Product ID in the CSV file matches the in-app product ID for
an existing in-app product in the product list. The overwriting process
doesn't delete in-app products that exist in a product list but aren't
included in the CSV file
Note: If you choose not to overwrite
existing items, the Product ID given to each item in the CSV
file must be different from any of the Product ID values
assigned to existing in-app products.
You can also export an existing product list to a CSV file by clicking Import/Export > Export in-app products to CSV file on the In-app Products page. This is useful if you have used the UI to add in-app products to your app but you want to start managing the product list through a CSV file instead.
The CSV file uses commas (,) and semicolons (;) to
separate data values. Commas are used to separate primary data values, and
semicolons are used to separate subvalues. Each item must appear entirely on a
single line within the CSV file.
When creating a CSV file that represents a list of items, you must specify the CSV syntax on the first row, followed by the items themselves on subsequent rows, as shown in the following example:
Product ID,Published State,Purchase Type,Auto Translate,Locale; Title; Description,Auto Fill Prices,Price,Pricing Template ID basic_sleeping_potion,published,managed_by_android,false,en_US; Basic Sleeping Potion; Puts small creatures to sleep.; es_ES; Poción básica de dormir; Causa las criaturas pequeñas ir a dormir.,false,,4637138456024710495 standard_sleeping_potion,published,managed_by_android,false,en_US; Standard Sleeping Potion; Puts all creatures to sleep for 2 minutes.,true, 1990000, invisibility_potion,published,managed_by_android,false,en_US; Invisibility Potion; Invisible to all enemies for 5 minutes.,false, US; 1990000; BR; 6990000; RU; 129000000; IN; 130000000; ID; 27000000000; MX; 37000000;
This example contains details for three items, each of which represents an in-app product:
en_US
and es_ES locales. A pricing template defines the item's
price.
Each row in a CSV file can contain the following values, though at least one of these values is undefined in each row:
Product IDSetting this value in the CSV file has the same effect as entering a Product ID when creating a new in-app product.
If you specify a Product ID assigned to an in-app product that already
exists in a product list, and you've checked the Overwrite
existing products checkbox in the Import In-app Products
dialog, the data for the existing in-app product is overwritten with the
values that you specify in the CSV file.
Publish State
This value must be set to published
or unpublished.
Setting this value to published has the same effect as
navigating to an item's Managed Product Details page and choosing
Active in the drop-down list next to the in-app product's
title and product ID. Setting the value to unpublished
has the same effect as choosing Inactive in the same
drop-down list.
Purchase Type
This value must be set to managed_by_android because batch
upload of product lists containing subscriptions is not supported.
Setting this value to managed_by_android has the same effect
as selecting Managed product in the Add New
Product dialog when creating an in-app product.
Auto Translate
This value must be set to false because auto-translation of
in-app product details isn't supported.
If you want to provide translations of an in-app product's title and
description, you need to specify these translations explicitly within the
Locale value.
Locale, Title, and DescriptionIf you include only one locale for an item, you must specify your app's default locale and the item's default title and description:
app_default_locale; item_default_title; item_default_description;
Setting these values has the same effect as performing the following sequence of actions:
When setting the Locale value, you can use any of the
language codes that appear within the Add Your Own Translations
dialog. You can access this dialog by navigating to an in-app product's
Managed Product Details page and clicking Add
translations or Manage translations.
Note: When specifying the Title and
Description values, use backslashes to escape the semicolon
(\;) and backslash (\\) characters.
If you want to include translated versions of the item's title and
description, you must list the default locale, title, and description,
followed by the locales, titles, and descriptions for each translation.
In the following example, the in-app product uses en_US
(United States English) as the default locale and es_ES
(Spain Spanish) as a translation:
en_US; Invisibility Cloak; Makes you invisible.; es_ES; Capote Invisible; Se vuelven invisible.
Note: An app contains a single default language, but each
in-app product maintains its own list of translations. Therefore, although
the first locale in each item's Locale value must be the same
throughout the CSV file, the other locales can differ from one item to
another.
Providing values for multiple translations has the same effect as performing the following sequence of actions:
Auto Fill Prices, Country, and
Price
You can set Auto Fill Prices to true or
false.
If an in-app product uses a pricing
template, you should set Auto Fill Prices to
false, and you shouldn't set a value for the
Price.
Note: When you specify an item's price in a CSV file, you provide a price in micro-units, where 1,000,000 micro-units is equivalent to 1 unit of real currency.
The following sections describe how the value of
Auto Fill Prices affects the syntax and meaning of the
Country and Price values.
If you set Auto Fill Prices to true, you specify
only the item's default price; you don't include a Country
value. Setting Auto Fill Prices to true has the
same effect as performing the following sequence of actions:
For example, under the following conditions:
en_US.
...you'd set the values of Auto Fill Prices and
Price at the end of a row in the CSV file as follows:
true,1990000,
If you set Auto Fill Prices to false instead,
you specify a series of Country and Price
values for all countries where you distribute your app, including the country corresponding to your app's default locale.
Each Country value is the two-letter uppercase ISO country
code that represents a country where your app is distributed.
Note: You must provide a country code and price for each country that your app is targeting. To view and edit the list of countries that your app targets, open your app's Pricing & Distribution page.
Each Price value represents the cost of the item in
micro-units of the currency used in that country. Setting Auto Fill
Prices to false has the same effect as performing
the following sequence of actions:
For example, if you're offering your app for the following prices (all taxes included) in other countries:
...you'd set the values of Auto Fill Prices,
Country, and Price at the end of a row in the
CSV file as follows:
false, BR; 6990000; RU; 129000000; IN; 130000000; ID; 27000000000; MX; 37000000;
Pricing Template ID
If an item is linked to a pricing template, you should set Auto Fill
Prices to false, and you shouldn't set a value for the
Price column. If the item isn't linked to a pricing template,
you shouldn't set a value for the Pricing Template ID; instead,
you should set Auto Fill Prices, Country, and
Price based on how you want to set the in-app product's prices.
Setting this value has the same effect as navigating to an in-app product's Managed Product Details page and linking the product's price to the pricing template that has the same pricing template ID as the one specified in the CSV file. This pricing template ID appears underneath a pricing template's name on the Pricing template page.
If you import a CSV file, and you've checked the Overwrite existing
products checkbox in the Import In-app Products dialog,
you can update the links between in-app products and pricing templates. To
link the product to a specific pricing template, set the Pricing
Template ID value to that pricing template's ID. To unlink an in-app
product from all pricing templates, don't set a value for its Pricing
Template ID.
You can link up to 100 app prices or in-app product prices to a particular
pricing template. Therefore, don't specify the same Pricing Template
ID value in more than 100 rows of a CSV file.
If you sell multiple apps at the same price, or if you sell multiple in-app products at the same price across one or more apps, you can add pricing templates. These templates make it easier to manage shared prices.
When creating a pricing template, you provide new pricing information that you can apply to paid apps and in-app products. You can link the prices of up to 100 apps and in-app products to a single pricing template.
To add a pricing template, do the following:
If you are adding your first pricing template, the Add a Pricing Template banner appears. Select Add template to create a new template. The new template's Pricing tab appears.
Otherwise, you see a list of your pricing templates. Select New pricing template. The new template's Pricing tab appears.
Provide details about the template. These details include the name, the price, and whether to include tax as part of your country-specific prices.
Based on the price and tax option you provide, the Developer Console generates prices for international currencies using current exchange rates and country-specific pricing patterns.
You can create links between pricing templates and sets of paid apps and in-app products that share the same price. After completing this linking process, any changes you make to the pricing template are applied to the prices of items that you've linked to the template. To complete the linking process, use either the pricing template's Linked Items tab or the Price section within a paid app or in-app product's pricing page.
Note: Since a subscription within your app has a constant price, you cannot link a subscription with a pricing template. You can, however, import the prices from a pricing template and apply them to a new subscription.
To link a pricing template to an in-app product, do the following:
To link a pricing template to the price of a paid app, you follow a similar process. On the pricing template's Linked Items tab, choose a paid app in the Link Paid Apps section.
To link an in-app product to a pricing template, do the following:
To link the price of a paid app to a pricing template, you follow a similar process on the app's Pricing & Distribution page.
As your app evolves, you may find it useful to remove older versions of in-app products or unpublish paid apps, some of which may be linked to pricing templates. To delete an in-app product or unpublish a paid app that is linked to a pricing template, complete the following steps. You don't need to unlink the in-app product or paid app from the pricing template beforehand.
To delete an in-app product that is linked to a template, do the following:
To unpublish a paid app that is already published and is linked to a template, do the following:
If you no longer need a pricing template, you can delete it by completing the following steps:
An item's product type controls how Google Play manages the purchase of the item. The supported product types include "managed product" and "subscription." Since support for different product types can vary among versions of the In-app Billing API, make sure that you choose a product type that's valid for the version of the In-app Billing API that your app uses.
For details, refer to the documentation for the In-app Billing API.
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 app developer). You can then process the refund through your Google payments merchant account. When you do this, Google Play receives a refund notification from Google payments, and Google Play sends a refund message to your app. For more information, see Handling IN_APP_NOTIFY messages and In-app Billing Pricing.
Important: You cannot use the API to issue refunds or cancel In-app Billing transactions. You must do this manually through your Google payments merchant account. However, you can use the API to retrieve order information.
When a user purchases an in-app item, Google 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
orderId field of the PURCHASE_STATE_CHANGED
intent.
Note: When a user completes a test purchase, the
orderId field remains blank. To track test transactions, use
the purchaseToken field instead. For more information about
working with test purchases, see Testing In-app
Billing.
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.
The order number itself is a string consisting of numbers only, with a format assigned and managed by Google.
For transactions dated 5 December 2012 or later, Google payments assigns a
Merchant Order Number (rather than a Google Order Number) and reports the Merchant
Order Number as the value of orderID. Here's an
example:
"orderId" : "GPA.1234-5678-9012-34567"
For transactions dated previous to 5 December 2012, Google checkout assigned
a Google Order Number and reported that number as the value of
orderID. Here's an example of an orderID holding a
Google Order Number:
"orderId" : "556515565155651"
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 apps that you have uploaded to the Google Play Developer Console but have not yet published.
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 apps 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.
Test accounts have three limitations:
To add test accounts to your publisher account, follow these steps:
The Google Play Developer Console provides a public licensing key for each app.
To locate the key for an app, follow these steps:
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 sets the app-specific key as the former developer key. This ensures compatibility for apps that depend on the (former) developer key.
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.
Table 2. Developer support resources for Google Play In-app Billing.
| Support Type | Resource | Range of Topics |
|---|---|---|
| Development and testing issues | Google Groups: android-developers | In-app billing integration questions, user experience ideas, handling of responses, obfuscating code, IPC, test environment setup. |
| Stack Overflow: http://stackoverflow.com/questions/tagged/ android | ||
| Billing issue tracker | Billing project issue tracker | Bug and issue reports related specifically to In-app Billing sample code. |
For general information about how to post to the groups listed above, see Developer Forums document in the Resources tab.