Developer Console

In-App Purchasing FAQ

Answers to Frequently Asked Questions (FAQ) relating to In-App Purchasing (IAP).

General 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 In-App Purchasing?

Review requirements on the In-App Purchasing Overview. For IAP development for Android, you can choose between the Appstore SDK and the Appstore Billing Compatibility SDK. For more information on these solutions, see In-app purchasing solutions questions. For IAP development for web apps, review IAP API for Web Apps and for Unity, see Appstore SDK Plugin for Unity.

Q5: Do I have to use Amazon In-App Purchasing APIs for digital purchases within my app?

Yes, to make the app available on the Amazon Appstore, you must use one of Amazon's In-App Purchasing solutions for all eligible purchases.

Q6: Which eligible items must use In-App Purchasing APIs?

For selling any digital goods and services, your app must use an 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 APIs. 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?

Google's in-app purchasing technology requires access to Google Mobile Services, which does not work on Amazon devices. However, to port your app to the Amazon Appstore, you can use the Appstore Billing Compatibility SDK, which uses the same API signatures as Google Play Billing.

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 go to the Target Your App screen. In the Availability section, clear the checkbox 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 Console and go to My Apps. Select an app, click In-App Items, and then go to the Appstore Details screen. In the Pricing section, select the radio button for I will 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 Amazon IAP provide any protection against users accidentally repeating purchases?

Amazon IAP 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 (e.g., how you can promote your in-app items or how the purchase of in-app items can impact the functionality of your app).

In-app purchasing solutions questions

Q1: What solutions does the Amazon Appstore offer for in-app purchasing?

Amazon offers the Appstore Billing Compatibility SDK, the Appstore SDK, and the IAP v2.0 SDK. For Unity, there is the Appstore SDK Plugin for Unity and the IAP v2.0 Plugin for Unity. IAP v2.0 is on a deprecation path and not recommended for use.

Q2: What are the differences between IAP in the Appstore SDK and the Appstore Billing Compatibility SDK? Why should I choose one over the other?

The Appstore Billing Compatibility SDK uses the same API signatures as Google Play Billing. If you're porting an app from Google Play, consider using the Appstore Billing Compatibility SDK. The Appstore SDK has different API signatures than Google Play Billing, but supports more features such as Pending Purchases, Promotional Pricing, and Receipt Verification. If your app needs these features, consider using the Appstore SDK. For a full comparison, see Comparison of Amazon's IAP solutions.

Q3: Can I migrate from Appstore SDK IAP to the Appstore Billing Compatibility SDK?

Yes, you can migrate from Appstore SDK IAP to the Appstore Billing Compatibility SDK. With the Appstore Billing Compatibility SDK you can have lower maintenance and faster release cycles. First, review the Comparison of Amazon's IAP solutions to make sure your app's use cases are compatible. You can reuse the same IAP configuration and SKUs that you created in the Developer Console for the Appstore SDK. Reporting works the same as with the Appstore SDK.

Q4: How can I test integration?

You can test Appstore SDK IAP with both Amazon App Tester and Live App Testing (LAT). For the Appstore Billing Compatibility SDK, you can test with LAT only. You can use Receipt Verification Service and Real-Time Notifications for both SDKs.

Q5: Can I use the same public key for Appstore SDK and Appstore Billing Compatibility SDK?

Amazon uses the same public key for Appstore SDK and Appstore Billing Compatibility SDK. You don't need to many any changes when migrating between the SDKs.

Appstore IAP API questions

Q1: Are the receipts returned by purchaseUpdateResponse() sorted?

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 onPurchaseUpdatesResponse() if 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 getPurchaseUpdates().
  • 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 cancelDate property.
Q3: What are the recommended values for the string lengths of UserId, ReceiptId, and marketplace?

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 UserId is 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.
  • marketplace: The marketplace value 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 marketplace value can be null for older version of the Amazon Appstore.
Q4: Is the notifyFulfillment() call required?
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: 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 or Help link after logging in at amazon.com.

Q7: Does the value of receiptId change for every renewal period?

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, if the customer did not auto-renew, let the subscription lapse, and then subscribed again a month later, the app will receive multiple receipts.
Q8: Does the purchaseDate value represent the initial purchase date or every renewed purchase?

The purchaseDate represents the initial purchase date, not the purchaseDate of subsequent renewals.

Q9: 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 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 cancelDate.

Free trial questions

Q1: 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.

Q2: Can a customer enjoy another free trial after they have already experienced it?
No. A free trial can only be used once per subscription product. After a customer has started a free trial, they are no longer eligible for a free trial on the same subscription.
Q3: If a customer cancels a subscription after enjoying only seven days of a 14-day free trial, can that customer subscribe again to enjoy another seven days of a free trial?
After the free trial period has started, the customer is not eligible for the same free trial even if they did not previously complete the entire free trial period.
Q4: Is a customer able to enjoy both a free trial and promotional pricing for the same subscription product?
Yes. If you offer a free trial and promotional pricing and a customer is eligible for both, the promotional pricing takes effect for the customer after their free trial ends.

Amazon Coins questions

Customers can use Amazon Coins to make in-app purchases. The following are frequently asked questions about how Amazon Coins works with in-app purchases.

Q1: What do I need to do integrate my app with Amazon Coins?
Nothing. There are no additional coding requirements to integrate your app with Amazon Coins.
Q2: Since Amazon Coins can be purchased at a discount, is there an indicator in the IAP APIs that reflects the actual amount of local currency spent when an in-app item is purchased with Amazon Coins?
No. Regardless of the payment method, there is no API available that shares the amount an individual paid for a transaction.
Q3: Where can I find Amazon Coins Terms and Conditions?
Each marketplace has separate Terms and Conditions. For details, see Amazon Coins Terms.

Testing questions

Q1: How should I test my IAP-integrated app?

Test your app locally, then beta-test your app before going live:

  1. Before submitting your app to the Amazon Appstore, use the App Tester to test your app.
  2. After submitting your app to the Amazon Appstore, use the Live App Testing service to beta test your app in a live production environment.
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 UserData class 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:

  1. Use the App Tester to test your app.
  2. In the Testing instructions section on the Review & Submit screen in the Developer Console, describe how to perform in-app purchases for your app.

Troubleshooting

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.

Last updated: May 22, 2024