Skip to content

Most visited

Recently visited

navigation

In-app Billing Reference

This documentation provides technical reference information for using the In-app Billing API.

Server Response Codes

The following table lists all of the server response codes that are sent from Google Play to your application. Google Play sends the response code synchronously as an integer mapped to the RESPONSE_CODE key in the response Bundle. Your application must handle all of these response codes.

Table 1. Summary of response codes for In-app Billing API calls.

Response Code Value Description
BILLING_RESPONSE_RESULT_OK 0 Success
BILLING_RESPONSE_RESULT_USER_CANCELED 1 User pressed back or canceled a dialog
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE 2 Network connection is down
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE 3 Billing API version is not supported for the type requested
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE 4 Requested product is not available for purchase
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR 5 Invalid arguments provided to the API. This error can also indicate that the application was not correctly signed or properly set up for In-app Billing in Google Play, or does not have the necessary permissions in its manifest
BILLING_RESPONSE_RESULT_ERROR 6 Fatal error during the API action
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED 7 Failure to purchase since item is already owned
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED 8 Failure to consume since item is not owned

Billing Support API Reference

This section presents methods for obtaining information about the types of in-app billing support that are available for your app.

The isBillingSupported() method

This method indicates whether:

Table 2. isBillingSupported() parameters.

Key Type Description
apiVersion int The version number of the In-app Billing API that your app is using.
packageName String The package name of the app that's calling this method.
type String Value must be inapp for an in-app product or subs for subscriptions.

This method is available in version 3 and later of the in-app billing API.

The isBillingSupportedExtraParams() method

This method is identical to isBillingSupported(), except that you can pass in a fourth argument, a Bundle, that can contain extra parameters.

Table 3. isBillingSupportedExtraParams() parameters.

Key Type Description
apiVersion int The version number of the In-app Billing API that your app is using.
packageName String The package name of the app that's calling this method.
type String Value must be inapp for an in-app product or subs for subscriptions.
extraParams Bundle

A set of extra parameters that further specifies the type of in-app billing that the app supports.

This bundle can contain an optional key called vr that has a boolean value. This flag specifies whether this app supports a virtual reality (VR) purchase flow.

This method is available in version 7 and later of the in-app billing API.

Billing Details API Reference

The In-app Billing API is defined in the IInAppBillingService.aidl file, which is included with the Version 3 sample application.

The getSkuDetails() method

This method returns product details for a list of product IDs. In the response Bundle sent by Google Play, the query results are stored in a String ArrayList mapped to the DETAILS_LIST key. Each String in the details list contains product details for a single product in JSON format. The fields in the JSON string with the product details are summarized in table 4.

Table 4. Description of JSON fields with product item details returned from a getSkuDetails() request.

Key Description
productId The product ID for the product.
type Value must be inapp for an in-app product or subs for subscriptions.
price Formatted price of the item, including its currency sign. The price does not include tax.
price_amount_micros Price in micro-units, where 1,000,000 micro-units equal one unit of the currency. For example, if price is "€7.99", price_amount_micros is "7990000". This value represents the localized, rounded price for a particular currency.
price_currency_code ISO 4217 currency code for price. For example, if price is specified in British pounds sterling, price_currency_code is "GBP".
title Title of the product.
description Description of the product.
subscriptionPeriod Subscription period, specified in ISO 8601 format. For example, P1W equates to one week, P1M equates to one month, P3M equates to three months, P6M equates to six months, and P1Y equates to one year.

Note: Returned only for subscriptions.

freeTrialPeriod Trial period configured in Google Play Console, specified in ISO 8601 format. For example, P7D equates to seven days. To learn more about free trial eligibility, see In-app Subscriptions.

Note: Returned only for subscriptions which have a trial period configured.

introductoryPrice Formatted introductory price of a subscription, including its currency sign, such as €3.99. The price doesn't include tax.

Note: Returned only for subscriptions which have an introductory period configured.

introductoryPriceAmountMicros Introductory price in micro-units. The currency is the same as price_currency_code.

Note: Returned only for subscriptions which have an introductory period configured.

introductoryPricePeriod The billing period of the introductory price, specified in ISO 8601 format.

Note: Returned only for subscriptions which have an introductory period configured.

introductoryPriceCycles The number of subscription billing periods for which the user will be given the introductory price, such as 3.

Note: Returned only for subscriptions which have an introductory period configured.

The getBuyIntent() method

This method returns a response code integer mapped to the RESPONSE_CODE key, and a PendingIntent to launch the purchase flow for the in-app item mapped to the BUY_INTENT key, as described in Implementing In-app Billing. When it receives the PendingIntent, Google Play sends a response Intent with the data for that purchase order. The data that is returned in the response Intent is summarized in table 5.

Note: Instead of using this method, we recommend that you use getBuyIntentExtraParams(), which provides additional functionality.

Table 5. Response data from an In-app Billing purchase request.

Key Description
RESPONSE_CODE Value is 0 if the purchase was success, error otherwise.
INAPP_PURCHASE_DATA A String in JSON format that contains details about the purchase order. See table 6 for a description of the JSON fields.
INAPP_DATA_SIGNATURE String containing the signature of the purchase data that was signed with the private key of the developer. The data signature uses the RSASSA-PKCS1-v1_5 scheme.

Table 6 describes the JSON fields that are returned in the response data for a purchase order.

Table 6. Descriptions of the JSON fields for INAPP_PURCHASE_DATA.

Field Description
autoRenewing Indicates whether the subscription renews automatically. If true, the subscription is active, and will automatically renew on the next billing date. If false, indicates that the user has canceled the subscription. The user has access to subscription content until the next billing date and will lose access at that time unless they re-enable automatic renewal (or manually renew, as described in Manual Renewal). If you offer a grace period, this value remains set to true for all subscriptions, as long as the grace period has not lapsed. The next billing date is extended dynamically every day until the end of the grace period or until the user fixes their payment method.
orderId A unique order identifier for the transaction. This identifier corresponds to the Google payments order ID.
packageName The application package from which the purchase originated.
productId The item's product identifier. Every item has a product ID, which you must specify in the application's product list on the Google Play Console.
purchaseTime The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).
purchaseState The purchase state of the order. It always returns 0 (purchased).
developerPayload A developer-specified string that contains supplemental information about an order. You can specify a value for this field when you make a getBuyIntent request.
purchaseToken A token that uniquely identifies a purchase for a given item and user pair.

The consumePurchase() method

Consume purchase corresponding to the given purchase token. This will result in this item being removed from all subsequent responses to getPurchases() and allow repurchase of items of the same sku.

Table 7. consumePurchase() parameters.

Key Type Description
apiVersion int The version number of the In-app Billing API that your app is using.
packageName String The package name of the app that's calling this method.
purchaseToken String Token in the purchase information JSON that identifies the purchase to be consumed.

This method returns a RESULT_OK(0) of consumption succeeded, and appropriate response codes on failures.

The getBuyIntentToReplaceSkus() method

This method is used to upgrade or downgrade a subscription purchase. The method is similar to getBuyIntent(), except that it takes a list of already-purchased SKUs that are to be replaced with the SKU being purchased. When the user completes the purchase, Google Play swaps out the old SKUs and credits the user with the unused value of their subscription time on a pro-rated basis. Google Play applies this credit to the new subscription, and does not begin billing the user for the new subscription until after the credit is used up.

Note: Instead of using this method, we recommend that you use getBuyIntentExtraParams(), which provides additional functionality.

This method was added with version 5 of the in-app billing API. To verify that the method is reported, send an isBillingSupported AIDL request.

Note: You can only use this method for subscription purchases. If the passed type parameter is anything other than "subs", the method returns BILLING_RESPONSE_RESULT_DEVELOPER_ERROR. Furthermore, the passed SKUs may not include SKUs for seasonal subscriptions.

This method returns a response code integer mapped to the RESPONSE_CODE key, and a PendingIntent to launch the purchase flow for the in-app subscription mapped to the BUY_INTENT key, as described in Implementing In-app Billing. When it receives the PendingIntent, Google Play sends a response Intent with the data for that purchase order. The data that is returned in the response Intent is summarized in table 8.

Table 8. Response data from an In-app Billing Version 5 purchase request.

Key Description
RESPONSE_CODE Value is 0 if the purchase succeeds. If the purchase fails, contains an error code.
INAPP_PURCHASE_DATA A String in JSON format that contains details about the purchase order. See table 6 for a description of the JSON fields.
INAPP_DATA_SIGNATURE String containing the signature of the purchase data that the developer signed with their private key. The data signature uses the RSASSA-PKCS1-v1_5 scheme.

The getBuyIntentExtraParams() method

This method begins a purchase request. The method is a variant of the getBuyIntent() method, and takes an additional extraParams parameter. This parameter is a Bundle of optional keys and values that affect the operation of the method as shown in table 9.

Table 9. getBuyIntentExtraParams() extra parameters.

Key Type Description
skusToReplace List<String> An optional list of SKUs that the user is upgrading or downgrading from. Pass this field if the purchase is upgrading or downgrading existing subscriptions. The specified SKUs are replaced with the SKUs that the user is purchasing. Google Play replaces the specified SKUs at the start of the next billing cycle.
replaceSkusProration boolean

Specifies whether the user should be credited for any unused subscription time on the SKUs they are upgrading or downgrading. If you set this field to true, Google Play swaps out the old SKUs and credits the user with the unused value of their subscription time on a pro-rated basis. Google Play applies this credit to the new subscription, and does not begin billing the user for the new subscription until after the credit is used up.

If you set this field to false, the user does not receive credit for any unused subscription time, and the recurrence date does not change.

Default value is true. Ignored if you do not pass skusToReplace.

accountId String

Optional obfuscated string that is uniquely associated with the user's account in your app. If you pass this value, Google Play can use it to detect irregular activity, such as many devices making purchases on the same account in a short period of time.

Do not use the developer ID or the user's Google ID for this field. In addition, this field should not contain the user's ID in cleartext. We recommend that you use a one-way hash to generate a string from the user's ID, and store the hashed string in this field.

vr boolean

Specifies whether the provided intent represents the beginning of a virtual reality (VR) purchase flow.

Note: In order for this extra parameter to have an effect on your app, you must use the In-app Billing Version 7 API, or a more recent API.

This method is available in version 6 and later of the in-app billing API.

The getPurchases() method

This method returns the current un-consumed products owned by the user, including both purchased items and items acquired by redeeming a promo code. Table 10 lists the response data that is returned in the Bundle.

Table 10. Response data from a getPurchases request.

Key Description
RESPONSE_CODE Value is 0 if the request was successful, error otherwise.
INAPP_PURCHASE_ITEM_LIST StringArrayList containing the list of productIds of purchases from this app.
INAPP_PURCHASE_DATA_LIST StringArrayList containing the details for purchases from this app. See table 6 for the list of detail information stored in each INAPP_PURCHASE_DATA item in the list.
INAPP_DATA_SIGNATURE_LIST StringArrayList containing the signatures of purchases from this app.
INAPP_CONTINUATION_TOKEN String containing a continuation token to retrieve the next set of in-app products owned by the user. This is only set by the Google Play service if the number of products owned by the user is very large. When a continuation token is present in the response, you must make another call to getPurchases and pass in the continuation token that you received. The subsequent getPurchases call returns more purchases and possibly another continuation token.

The getPurchaseHistory() method

This method returns the most recent purchase made by the user for each SKU, even if that purchase is expired, canceled, or consumed. Table 11 lists the response data that is returned in the Bundle:

Table 11. Response data from a getPurchaseHistory request.

Key Description
RESPONSE_CODE Value is 0 if the request was successful, error otherwise.
INAPP_PURCHASE_ITEM_LIST StringArrayList containing the list of productIds of purchases from this app.
INAPP_PURCHASE_DATA_LIST StringArrayList containing the details for recent purchases from this app. See table 12 for the details of the contents of this field.
INAPP_DATA_SIGNATURE_LIST StringArrayList containing the signatures of purchases from this app.
INAPP_CONTINUATION_TOKEN String containing a continuation token to retrieve the next set of in-app products owned by the user. This is only set by the Google Play service if the number of products owned by the user is very large. When a continuation token is present in the response, you must make another call to getPurchases and pass in the continuation token that you received. The subsequent getPurchases call returns more purchases and possibly another continuation token.

Table 12. Descriptions of the JSON fields for the purchase history returned by getPurchaseHistory().

Field Description
productId The item's product identifier. Every item has a product ID, which you must specify in the application's product list on the Google Play Console.
purchaseTime The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).
developerPayload A developer-specified string that contains supplemental information about an order. You can specify a value for this field when you make a getBuyIntent request.
purchaseToken A token that uniquely identifies a purchase for a given item and user pair.

Note: The getPurchaseHistory() method has higher overhead than getPurchases(), because it requires a call to the Google Play server. You should use getPurchases() if you do not actually need the user's purchase history.

This method is available in version 6 and later of the in-app billing API.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)