About the Android IAP package
Thecom.amazon.device.iap package provides classes and an interface that you use to implement In-App Purchasing in your Android app.
This package contains the following primary interface and classes:
- : Class that receives broadcast intents from the Amazon Appstore.
- : Class that initiates requests through the Amazon Appstore.
- : Interface that receives asynchronous responses to the requests initiated by .
| PurchasingService method | PurchasingListener callback | Response object |
|---|---|---|
| None | None | |
| None | None |
Manifest requirements
If you want to use the In-App Purchasing API and your app targets Android API level 30 or higher, you must define the list of packages your app needs to query in the AndroidManifest.xml file. To be able to query Amazon App Tester and Amazon Appstore, add the following code to your manifest file.ResponseReceiver class. For details, see ResponseReceiver.
ResponseReceiver
The In-App Purchasing API performs all of its activities in an asynchronous manner. Your app needs to receive broadcast intents from the Amazon Appstore via the class. This class is never used directly in your app, but for your app to receive intents, you must add an entry for the to your manifest. The following code example shows how to add a to the AndroidManifest.xml file for the Appstore SDK. If your app targets Android 12 or higher, you must explicitly setandroid:exported to true in the MainActivity and .
PurchasingService
Use the class to retrieve information, make purchases, and notify Amazon about the fulfillment of a purchase. implements methods below. You must implement each method for your callbacks to work:- : This method is the mechanism through which callbacks occur. Call before calling other methods in the class. The object allows your app to listen for and process the callbacks triggered by the . Call in the
onCreate()method in the main UI thread of your app. - : Call this method to retrieve the app-specific ID, marketplace, and the country code of the country of residence for the user who is currently signed in. For example, if a user switched accounts or if multiple users accessed your app on the same device, this call helps you make sure that the receipts that you retrieve are for the current user account. Call in the
onResume()method. - : retrieves all Subscription and Entitlement purchases across all devices. A consumable purchase can be retrieved only from the device where it was purchased. retrieves only unfulfilled and canceled consumable purchases. Amazon recommends that you persist the returned data and query the system only for updates. The response is paginated. Call in the
onResume()method. - : Call this method to retrieve item data for a set of SKUs to display in your app. Call in the
onResume()method. - : Call this method to initiate a purchase of a particular SKU.
- : Call this method to send the of the specified
receiptId. Possible values for are: , , , . - : Call this method to enable the Pending Purchase feature, for kids and parents, in your app. When the value is , the purchase is not yet approved. Do not grant the entitlement to the customer if the status is pending. If the purchase is approved, it’s processed in the usual way when you call in the
onResume()method. For more details, see Implement Pending Purchases.
PurchasingListener
Implement the interface to process asynchronous callbacks. Because your UI thread invokes these callbacks, do not process long-running tasks in the UI thread. Your instance of should implement the following required methods:- : Invoked after a call to . Determines the user ID, marketplace, and country code (of the country of residence) of the currently signed-in user. Also provides the consent status of the user for Quick Subscribe.
- : Invoked after a call to . Retrieves the purchase history. Amazon recommends that you persist the returned data and query the system only for updates.
- : Invoked after a call to . Retrieves information about SKUs you would like to sell from your app. Use the valid SKUs from the object.
- : Invoked after a call to . Used to determine the status of a purchase.
Response objects
Every call you initiate via the results in a corresponding response received by the . Each of these responses uses a response object:- : Provides the app-specific user ID, marketplace, and country code (of the country of residence) for the currently signed-in user. Also provides the consent status of the user for Quick Subscribe.
- : Provides a paginated list of receipts. Receipts are unordered.
- : Provides item data, keyed by SKU. The method lists any SKUs that are unavailable.
- : Provides the status of a purchase initiated within your app. Note that a result of can simply mean that the user canceled the purchase before completion.
Integrate the IAP API with your app
Now that you understand a bit more about the classes that you need to implement IAP, you can start writing the IAP code in your app. The code snippets in this section are from the Consumable IAP sample app, included with the SDK.1. Create placeholder methods
To organize your code, use placeholders or stubbed out code snippets to call the following methods in the following places:- Call in your
onCreate()method. - Call in your
onResume()method. - Call in your
onResume()method. - Call in your
onResume()method.
onCreate() method of the app’s main activity. Invoke the other three methods in the onResume() method of the app’s home activity (the primary activity used by the app). These four calls, which are part of the class, provide the foundation for executing an in-app purchase. The steps that follow go into more detail about how to implement these calls and provide sample code snippets that you can use to model your code.
2. Implement and register PurchasingListener
Implement and register in theonCreate() method so that your app can listen for and process the callbacks triggered by the .
The code snippet below performs the following tasks:
- (Required) Registers the .
-
(Optional) Creates a new
SampleIapManagerinstance to store data related to purchase receipts. This is an optional step; however, your app should store purchase receipt data somewhere where you can access it. Whether you choose to use a database or to store that data in memory is your decision. -
(Optional) Checks if the app is running in sandbox mode. If you’re using the Appstore SDK and have implemented a for DRM, use the getAppstoreSDKMode method from the class. If you’re using IAP v2.0 check for sandbox mode with the
PurchasingService.IS_SANDBOX_MODEflag. This flag can be useful when your app is in development, and you’re using the App Tester to locally test your app. - (Optional) Enables pending purchases. This feature allows a child within Amazon Kids to request an in-app purchase and have a parent approve or decline it. The purchase will be in a pending state while waiting for the parent’s response. For instructions on how to set up pending purchases, see Implement Pending Purchases.
3. Get user information
Retrieve information (user ID, marketplace, and country code of the country of residence) about the current user by implementing inonResume().
4. Implement getPurchaseUpdates method
The method retrieves all purchase transactions by a user since the last time the method was called. Call in theonResume() method to make sure you are getting the latest updates.
The method takes a boolean parameter called reset. Set the value to true or false depending on how much information you want to retrieve:
-
false- Returns response of purchase history since the last call to . Purchase types have the following behavior:- Entitlements – If your app uses Pending Purchases, Appstore returns all unfulfilled entitlement receipts until your app calls and sends a fulfillment result of . Otherwise, Appstore returns all new transactions since the last time the method was called.
- Consumables – Appstore returns all unfulfilled consumable receipts until your app sends a fulfillment result of .
- Subscriptions – Appstore returns only the new receipts that your app hasn’t sent a fulfillment result for. These receipts appear in every
getPurchaseUpdates(false)call until your app acknowledges the receipts by sending a fulfillment result.
-
true- Retrieves a user’s entire purchase history. You need to store the data somewhere, such as in a server-side data cache or to hold everything in memory. Usetruewhen you require a full list of a user’s purchases, such as when a customer wants to restore a purchase, or you’ve detected a consistency issue between your app and the Appstore.
getPurchaseUpdates responses
You receive a response from in most scenarios. Responses are sent in the following cases:- Subscriptions and entitlements: You always receive a receipt for subscription and entitlement purchases.
- Consumables: If a consumable transaction is successful, and you notify Amazon of the fulfillment (by calling ), you receive a receipt in but won’t receive a receipt from . In all other cases, you receive a receipt for consumables. The method only returns fulfilled consumable purchases in rare cases, such as if an app crashes after fulfillment but before Amazon is notified, or if an issue occurs on Amazon’s end after fulfillment. In these cases, you would need to remove the duplicate receipts so as not to over fulfill the item. When you deliver an item, record somewhere that you have done so, and do not deliver again even if you receive a second receipt.
- Canceled purchases: You receive a receipt for canceled purchases of any type (subscription, entitlement, or consumable).
Handle the response of getPurchaseUpdates
Next, you need to handle the response. When the callback is triggered, check the request status returned by . If is , process each receipt. You can use the method to retrieve details about the receipts. To handle pagination, get the value for . If returns true, make a recursive call to , as shown in the following sample code:Process the receipts
Process the receipts. Call theSampleIapManager.handleReceipt() method to handle all receipts returned as part of the .
5. Implement getProductData method
Also in youronResume() method, call . This method validates your SKUs so that a user’s purchase does not accidentally fail due to an invalid SKU.
The following sample code validates the SKUs for an app’s consumable, entitlement, and subscription items with Amazon:
Successful request
If the is , retrieve the product data map keyed by the SKU displayed in the app. If is but has unavailable SKUs, call to retrieve the product data for the invalid SKUs and prevent your app’s users from being able to purchase these products. If you want to display the IAP icon within your app, you must edit your AndroidManifest.xml file to include theandroid.permission.INTERNET permission.
The product data map contains the following values:
| Field | Data Type | Description |
|---|---|---|
sku | String | Stock-keeping unit (SKU) of the product. |
title | String | Localized title of the product. |
description | String | Localized description of the product. |
smallIconUrl | String | Small icon URL for the product. |
productType | String | Type of product. Valid values: CONSUMABLE, ENTITLED, SUBSCRIPTION. |
coinsRewardAmount | int | No longer supported. Amazon Coins was discontinued on August 20, 2025. |
freeTrialPeriod | String | Free trial period of the subscription term. Returned only if a free trial is configured and the customer is eligible. |
subscriptionPeriod | String | Period of the subscription term for the SKU. Returned only for term SKUs. Valid values: Weekly, BiWeekly, Monthly, BiMonthly, Quarterly, SemiAnnual, Annual. |
promotions | List<Promotion> | Details of the promotion the customer is eligible for. Returned only for term SKUs. See the following table for details on the Promotion object. For how to set up promotional pricing, see Set Up Promotional Pricing. |
price | String | Localized price of the product (on the child SKU for subscription items). |
addons | List<String> | List of add-on subscription term SKUs eligible for a given base subscription term SKU. |
bases | List<String> | List of base subscription term SKUs associated with a given add-on subscription term SKU. |
Promotion object contains the following fields:
| Field | Data Type | Description |
|---|---|---|
promotionType | String | Type of the promotion. Valid value: |
promotionPlans | List<PromotionalPlan> | Details about price and billing cycles of the promotion. See the following table for details on the PromotionalPlan object. |
PromotionalPlan object has the following fields:
| Field | Data Type | Description |
|---|---|---|
promotionPrice | String | Price of the term SKU during the promotion period in localized format. |
promotionPricePeriod | String | Duration of each billing cycle of the promotion. Valid values: Weekly, BiWeekly, Monthly, BiMonthly, Quarterly, SemiAnnual, Annual. |
promotionPriceCycles | int | Number of billing cycles. |
Open/Close product data map examples
Open/Close product data map examples
Failed request
If is , disable IAP functionality in your app as shown in the following sample code:6. Implement code to make a purchase
Write the code to make a purchase. While this particular example makes the purchase of a consumable, you should be able to use similar code for subscriptions and entitlements, as well. The following code from the consumable sample app’sMainActivity class calls to initialize a purchase. In the sample app, this method runs when an app user taps the Buy Orange button:
SamplePurchasingListener.onPurchaseResponse() callback. In this snippet SampleIapManager.handleReceipt() handles the actual purchase:
7. Process the purchase receipt and fulfill the purchase
You can now process the purchase receipt and, if the receipt is verified, fulfill the purchase. When designing your own app, keep in mind that you will likely implement some sort of fulfillment engine to handle these steps all in one place. Verify the receipts from the purchase by having your back-end server verify thereceiptId with Amazon’s Receipt Verification Service (RVS) before fulfilling the item. Amazon provides an RVS Sandbox environment and an RVS production environment. See the Receipt Verification Service (RVS) documentation to learn how to set up both the RVS Sandbox and your server to work with RVS:
- During development, use the RVS Sandbox environment to verify receipts generated by App Tester.
- In production, use the RVS production endpoint.
handlePurchase() method checks whether the receipt is canceled.
- If the receipt is canceled and the item was previously fulfilled, call the
revokePurchase()method to revoke the purchase. - If the customer already has access to the content because they made the purchase outside of Amazon, call
cancelPurchase()to notify Amazon that purchase cannot be fulfilled. - If the receipt is not canceled, verify the receipt from your server using RVS, then call
grantPurchase()to fulfill the purchase.
Guidelines for subscription purchases
If the purchasable item is a subscription, keep the following guidelines in mind with regards to the value ofreceiptId.
- If the subscription is continuous and has never been canceled at any point, the app will only receive one receipt for that subscription/customer.
- If the subscription was not continuous, for example, the customer did not auto-renew, let the subscription lapse, and then subscribed again a month later, the app will receive multiple receipts.
8. Send fulfillment result to Amazon and grant item to the user
When you send a fulfillment result, you ensure that Amazon can confirm whether users can access the content that they paid for. Always communicate the fulfillment result to Amazon. Use the method to send a . When you send a fulfillment result, Appstore no longer tries to send the purchase receipt to the app. The following table lists the conditions under which you send each fulfillment result.| Fulfillment result | Condition to send |
|---|---|
| The customer has successfully created their account and can access content on your service. | |
| The customer already has an existing account and subscription for your service. | |
| The customer is not eligible to sign up for an account for your service. | |
| For any other reason you can’t fulfill the order. |

