You can enter the in-app items for your IAP-integrated app independently from submitting your app. In fact, entering your in-app items before testing can help facilitate your testing with the Amazon App Tester (see Testing In-App Purchasing). For example, you can enter all of your in-app items, then download the JSON file for your app, and use that JSON file in performing your app testing, which will save you the step of manually creating a JSON file. Additionally, using the downloaded JSON file will help to ensure that all of your items will be available during your optional Live App Testing and in production.
The topic on this page describes how to create your in-app items for testing and for your app submission and clarifies the app submission process for IAP-integrated apps.
Creating New In-App Purchasable Items
Before you submit your app itself to the Amazon Appstore, submit your consumable, entitled, and/or subscription items that will be available for in-app purchases. The Amazon Appstore will not test your app until both the app and your in-app items have been submitted.
Note: You will need to have created an app on the Amazon Apps & Games Developer Portal before you can add In-App Purchase items to that app.
To create your purchasable items for IAP:
Navigate to your in-progress app on the Amazon Apps & Games Developer Portal:
- Log in to your developer account on the Amazon Apps & Games Developer Portal.
- Scroll down to the Dashboard view to see your apps.
- Click the link to your app to view the app detail page.
Click the In-App Items tab to view, add, or edit In-App items for the app.
Note the JSON Data File download button. Once you have entered all of your in-app items (or at least all of the in-app items that you plan to use for testing), you can click this button to automatically create and download a JSON-formatted data file that is compatible with IAP’s testing tools, such as the App Tester.
- At the bottom of the list of existing In-App Items (if any), click the button corresponding to the type of In-App Item that you want to create:
- Add a Consumable
- Add an Entitlement
- Add a Subscription
A New Consumable/Entitlement/Subscription page opens:
- On the New Item page, enter values for the following fields:
- Title: String containing the title of your item. (Max length = 128 characters)
- SKU: A unique-to-your-app string that becomes the ID for the item, for example, “com.amazon.example.iap.consumable” is the consumable SKU used by the IAP consumable sample app. The SKUs used by your app must match the SKUs that you submit to the Amazon Appstore. SKUs are case-sensitive. The SKU has a max length of 150 characters and can contain the characters a-z, A-Z, 0-9, underscores, periods, and dashes. If you are creating a subscription item, this SKU becomes the parent SKU for the subscription period SKUs that you will create later.
- Content delivery: Choose No additional file required if the content to be delivered is included as part of the app. Choose I’ll deliver the required assets if, as a developer, you will be fulfilling the purchased content yourself.
Click Save to create the item and the associated detail tabs for the item:
The item detail page now displays three additional tabs, where you can configure additional details about your in-app items:
- Availability & Pricing (Consumables and Entitlements only) : Set the price and availability date for the item.
- Subscription Periods (Subscriptions only): Specify subscription length and free trial information for the item.
- Description: Assign a display name and description to the item.
Images: Add images for the item.
The tabs shown depend on the type of item that you are creating.
Note: You must save the information that you have entered on one tab before moving onto the next tab. If you move from one tab to another without saving, the information that you have already entered will not be persisted when you return to that tab or submit your item.
Enter the appropriate additional details for your item, depending on the item type:
- If your item is a consumable or entitlement, click the Availability & Pricing to enter a price and availability date for your item:
- Are you charging for this consumable/entitlement?: Yes, if you are charging for the item, No, if you intend the item to be free.
- If you specify that Yes, you are charging for the item, a field displays allowing you to set the base price and currency for the item. After you set the base price, you will have the option of either manually setting the price for other currencies, or allowing the Amazon Appstore to set those prices for you, based on conversion rates and taxes. Valid prices (in USD) can either be $0.00 or range from $0.99 to $99.00.
- When would you like this item to be available?: Specify a date (IAP uses the PST time zone) for the item to become available in your app. If you leave this field blank, the item will become available as soon as it is approved by the Amazon Appstore.
- If your item is a subscription, enter the click the Subscription Period to add at least one subscription period for your item. Note that you can definite multiple subscription periods for an item:
- Subscription Period: Select a Subscription Period. Subscription periods start on the date of purchase. Valid values are Weekly, Bi-Weekly (every two weeks), Monthly, Bi-Monthly (every two months), Quarterly, Semi-Annually (every six months), or Annually (every twelve months).
- SKU: Enter a SKU (using the same guidelines as the item SKU) that corresponds to this subscription period. For example, “com.amazon.example.iap.subscription.weekly”. This SKU is a child SKU of the SKU that you entered on the item detail page.
- Free Trial: Specify an optional free trial period for the subscription. Valid values are No (no free trial), 7 days, 14 days, 1 month, 2 months, and 3 months.
- Are you charging for this subscription?: Yes, if you are charging for the subscription, No, if you intend the subscription to be free.
- If you specify that Yes, you are charging for the item, a field displays allowing you to set the base price and currency for the item. After you set the base price, you will have the option of either manually setting the price for other currencies, or allowing the Amazon Appstore to set those prices for you, based on conversion rates and taxes. Valid prices (in USD) can either be $0.00 or range from $0.99 to $200.00.
- Click either of the Save and Add a Subscription Period buttons to save the subscription period. If you want multiple subscription period options to be available for this item, you can define each of them the same way that you did for the subscription period that you just added.
- If you ever need to remove a subscription period, select the period and click the Remove Subscription Period button.
- Click the Description tab to enter description and language information for your item. This tab is the same for all three item types.
- Display Title: Name of the item as it will be displayed in your app.
- Description: Description of the item. (Max length = 1200 characters.)
- Keywords: Comma or white-space-delineated keywords, used to improve the discoverability of your app.
- To save this set of information and add a set translated into another language, click either Save and Add a Translation button.
- To save the description information and move on, click Save.
- Click the Images tab to upload a small and large icon for your item. This tab is the same for all three item types.
- Small icon (114px x 114px): A 32-bit 114x114 pixel icon for this purchasable item with a transparent background. This icon must be the same as the large icon.
- Large icon (512px x 512px): A 32-bit 512x512 pixel icon for this purchasable item with a transparent background. This icon must be the same as the small icon.
- To save this set of information and add a set of localized icons, click either Save and Add Localized Media button.
- To save the description information and move on, click Save.
When you have entered all of your in-app items, you can click the JSON Data File download button on your app’s detail page to download a JSON-formatted data file containing all of the real data for your items. Use this file when you test your app using Amazon’s App Tester and other testing tools. See Testing In-App Purchasing.
Submitting Your App
When your app and in-app items are ready, you can complete the submission of your app to the Amazon Appstore. This section gives recommendations to help facilitate your app submission and describes the app submission workflow.
Recommendations for App Submission
To expedite the approval of your app in the Amazon Appstore, in the “Testing Instructions” section, provide specific use cases for your IAP integration. Make sure to include where your items can be found and purchased within you app and any relevant information to help Amazon test your app.
App Submission Flowchart
Now that you have submitted your app and in-app items, what happens next? The following flowchart shows how an app moves through the Amazon Appstore submission workflow, starting with an IN PROGRESS app and finishing with a PUBLISHED app.
You can cancel your app submission while your app is in SUBMITTED status by clicking the Cancel review button.
If the Amazon Appstore encounters an issue with your app or a purchasable item defined for your app, your app status will change to PENDING, and you will be sent an explanation of the issue encountered and additional information as appropriate. Amazon will suspend additional testing until the issue is resolved by you submitting an updated version of the app or purchasable items.
Once your app has been approved for publication, the status will change to APPROVED and your app will be live in the Amazon Appstore.
Updating your App or In-App Purchasable Items
Even if you have already submitted your app, you can still make updates to both the app itself and your in-app items:
If your app update is independent of the purchasable items, submit only the updated app; no update to the items is required.
If your app update also includes an addition of or update to a purchasable item, submit your in-app item update before submitting your app update.
Troubleshooting Your App’s Submission
This section describes common issues with app submission and suggests ways to resolve these issues.
Missing IAP items
Issue: The Amazon Appstore is unable to identify where the IAP items are located within your app.
Resolution: Update the “Testing Instructions” for your app with specific IAP use cases that show where to find IAP items in your app.
Issue: Your app’s submission was missing specific expected IAP items.
Resolution: Please update your IAP items with all required information as specified in the section of this page.
Issue: The Amazon Appstore is unable to commence testing until your IAP items have been submitted through your portal account.
Resolution: Submit the missing IAP items so that the IAP items are live for the Amazon Appstore to test the app or to test the app in the Live App Testing environment.
UX Design Issue
Issue: The Amazon Appstore found interstitial dialog boxes in your IAP workflow.
Resolution: Update your application to remove all interstitial dialog boxes from the IAP workflow. Only Amazon’s messaging should be included in the purchase flow. See the UI and UX Design Guidelines for IAP.
IAP Workflow Issue
Issue: The Amazon Appstore encountered an error when attempting to purchase an item while validating the IAP workflow.
Resolution: Verify that the SKUs that your application is sending matches the SKUs that you included in your app submission. Also verify that your application is using the
getProductData(…)/onProductDataResponse(…)calls to validate your SKUs before offering them to your customer for purchase. Note that SKUs are case sensitive.
- Issue: The purchase flow for an item failed based on the
RequestStatusin the purchase response.
- Resolution: The purchase flow can fail for three possible reasons based on the
RequestStatusin the purchase response:
- ALREADY_PURCHASED: The user tried to buy an entitlement or subscription they already own. Your app can avoid this status by only offering entitlements and subscriptions not currently owned.
- INVALID_SKU: Your app should not receive this status if it validates SKUs prior to
getProductData(), as recommended.
- FAILED: An app can receive this status if the user did not complete the purchase, for example, if the user tapped Cancel before completing the purchase. This status is not necessarily indicative of an error.