Developer Console

In-App Purchasing Overview

The In-App Purchasing (IAP) API allows your app to present, process, and fulfill purchases of digital content and subscriptions within your app. Amazon supports an IAP API for Android Apps and Web Apps. This page gives a high-level introduction to the IAP API.

What is In-App Purchasing (IAP)?

With In-App Purchasing (IAP), your app's users can purchase various types of digital items within your app, such as extra lives for a game or a subscription to premium content.

The following scenarios describe potential use cases for IAP:

  • Create a "freemium" model for your app where the app itself is free but you charge a premium for advanced services or functionality.
  • Allow your customers to purchase items to enhance their gaming experience, such as currency, extra moves, or lives.
  • Unlock bonus levels or mini-games by allowing users to purchase access to this content.
  • Enable customers to subscribe to content available within your app.

The IAP API handles details about purchase flow, payment processing, providing a receipt to your app, and managing rights to the purchasable content, so that you do not have to code these things yourself.

Amazon's Role in IAP

The Amazon Appstore plays an integral part of the IAP API workflow. Amazon runs the purchase workflow, starting when the customer decides to purchase an item and ending when Amazon provides the app either a receipt for the purchase or a status code, in the case of a failed purchase. You do not need to provide purchase dialogs, transaction timeout logic, or "Thank You" dialogs. The Amazon Appstore provides all of these pieces of a transaction.

Once a user initiates a purchase, the Amazon Appstore client app surfaces and presents an Amazon-branded user interface to complete the transaction. This app presents the user interface for all aspects of the purchase workflow:

  • Logic to display the purchasable item.
  • Perform the purchase.
  • Handle any preconditions or error scenarios.

If a purchase is unsuccessful, the Amazon Appstore presents the relevant messaging to the customer; your app should not message the customer. For example, if the customer does not have a valid credit card on file, the Amazon Appstore redirects the customer to a page where they can update their payment information. Do not provide a confirmation or other interstitial dialog to the customer regarding the purchase flow.

The following table summarizes the separation of responsibility between your app and the Amazon Appstore when implementing IAP:

Responsibility
Your App
Amazon
Presents the catalog of in-app items to the customer for purchase.
Unlocks purchasable functionality.
Manages the purchase flow.
Performs payment processing.
Handles secure communication with the Amazon platform, including payment security.
Verifies entitlements and validates purchase receipts.
Manages billing for auto-renewing subscriptions.
Manages billing for revoking of entitlements.
Verifies receipts for subscriptions and entitlements before providing content to user.
Downloads remotely delivered content.
Displays and uses downloaded digital goods.
Tracks customer purchases and consumable inventory.

IAP Components

If you are new to working with IAP, familiarize yourself with the following components, which are all involved in implementing this feature:

Name Description Documentation
IAP API Your app uses the IAP API to implement and fulfill in-app purchases. Android apps: Get Started with IAP

Web apps: IAP API for Web Apps
For more information on web apps, see Web App Development Overview.
IAP API reference Lists and descriptions of IAP APIs. Android apps: Appstore SDK API Reference

Web apps: Web App IAP API Reference
For more information on web apps, see Web App Development Overview.
Amazon Appstore Handles payment processing, alerts, fulfillment, and other back-end functionality. Not applicable
App Tester Test your app locally before publishing to the Amazon Appstore. IAP Testing Overview
Receipt Verification Service (RVS) Verify the validity of transaction receipts. RVS supports a sandbox environment and a production environment. Receipt Verification for IAP Apps
Live App Testing service Beta test your app with a select group of users in a production environment. Understanding Live App Testing

Types of Purchases

As you plan your IAP implementation, you will need to define what types of items your app will make available to its users. You will also need to determine how you want to deliver those purchased items. This section gives a brief introduction to the types of purchases supported by IAP.

Refer to the Distribution Agreement for information on what can and cannot be a purchasable item.

Types of Purchasable Items

IAP includes three different categories of purchasable items:

  • Consumables: Purchase that is made, then consumed within the app, such as extra lives, extra moves, or in-game currency. May be purchased multiple times.
  • Entitlements: One-time purchase to unlock access to features or content within an app or game.
  • Subscriptions: Offers access to a premium set of content or features for a limited period of time.

Content Type and Delivery Flows

IAP supports three basic delivery flows:

  • Instantly available content
  • Deliverable content
  • Pending purchase

Instantly available content

Instantly available content is unlocked or otherwise made available to the customer upon purchase. Under this model, your app already has everything it needs for the customer to use the purchasable item immediately upon purchase. You can use all three types of purchasable items with this model.

Your app should contain the unique identifiers for each purchasable item (SKUs), the ability to present a catalog to the customer, and logic within the app to unlock the purchasable item upon successful transaction.

Step Component Task
Step 1 App App launches the in-app purchase flow. App invokes IAP API to manage the purchase.
Step 2 IAP API IAP API interacts with the user to complete the purchase. IAP API returns a purchase receipt to the App.
Step 3 App App uses the receipt to unlock the purchased local content.

Deliverable content

Deliverable content allows you to make new content available to the customer. Under this model, your app will download the new content from your servers and make it available to the customer. Deliverable items typically are subscription items.

Your app should contain the unique identifiers for each purchasable item (SKUs), the ability to present a catalog to the customer, and logic within the app to download, persist, and make available the downloaded content upon successful transaction.

Step Component Task
Step 1 App App launches the in-app purchase flow. App invokes IAP API to manage the purchase.
Step 2 IAP API IAP API interacts with the user to complete the purchase. IAP API returns a purchase receipt to the App.
Step 3 App App sends receipt to the App server, to initiate the content delivery.
Step 4 App server App server makes the content available to the user.

Pending purchase

A pending purchase is not immediately made available to the customer. Under this model, an additional step is required after the customer initiates the purchase and before your app can grant the purchase. Your app should not grant the purchase to the customer while it is still in the pending state. You can use consumables and entitlements with this model.

The difference between the pending purchase flow and the deliverable content flow is that your app calls enablePendingPurchases() on app create, and doesn't grant entitlements to the customer when it receives PurchaseResponse.RequestStatus.PENDING in onPurchaseResponse().

Step Component Task
Step 1 App App launches the in-app purchase flow. App invokes the enablePendingPurchases() and purchase() APIs to initiate the transaction.
Step 2 IAP API IAP API interacts with the user to request the purchase. IAP API returns a PENDING status to the app.
Step 3 IAP API If the customer approves the transaction, IAP API returns a purchase receipt to the app through Real-Time Notifications (RTN) or getPurchaseUpdates().
Step 4 App or App server App or App server makes the content available to the user.

For details on how to implement pending purchases, see Implement Pending Purchases.

Refunds

For consumables and entitlements, if a customer has a valid reason for requesting a refund, they should contact Amazon customer service on the Amazon website through Contact Us or Help.

For subscriptions, a customer can cancel a subscription by opting out of auto-renew. However, this doesn't immediately cancel a subscription and the customer continues to have access for the remainder of the subscription term for which they paid. If a customer has a valid reason, they can request a pro-rated refund by contacting Amazon customer service on the Amazon website through Contact Us or Help.

SKUs

A SKU (technically a stock-keeping unit) is a unique identifier for each distinct purchasable item. It is unique to you (specifically your developer account registered on the developer portal), and is a (up to) 150-character length string of arbitrary structure that can contain the characters a-z, A-Z, 0-9, underscores, periods, and dashes, and is case sensitive. Purchasable items and SKUs have a 1:1 mapping. Your app will pass the SKU value via the PurchasingManager helper class to the client. The SKU is how the client knows what the customer is trying to purchase, and will manage the purchase flow accordingly.

You need to ensure that every purchasable item you define has a unique SKU. The SKUs are unique across your developer account. When you submit SKUs for multiple apps you need to ensure that there is no overlap.

Before a SKU can be used, it must be configured via the developer portal. Refer to the developer portal section of the Frequently Asked Questions for information on how to configure SKUs.

App Submission Process

You need to create and submit the in-app items for your IAP-integrated app before you submit the app to the Appstore. The Amazon Appstore will not test your app until both the app and your in-app items are submitted.

Use the Developer Console to create and manage the app's catalog of purchasable items. See Submit Single In-App Items.

You can also create or modify multiple in-app items at the same time. See CSV Files for IAP Batch Submission.

If you decide to add or edit your purchasable items after submitting your app, you will need to re-submit both the new/changed items and the app itself to the Amazon Appstore.


Last updated: Sep 18, 2023