Answers to Frequently Asked Questions (FAQs) relating to In-App Purchasing (IAP) API 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/regions.
- The default address for 1-Click Payment must be a valid address in one of the supported countries/regions.
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: Review the IAP Overview, then review the getting started page for your chosen technology: for IAP with Android, review Get Started with IAP; for IAP development with web apps, review IAP API for Web 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: We’ll pay you royalties as set out in the App Distribution and Services Agreement.
Q: How do I make my in-app purchasable items available in all countries and regions?
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.
- 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
Q: What are the recommended values for the string lengths of
A:These parameters have the following recommended lengths if you are defining space for them in a database:
UserId: 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.
ReceiptId: 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 maps a two letter code to each country, territory, or area of geographical interest. The actual
marketplacevalue can be
nullfor older version of the Amazon Appstore.
Q: Is the
notifyFulfillment() call required?
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: Can I raise or lower the price of a subscription?
A: If you lower the price, new and current subscribers pay the new price (starting with their next payment). if you raise the price, only new subscribers pay the higher price. For additional details, see Update Subscription Price.
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, use the App Tester to test your app.
- 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: https://developer.amazon.com/sdk/shared-key.html
Q: I tried using the Amazon App Tester 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 App Tester to test your app.
- 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.