This page contains answers to Frequently Asked Questions (FAQs) relating to the In-App Purchasing (IAP) API (v1.0 and v2.0).
- General Questions
- IAP API Questions
- Subscription Item Questions
- Testing Questions
- Amazon Appstore and Submission Process Questions
Q: What does “IAP” stand for?
A: “IAP” is the abbreviation for Amazon’s In-App Purchasing feature.
Q: What do customers need to complete in-app purchases?
A: Customer requirements for in-app purchases are the same as those for the Amazon client app:
- The Amazon client app must be installed on the user’s device.
- The customer account must have 1-Click Payment enabled.
- 1-Click Payment must be linked to a credit card from one of the supported countries.
- The default address for 1-Click Payment must be a valid address in one of the supported countries.
See the In-App Purchase requirements.
Q: Does the IAP API provide any protection against users accidentally repeating purchases?
A: No. Amazon policy is that refunds are not available for digital goods. If a user has a valid reason for a refund (for example, if the app is not compatible with their device), they should contact Amazon customer service through the Contact Us link on the Help & Customer Service page at Amazon.com.
Q: Can I link directly to the Amazon Client from within an app?
A: Yes. For information about how to link from an app to the Amazon Client, see Linking to the Amazon Client.
Q: How do I get started with the In-App Purchasing API?
A: With the In-App Purchasing API, you can offer digital content and subscriptions—such as in-game currency, expansion packs, upgrades, and magazine issues—for purchase within apps.
Q: How can I make in-app purchasing work on Amazon devices?
A: Amazon’s In-App Purchasing API is compatible with Amazon devices.
Q: Do I have to use the Amazon In-App Purchasing API for digital purchases within my app?
A: To make the app available on Amazon devices, the app must use the Amazon In-App Purchasing API for all eligible purchases.
Q: My app uses Google’s in-app purchasing technology. Can I make it work on Amazon devices?
A: Google’s in-app purchasing technology requires access to Google Mobile Services, which do not work on Amazon devices. Amazon offers an In-App Purchasing API that makes it easy for you to offer digital content and subscriptions for purchase within your apps.
Q: What is the revenue split with Amazon on in-app purchases?
A: Amazon pays developers 70% of the marketplace list price.
Q: How do I make my in-app purchasable items available in all countries?
A: Your in-app purchasable items are automatically available wherever your app is available now, or will be available in the future. By default, Amazon automatically converts the base list price of your IAP items into the local currency of each marketplace where they can be sold, and customers will see IAP items in English.
Q: What should I do if I do not want my in-app purchasable items sold on a particular marketplace?
A: You must specify that the app itself is not available in that specific marketplace. Sign in to the developer portal and go to the My Apps tab. Once there, select the app and click the Availability and Pricing tab. On this tab, clear the check box next to the marketplace in which you do not want your app sold.
Q: How do I change the prices of my IAP items in individual marketplaces?
A: Sign in to the developer portal and go to My Apps. Select an app, click In-App Items, and then click the Availability and Pricing tab. On that tab, select the radio button for I’ll set my own list prices, which exposes the option to edit the marketplace list prices by currency and marketplace.
Q: Do you support parental controls for in-app purchasing?
A: Customers can require their Amazon password or a 4-digit PIN to complete in-app purchases. This setting is found under the Settings menu on the Amazon Apps storefront.
Q: What can be sold by using the In-App Purchasing API, and what is prohibited?
A: You can enable customers to buy digital products, content, or services—such as additional or enhanced functionality, in-app tools, data, or media content—intended to be accessed or used within an app.
You may not allow customers to purchase any other item, including:
- Any goods or services that are to be used outside of the app itself (other than digital content accessible both inside and outside your app)
- Any currency, credits, points, or other items or units that can be transferred from an end user to others and/or circulated as a medium of exchange
- A prepaid account that creates cash balances that end users can use to purchase additional in-app products
- Any gift cards
- Any lottery tickets
- Any event tickets, such as sporting event tickets or concert tickets
- Any illegal and potentially illegal products
- Any government documents, identification, birth certificates, passports, and licenses
- Any unauthorized and unlicensed products
- Any content that violates the Amazon Appstore Content Policy Requirements
- Any items that infringe upon an end user’s privacy
- Any insurance product
- Any listings for warranties and other similar offerings
- Any product or service that is regulated by a government entity
Q: Are there any additional requirements that apply to my use of in-app purchasing?
A: Yes. In addition to complying with our program policies on the types of in-app items you can offer, you must ensure that in-app purchasing in your app complies with all applicable laws. Some of these laws limit how you can promote your in-app items. For instance, consumer protection laws in the European Union prohibit direct exhortations to children to buy items. They may also restrict how the purchase of in-app items can impact the functionality of your app. Two references that can help you understand how EU consumer protection laws apply to in-app purchasing are the EU Consumer Protection Cooperation (CPC) Network’s position and the UK Competition and Markets Authority’s Principles for online and app-based games.
IAP API Questions
Q: Are the receipts returned by
A: No. The receipts returned are not guaranteed to be sorted. You can have your app sort the receipts.
Q: What if a purchase transaction is interrupted before the response is received?
A: If there is an interruption in power or the network connection is dropped before the response is received, the Amazon server adds the purchase response to a queue. When the power and the network connection are restored, the Amazon client can retrieve the purchase responses from the queue. Check for the purchase receipts sent from the Amazon client by sending a
getPurchaseUpdates() call each time the app starts. The behaviors for queued receipts varies slightly depending on the purchase type and whether you are using IAP v1.0 or v2.0.
- For IAP v1.0:
- For Consumables, the purchase responses are queued up on the Amazon servers for retrieval by the Amazon client. When the Amazon client is capable, it will automatically retrieve the response and send it to the application.
- For Entitlements and Subscriptions, your app should retrieve the receipt data through the
PurchaseUpdateRequest()call the next time that the app starts. Because purchase responses are implemented in an asynchronous manner, your app should handle them as such to avoid errors.
- For IAP v2.0:
- For Consumables, the purchase receipt is only listed in the
notifyFulfillment()was not called for that receipt. If the receipt is already fulfilled, Amazon treats the consumable purchase transaction as completed and does not deliver the receipt in the next call to
- For Entitlements and Subscriptions, the purchase receipt is listed in the
onPurchaseUpdatesResponse(). If the purchase receipt is canceled or expired, the receipt has a valid
- For Consumables, the purchase receipt is only listed in the
Q: What are the recommended values for the string lengths of
PurchaseToken, ReceiptId, and
A:These parameters have the following recommended lengths if you are defining space for them in a database:
UserId(IAP v1.0, 2.0): Use 128 characters for the
UserId.The string can include alphanumeric values and punctuation. Because
UserIdis an encrypted string, its length can be influenced by your encryption technique.
PurchaseTokenhas a value of 512 characters.
ReceiptId(v2.0): Use 200 characters for the
ReceiptId.The string can include alphanumeric values and punctuation.
marketplacevalue adheres to the ISO 3166-1-alpha-2 standard, which represents country names with two letters. The actual
marketplacevalue can be
nullfor older version of the Amazon Appstore.
Q: Is the
notifyFulfillment() call required (IAP v2.0)?
A: Yes, the
notifyFulfillment() call is required for all three types of in-app purchases. This call tracks the status of the purchase.
Note that for Consumable purchases, call
notifyFufillment() after fulfilling the purchase. If you do not call
notifyFulfillment(), the Amazon client keeps sending consumable purchase receipts as part of
onPurchaseUpdatesResponse() because in this case Amazon, assumes that the customer has not received their purchase.
Subscription Item Questions
Q: Can users manage subscriptions from their mobile devices?
A: Yes. Users can manage their subscriptions through both the Amazon client and the Amazon website.
Q: Is there a way for my app to determine if a customer has enabled the auto-renew option?
A: No. The IAP API does not include any methods to determine whether a user has auto-renew enabled or disabled.
Q: When a customer purchases a subscription with a free trial, is the free trial period part of the subscription term or is it in addition to the subscription term?
A: Free trial periods are in addition to the subscription term that the customer chooses. After a free trial period ends, customers will begin their subscription term. For example, if a customer chooses a monthly subscription and the app offers a 14-day free trial, they have a 14-day subscription without charge. Once the 14-day free trial period passes, the monthly subscription term will begin and the customer will be charged. If the customer disables off auto-renew before the end of the 14-day free trial period, the subscription simply ends, and the customer is not charged.
Q: When I initiate a purchase for a subscription SKU, why is a different SKU returned?
A: A subscription comprises a non-buyable parent SKU representing the product and one or more child SKUs representing the subscription term. This setup prevents users from purchasing multiple subscriptions of the same product. The parent SKU is the SKU returned in the purchase response. The child SKU initiates the purchase. Because subscription terms and charges are handled by Amazon, your app only needs to check whether a subscription is valid.
Q: When a customer purchases a subscription are they able to cancel the subscription and receive a pro-rated refund?
A: No. Once a subscription is purchased for a period, it is valid through that period and cannot be cancelled. The customer can opt out of the auto-renew, but the purchased subscription is not cancelled. If a user has a valid reason for a pro-rated refund, they should contact Amazon customer service through the Contact Us link at Amazon.com.
Q: Does the value of
receiptId change for every renewal period?
A: Whether or not the
receiptId changes depends on whether the customer’s subscription was continuous or not:
- 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.
Q: Does the
purchaseDate value represent the initial purchase date or every renewed purchase?
purchaseDate represents the initial purchase date, not the
purchaseDate of subsequent renewals.
Q: Is calling the renew endpoint on the RVS still necessary in IAP v2.0?
A: No. RVS for IAP v2.0 only exposes the service named
verifyReceiptId. You do not need to renew anything in the request parameters like
purchaseToken of IAP v1.0 RVS.
Q: Can we determine on our backend server whether a subscription has been renewed without having the user opening the app? If so, how?
A You will not be able if the customer has specifically renewed the subscription. You will only know if the subscription is active or canceled. Amazon provides a
cancelDate when the subscription is no longer active. If the
cancelDate is null, the subscription is still active for the customer. If the customer cancels and then renews again, the app will receive multiple receipts. The first subscription that was canceled will have a
cancelDate and the new subscription will have a
purchaseDate and null
Q: How should I test my IAP-integrated app?
A: Test your app locally, then beta-test your app before going live:
Before submitting your app to the Amazon Appstore, test your app locally using the appropriate app for your version of IAP:
After submitting your app to the Amazon Appstore, use the Live App Testing service to beta test your app in a live production environment.
Q: What is the “Shared Secret”, and where do I find it?
A: The “Shared Secret” pins an IAP transaction to a particular vendor and validates that as a developer, you have the right to validate the receipt for the transaction.
The shared secret can be found on the Shared Key page for your developer account with the Amazon Appstore:
Q: Under what circumstances can a purchase token expire?
A: If Amazon has to cycle its security certificate for generating purchase tokens, purchase tokens can be rotated. This is not considered a common case and will not happen unless deemed necessary. Use the Receipt Verification Service
Renew method call to obtain a new purchase token if a token rotation is needed.
Q: I tried using the SDK Tester (IAP v1.0) Amazon App Tester (IAP v2.0) with the sample app and noticed that the currency is missing. I also noticed that the price entries do not have any additional information in their drop-down list. Is this intentional?
A: The currency symbol is intentionally absent for this app.The price entries are also intentionally formatted without additional information. The Product class returns Price as a
java.lang.String, which has the currency symbol. To discover what the marketplace your customer is in, and as a result of the returned currency symbol, the
UserData class has the
getMarketplace(), method which can be called to obtain the ISO_3166-1 marketplace code. Amazon’s testing tools intentionally omit the currency symbols from JSON strings, so that you can add those strings yourself.
Q: When I select an entry, it always displays the subscription type as “Monthly subscription”, even if the entry is a “Quarterly subscription.” Why is this happening?
A: This issue is a known limitation with the App Tester and does not affect functionality.
Amazon Appstore and Submission Process Questions
Q: Do I need specific assets for IAP items, such as an icon or thumbnail?
A: Yes. Each IAP item requires its own set of assets in the Amazon Apps & Games Developer Portal, but the assets do not need to be unique to the item.
- The icon is displayed on the In-App Purchasing Detail page and Thank You confirmation page.
- The thumbnail is not displayed publicly but is still required for each item.
Upload all of your assets for an item to the Amazon Apps & Games Developer Portal.
Q: How do I submit my IAP-integrated app?
A: Once you have tested your app, you can upload and submit it through the developer portal.
Q: How can I expedite the app approval process for my IAP-integrated app?
A: Test your app locally before submitting to the Amazon Appstore:
Use the appropriate app for your version of IAP:
In the Testing Notes area of the Submission tab on the Amazon Apps & Games Developer Portal, describe how to perform in-app purchases for your app.
Q: I receive an “unknown error” message from the Amazon client instructing me to re-download my app. What’s going on here?
A: The most likely cause for this “unknown error” is that the app failed the Digital Rights Management (DRM) check against the Amazon client. If you side loaded a DRM-wrapped app, the DRM check will fail. Perform your internal testing with the non-DRM wrapped version of your app. Amazon will conduct testing on your DRM-wrapped version of your app before it goes live.
Another possible cause for this error is that the Amazon Appstore client app crashed during the IAP purchase flow. To check if this is the case, force close the Amazon Appstore client app, then reopen the app to reestablish the fact that the app is valid.