Implement pending purchases with Amazon IAP
Tags: tutorial, amazon, iap, kotlin
Published: 2023-03-13 17:39:38

What if I told you that as a developer you can provide parents with the peace of mind to never experience news headlines such as these:

![Newspaper headlines](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jgtacdskb8scs8zprjbm.png)

With Appstore SDK’s new pending purchases feature for the In-App Purchasing (IAP) API, you can now provide users with the assurance that unknown purchases won’t occur when children are using your app. _Why does it matter?_ Because offering the best user experience for IAP flows creates several benefits including positive brand reputation, increased ROI, and customer loyalty to start.

![Pending Purchases flow](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0ro8n752lmz9t2rb1q9v.png)

### So what are pending purchases?

A pending purchase occurs when a user of a child profile in Amazon Kids requests a purchase inside an app or game. After a child requests a purchase, a notification is sent to the parent. The parent can then approve or decline the purchase through the Parent Dashboard. While waiting for approval, the purchase will be in a pending state. If the parent approves the request, your app can deliver the IAP item. 

Here’s a screen recording of the pending purchase flow for Amazon Kids:

{% youtube uKSIxOv9yvI %}

### Integrating pending purchases with the Appstore SDK

Before you can implement pending purchases there are a few things you will need: 

* An app or game implementing the Amazon IAP API. If you would like to implement the API for the first time, you can watch my YouTube tutorial [here](https://www.youtube.com/watch?v=cmPAY16wGb0&feature=youtu.be).
* An app or game upgraded to the latest version of the [Appstore SDK - v3.0.4](https://developer.amazon.com/docs/apps-and-games/sdk-downloads.html#appstoresdk) (Appstore SDK contains the IAP API)
* Fire tablet device for testing (optional)

Now that you are all set, lets look at how you can implement `PendingPurchases` and the good news is this can be done in 3 steps:

### Stage 1: Call `enablePendingPurchases` to support child request

![Pending Purchase child request](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ljicd112b0f471x6sxyk.png)

To enable Pending Purchases, your app must call the `PurchasingService.enablePendingPurchases()`
method at any point before initiating a purchase in the `MainActivity` of your app.

**Kotlin**

```kotlin
class MainActivity : AppCompatActivity() {

    private lateinit var binding: ActivityMainBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        binding = ActivityMainBinding.inflate(layoutInflater)
        val view = binding.root
        setContentView(view)

        PurchasingService.registerListener(this, purchasingListener)
        // The call to enablePendingPurchases is required for your app to receive a PENDING RequestStatus
        PurchasingService.enablePendingPurchases();

 ....

        fun requestInAppPurchase() {
        PurchasingService.purchase(....)
        }
    }
```

**Java**

```java
public class MainActivity extends Activity {

    @Override
     public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        PurchasingService.registerListener(...);
        // The call to enablePendingPurchases is required for your app to receive a PENDING RequestStatus
        PurchasingService.enablePendingPurchases();
    }
    
...

    void requestInAppPurchase() {
        PurchasingService.purchase(...)
    }
}
```
### Stage 2: Parent approval & handle `RequestStatus` of `PENDING`

![Pending Purchase parent approval and purchase](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4yz0xo43mxtzqosfi233.png)

When a child initiates a request for a purchase, the resulting `PurchaseResponse` object has a `RequestStatus` of `PENDING`. Therefore, in your app or game ensure you are monitoring the purchase request status. You must either use Real-Time Notifications (RTN) or regularly call `getPurchaseUpdates()` to be notified of the purchase status and fulfil the purchase.

**Kotlin**

```kotlin
private var purchasingListener: PurchasingListener = object : PurchasingListener {
        override fun onUserDataResponse(response: UserDataResponse) {
            if (response.getRequestStatus() == PurchaseResponse.RequestStatus.PENDING) {
             // You can break here and do nothing, or show a modal indicating a request is pending.
             // The Appstore also shows a modal to the user indicating the request is pending before
             // returning the response to your app.
            }
        }
        // ...
 }
```

**Java**

```java
class MyListener implements PurchasingListener {
      public void onPurchaseResponse(final PurchaseResponse response) {
         if (response.getRequestStatus() == PurchaseResponse.RequestStatus.PENDING) {
             // You can break here and do nothing, or show a modal indicating a request is pending.
             // The Appstore also shows a modal to the user indicating the request is pending before
             // returning the response to your app.
         }
     }
     // ... 
}
```

### Stage 3: Child approval notification and handling

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8qbccy7rpryhozv0b0ms.png)

Once a parent has reviewed the request, the purchase is either:

1. **approved**, the `RequestStatus` is updated to `SUCCESSFUL` and your app follows its regular logic for successful transactions. On Fire devices, users get a notification from the system when a purchase is approved.
2. **not approved**, such as if the parent declines the purchase or lets the purchase request expire, your app doesn't need to take any further action. When not approved, there will be no notification from RTN and no new transaction when a call to `getPurchaseUpdates()` is made.

### Next steps
Once you have implemented Pending Purchases, you can test out your implementation with the Amazon App Tester. Within the tester you will be able to see the status of the purchases and manipulate them to test out the different scenarios of your users journey. 

Here’s a screen recording of the Amazon App Tester in action:

![Amazon App Tester demo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/oqld94h7aphbjblbwyf8.gif)

### Summary
We hope this feature enables new purchase flows to improve the user experience and review stages for parents and children. Try this feature out and let us know what you think!

### Related resources:
* [Appstore SDK v3.0.4 docs](https://developer.amazon.com/docs/in-app-purchasing/iap-overview.html?cmp=2023_02_devg&ch=soc&chlast=soc&pub=devto&publast=devto&type=org&typelast=org)
* [Amazon App Tester](https://developer.amazon.com/docs/in-app-purchasing/iap-app-tester-user-guide.html?cmp=2023_02_devg&ch=soc&chlast=soc&pub=devto&publast=devto&type=org&typelast=org)
* Implementing Amazon In-App Purchasing API (Part 1) [YouTube](https://www.youtube.com/watch?v=cmPAY16wGb0)

To stay up to date with Amazon Appstore developer updates on the following platforms:

📣 Follow [@AmazonAppDev](https://twitter.com/AmazonAppDev) on Twitter
📺 Subscribe to our [Youtube channel](https://www.youtube.com/amazonappstoredevelopers)
📧 Sign up for the [Developer Newsletter](https://m.amazonappservices.com/devto-newsletter-subscribe)