Web App IAP API Reference

• Amazon Services Library
  • Response Objects
  • Purchasing Handlers
• API Reference: AmazonInAppPurchasing
  • Members
    • ItemDataStatus
    • ItemType
    • Offset
    • PurchaseStatus
  • PurchaseUpdatesStatus
    • UserIdStatus
  • Methods
    • getItemData(skus)
    • getPurchaseUpdates(reset)
    • getUserId()
    • purchaseItem(sku)
    • registerObserver()
  • Type Definitions
    • onGetUserIdResponse(event)
    • onItemDataResponse(event)
    • onPurchaseResponse(event)
    • onPurchaseUpdatesResponse(event)
    • onSdkAvailable()

Amazon Services Library

The Amazon Services library includes the following methods:

• AmazonIapV2.addListener(listener)
  • You must register your observer prior to using this class
  • This method needs to be called within your onLoad() lifecycle method
• AmazonIapV2.purchase(sku)
  • This method is used to initiate a purchase of a particular SKU
  • This method works with all types of Purchasable Items
  • The user interface surfaced uses the information configured for the SKU to determine the purchase flow presented to the customer
  • This method can be called from your app anytime
• AmazonIapV2.getProductData(skus)
  • This method is used to retrieve Item data about a set of SKUs
  • This method works with all types of Purchasable Items
  • This method can be called from your app anytime
  • The parameter SKUs is an array of SKU strings
• AmazonIapV2.getPurchaseUpdates(reset)
  • This method is used to sync previous purchases and revoked entitlements across devices.
  • Implement getPurchaseUpdates() in the onStart() or onResume() method of the activity. Also, to prevent over-fulfillment of an order, de-duplicate the receipts with receiptId. See below for implementation details concerning the differences between consumables, entitlements, and subscriptions.
  • Consumables: The getPurchaseUpdates() method returns unfulfilled and canceled purchase receipts for consumables. Note the following for getPurchaseUpdatesResponse()in IAP 2.0:
    • Add logic in your app to handle fulfillment of purchase receipts returned from the call to getPurchaseUpdates(). The corresponding purchaseUpdatesResponse() callback may run when your app opens, or any other time, so use caution when referencing user interface (UI) elements or objects that may not be available.
    • Use the boolean reset parameter instead of the offset parameter. Set reset to true to return all purchase receipts, or set reset to false to return the receipts for purchases made since the last call to getPurchaseUpdates().
  • Entitlements: onPurchaseUpdatesResponse() returns receipts for canceled and active purchases of entitlements and subscriptions. Check whether the purchase was canceled with receipt.isCanceled(). In IAP 1.0, receipts for canceled entitlements and subscriptions were returned by calling getRevokedSkus() on the purchaseUpdatesResponse object.
  • Subscriptions: Same as Entitlements.
• AmazonIapV2.getUserData()
  • This method is used to retrieve the app-specific ID of the currently logged-in user
  • This method needs to be called within your onLoad() method
• AmazonIapV2.notifyFulfillment(receiptId, fulfillmentResult)
  • IAP 2.0 provides a new API that you can use to track the fulfillment status of a purchase. To track the fulfillment status of a purchase, implement the notifyFulfillment() API. Implement this call after the item is fulfilled to send the status of the purchase to Amazon.
  • If you do not call notifyFulfillment() with the FULFILLED status after the item is fulfilled, the delivery remains pending. In this case, the delivery attempts will continue to be made through the onPurchaseUpdatesResponse() callback the next time you call getPurchaseUpdates(). Eventually, the order may be canceled if Amazon does not receive explicit acknowledgement of fulfillment with this API.
  • If you can never fulfill the item, use the UNAVAILABLE status. You can call notifyFulfillment() with the UNAVAILABLE status from your app anytime.
  • This call is immutable. If an order is marked as FULFILLED or UNAVAILABLE via notifyFulfillment(), the status cannot be changed again

Response Objects

Every call you initiate via the Amazon Services results in a response received by the corresponding response handler specified in registerObserver(). Each of these responses makes use of a response object. These responses are detailed below:

• GetUserIdResponse - provides the app-specific UserID for the user currently logged into the Amazon Client
• PurchaseUpdatesResponse - provides a paginated list of receipts and revoked SKUs since the offset passed into the initiating request. Receipts are returned in a set and are unordered.
• ItemDataResponse - provides item data, keyed by SKU.
• PurchaseResponse - provides a status on purchases initiated within your app. Any error for a purchase is opaque to the developer, you do not need to implement any error handling scenarios in your app; this is managed by In-App Purchasing API.

Purchasing Handlers

You must implement the following response handlers and register them in the registerObserver method with the Amazon Services library:

• onSdkAvailable(onAvailableResponse) - This gets called when the In-App Purchasing services are ready to be called by your code.
• onGetUserIdResponse(userIdResponse) - Called in response to GetUserId.
• onItemDataResponse(itemDataResponse) - Called in response to GetItemData. data.itemData is a hash table of itemData objects keyed by SKU.
• onPurchaseResponse(purchaseResponse) - Called to report the status of a purchase operation. purchaseResponse.purchaseRequestStatus contains the status of the response. If a prior session of the application shut down before a purchase response could be delivered, this function will be called when a new session of the application registers a purchase hander.
• onPurchaseUpdateResponse(data) - Called with the list of entitlements that the user has been granted. data.receipts contains a hash table, keyed on SKU, that contains the receipts for the IAPs that have been granted to the user. data.revokedSkus has a list of SKUs that the user can no longer use.

API Reference: AmazonInAppPurchasing

Members

ItemDataStatus

Response codes for getItemData()

• INVALID_INPUT
• SUCCESSFUL
• FAILED
• SUCCESSFUL_WITH_UNAVAILABLE_SKU

ItemType

Types of purchases that can be made by the Amazon In-App Purchasing API.

This enumeration contains the following values:

• CONSUMABLE
• ENTITLEMENT
• SUBSCRIPTIONS

Offset

Helper value for finding purchase updates from the beginning of time.

Properties:

• BEGINNING - default value is NULL

PurchaseStatus

The status of the receipt

• INVALID_INPUT
• SUCCESSFUL
• FAILED
• INVALID_SKU
• ALREADY_ENTITLED

PurchaseUpdatesStatus

Response codes for getPurchaseData()

• INVALID_INPUT
• SUCCESSFUL
• FAILED

UserIdStatus

Response codes for getUserId()

• SUCCESSFUL
• FAILED

Methods

getItemData(skus)

Get item data for the list of SKUs.

Parameters:

Name	Type	Description
skus	Array	List of SKUs for which to retrieve item information

getPurchaseUpdates(reset)

Get the user's receipts. Set reset to false to return only the new receipts since the last time you called this method. Set reset to true to return all of the receipts for this user.

Parameters:

Name	Type	Description
reset	Boolean. Pass in a key/value pair, such as {reset: true}	Set to false to return only the new receipts since the last time you called this method. Set to true to return all of the receipts for this user.

getUserId()

Request the user ID. This will trigger a call to onGetUserIdResponse when the result is available.

purchaseItem(sku)

Initiates a purchase of the given SKU

Parameters:

Name	Type	Description
sku		Requested SKU

registerObserver()

Registers the callback handlers for handling asynchronous responses from the Amazon In-App Purchasing API.

Expects a hashtable of functions that will get called.

• onSdkAvailable
• onGetUserIdResponse
• onItemDataResponse
• onPurchaseResponse
• onPurchaseUpdatesResponse

Type Definitions

onGetUserIdResponse(event)

Called as a response to getUserId

The structure of the event object is:

• requestId
• getUserIdRequestStatus
• userId

Parameters:

Name	Type	Description
event		Requested SKU

onItemDataResponse(event)

Called as a response to getItemData with the requested item data.

The structure of the event object is:

• requestId
• itemDataRequestStatus
• itemData (array)
  • sku
  • price
  • title
  • itemType
  • description
  • smallIconUrl

onPurchaseResponse(event)

Called as a response to purchaseItem with the receipts.

The structure of the event object is:

• requestId
• userId
• purchaseRequestStatus
• receipt
  • sku
  • itemType
  • purchaseToken
  • subscriptionPeriod (null for non-subscription receipts)
    • startDate
    • endDate

onPurchaseUpdatesResponse(event)

Called as a response to getPurchaseUpdates with the receipts.

The structure of the event object is:

• requestId
• purchaseUpdatesRequestStatus
• receipts (array)
  • sku
  • itemType
  • purchaseToken
  • subscriptionPeriod (null for non-subscription receipts)
    • startDate
    • endDate
• revokedSkus (array of strings)
• offset
• isMore

onSdkAvailable()

Called when the API is ready for further calls. This is a callback for the registerObserver method.

---

Last updated: Dec 29, 2020