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
- Q1. What does "IAP" stand for?
"IAP" is the abbreviation for Amazon's In-App Purchasing feature.
- Q2. What do customers need to complete in-app purchases?
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.
- See Change your 1-Click Settings.
- Q3: In order to promote my app, can I directly link it from within to the Amazon client?
Yes. For information about how to link from an app to the Amazon Client, see Linking to the Amazon Client.
- Q4: How do I get started with the In-App Purchasing API?
Review requirements on the In-App Purchasing Overview for your chosen technology. For IAP development for Android, review Get Started with IAP; for IAP development for web apps, review IAP API for Web Apps.
- Q5: Do I have to use the Amazon In-App Purchasing API for digital purchases within my app?
Yes, to make the app available on the Amazon Appstore, you must use the Amazon In-App Purchasing API for all eligible purchases.
- Q6: Which eligible items must use the In-App Purchasing API?
For selling any digital goods and services, your app must use the Amazon In-App Purchasing API. In-App Purchases can be in the form of the following:
- Consumable purchases such as extra lives, extra levels, or in-game currency.
- Premium purchases such as ad-free versions of your app. They typically do not expire.
- Subscription purchases such as music streaming, magazine and cloud storage.
- Q7: What items can I sell using payment methods other than Amazon In-App Purchasing?
For physical goods and services intended for customers to access or use outside the app, you must use payment methods other than the Amazon IAP API. Use credit card/third party payment services for the following purchases:
- Clothing, groceries, electronics
- Transportation and delivery services
- Airfare, event/movie tickets and gift cards
- Any listings for warranties and other similar offerings
- Any insurance product
- Donations for a non-profit
- Q8: Is there anything I cannot sell on the Amazon Appstore?
The following types of products are prohibited from being sold on the Amazon Appstore:
- Currency, credits, points, and other items/units that can be transferred from an end user to others and/or circulated as a medium of exchange
- Any prepaid account that creates cash balances enabling end users to purchase additional in-app products
- Lottery tickets
- Government documents, identification, birth certificates, passports, and licenses
- Unauthorized and unlicensed products
- Content that violates the Amazon Appstore Content Policy found here
- Items that infringe upon an end user’s privacy
- Any product or service that is regulated by a government entity such as alcohol, tobacco, medications or firearms
- Illegal and potentially illegal products
- Q9: My app uses Google’s in-app purchasing technology. Can I make it work on Amazon devices?
No, Google’s in-app purchasing technology requires access to Google Mobile Services, which does not work on Amazon devices.
- Q10: How do I make my in-app purchasable items available in all countries and regions?
Your in-app purchasable items are automatically available wherever your app is currently available, 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.
- Q11: What should I do if I don't want my in-app purchasable items be sold on a particular marketplace?
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.
- Q12: How do I change the prices of my IAP items in individual marketplaces?
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.
- Q13: What is the revenue split with Amazon on in-app purchases?
We’ll pay you royalties as set out in the Amazon Developer Services Agreement.
- Q14: Do you support parental controls for in-app purchasing?
Customers can require their Amazon password or a 4-digit PIN to complete in-app purchases. This feature is found under the Settings menu on the Amazon Apps storefront.
- Q15: Does the IAP API provide any protection against users accidentally repeating purchases?
IAP API does not offer this functionality. However, customers can protect themselves from accidental repeating purchases by using parental controls.
- Q16: Are there any additional requirements that apply to my use of in-app purchasing?
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 might 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
- Q1: Are the receipts returned by
No. The receipts returned are not guaranteed to be sorted. You can have your app sort the receipts.
- Q2: What if a purchase transaction is interrupted before the response is received?
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 behavior 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
- For Consumables, the purchase receipt is only listed in the
- Q3: What are the recommended values for the string lengths of
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, your encryption technique can influence its length.
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.
- Q4: Is the
- Yes, the
notifyFulfillment()call is required for all three types of in-app purchases. This call tracks the status of the purchase. 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
- Q1: When I initiate a purchase for a subscription SKU, why is a different SKU returned?
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.
- Q2: Why does the parent subscription SKU have no value for price?
Price information is associated with each child SKU, because each child SKU represents a different subscription period. The parent SKU does not have a price, as price varies depending on subscription duration.
- Q3: Can users manage subscriptions from their mobile devices?
Yes. Users can manage their subscriptions through both the Amazon client and the Amazon website.
- Q4: Is there a way for my app to determine if a customer has enabled the auto-renew option?
No. The IAP API does not include any methods to determine whether a user has auto-renew enabled or disabled.
- Q5: Can I raise or lower the price of a subscription?
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.
- Q6: 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?
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.
- Q7: After a customer purchases a subscription, are they able to cancel it and receive a pro-rated refund?
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.
- Q8: Does the value of
receiptIdchange for every renewal period?
Whether or not the
receiptIdchanges 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, if the customer did not auto-renew, let the subscription lapse, and then subscribed again a month later, the app will receive multiple receipts.
- Q9: Does the
purchaseDatevalue represent the initial purchase date or every renewed purchase?
purchaseDaterepresents the initial purchase date, not the
purchaseDateof subsequent renewals.
- Q10: Is calling the renew endpoint on the RVS still necessary in IAP v2.0?
You do not need to renew anything in RVS for IAP v2.0. There is no equivalent to the
purchaseTokenrequest parameter of IAP v1.0 RVS.
- Q11: Can I determine on my backend server whether a subscription has been renewed without having the user opening the app? If so, how?
You will not be able to do so, if the customer has specifically renewed the subscription. You will only know if the subscription is active or canceled. Amazon provides a
cancelDatewhen the subscription is no longer active. If the
cancelDateis 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
cancelDateand the new subscription will have a
- Q1: How should I test my IAP-integrated app?
Test your app locally, then beta-test your app before going live:
- Q2: What is the "Shared Secret", and where do I find it?
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. You can find the shared secret on the Shared Key page for your developer account with the Amazon Appstore: https://developer.amazon.com/sdk/shared-key.html
- Q3: 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?
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
UserDataclass has the
getMarketplace()method which you can call to obtain the ISO_3166-1 marketplace code. The testing tools intentionally omit currency symbols from JSON strings, so that you can add those strings yourself.
- Q4: 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?
This issue is a known limitation with the App Tester and does not affect functionality.
Amazon Appstore and Submission Process Questions
- Q1: Do I need specific assets for IAP items, such as an icon or thumbnail?
Yes. Each IAP item requires its own set of assets in the 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 on the "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 on the developer portal.
- Q2: How do I submit my IAP-integrated app?
Once you have tested your app, you can upload and submit it through the developer portal.
- Q3: How can I expedite the app approval process for my IAP-integrated app?
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.
- Q1: Why do I receive an "unknown error" message from the Amazon client instructing me to re-download my app?
The most likely causes for this "unknown error" are the following:
- The app failed the Digital Rights Management (DRM) check against the Amazon client. If you side-loaded a DRM-wrapped app, the DRM check fails. 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.
- 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 confirm that it is valid.