Set Up Add-On Subscriptions

The following steps show you how to set up, integrate, and test an add-on subscription.

Prerequisites

To use add-on subscriptions, you must have the following:

• Add-on subscriptions activated in the Developer Console.

  Because this feature is available to select partners only, your Amazon representative must activate it for you.

• Appstore SDK version 3.0.9 or later.

Step 1: Set up an add-on subscription

Setting up an add-on subscription in the Amazon Developer Console is similar to setting up a base subscription. For instructions on how to set up a new subscription, see Create new in-app items.

To set up an add-on subscription

1. Sign in to the Developer Console and from the navigation bar, select My Apps.
2. Find your app in the list and in the In-App Items column, select <Number> Items.

3. On the "In-App Items" screen, select Add Single IAP > Add an add-on subscription.

   

4. To customize the add-on subscription purchase experience and the subscription management experience, upload an add-on subscription icon and background image.

5. In the Map add-on to live subscription section, click Map add-on to live subscription.

   

   Here you provide information to define the relationship between the add-on subscription and the base subscription.

6. Complete all required fields. Make sure to use the most granular level to define the relationship between the add-on and base subscription. For example, you can define the relationship at the base subscription term level.

   The Submit IAP button remains inactive until you provide all required information.

7. After completing all required fields, choose whether to submit the add-on subscription to only Live App Testing (LAT), or to both LAT and the currently live app.

   For more details, see Submit a new or updated in-app item.

   Note: Consider first testing your add-on subscription using LAT before you promote the changes to the live app. With LAT, you can test your add-on subscription before it's available to all customers.

Step 2: Integrate an add-on subscription in your app

After you've set up and published an add-on subscription (in either testing or live mode), you must upgrade the Appstore SDK integration in your app.

Before you upgrade your SDK integration, consult the following add-on integration summary table.

This guide focuses specifically on how to integrate the In-App Purchasing (IAP) API to support add-on subscriptions in your app. For comprehensive steps on how to completely integrate with the IAP API, see Integrate the IAP API within your app.

Handle purchase updates

Add-on subscription receipts are treated the same way as regular subscription receipts. There is no change to the getPurchaseUpdates() method to support add-on subscriptions. When you call getPurchaseUpdates(), the response returns add-on receipts the same way as base receipts. For implementation details for the getPurchaseUpdates() method, see Implement getPurchaseUpdates method in the IAP implementation documentation.

Implement the getProductData() method to surface add-on subscriptions in your app

To implement the getProductData() method, see Implement getProductData method in the IAP implementation documentation. There is no change in request parameters for the getProductData() method. However, the response includes two additional fields for mapping add-on and base subscription SKUs.

The getProductData() method handles the following scenarios for subscription relationships:

• When you provide a base subscription's term SKU:
  • Returns a list of related add-on subscription term SKUs under the addons field.
• When you provide an add-on subscription's term SKU:
  • Returns a list of compatible base subscription term SKUs under the bases field.

These relationships reflect the mappings you've established in the Developer Console, where specific add-on subscription terms are linked to compatible base subscription terms.

With this functionality, you can:

• Show only relevant add-on subscriptions to customers who have specific base subscriptions.
• Make sure add-on subscriptions are offered only with their compatible base subscriptions.
• Maintain proper subscription dependencies in your app.

Implement code to purchase an add-on subscription in your app

To implement the purchase of an add-on subscription, use the purchase() method and pass the add-on term SKU as a parameter. Add-on subscription purchases are built on the existing IAP purchase flow, and include additional validations to verify whether the customer's base subscription is active. If the customer's base subscription is inactive, the PurchaseResponse.RequestStatus has the value INACTIVE_BASE_SUBSCRIPTION. A successful add-on subscription purchase has a status with the value SUCCESSFUL. There is no change to existing request and response structure.

The following example shows a purchase request and response.

Example request

public void onBuyOrangeClick(final View view) {
    final RequestId requestId = PurchasingService.purchase("com.example.app.monthly");
    Log.d(TAG, "onBuyOrangeClick: requestId (" + requestId + ")");
}

Example response

public void onPurchaseResponse(final PurchaseResponse response) {
    switch (status) {
        // ...
        case SUCCESSFUL:
            final Receipt receipt = response.getReceipt();
            iapManager.setAmazonUserId(response.getUserData().getUserId(), response.getUserData().getMarketplace());
            Log.d(TAG, "onPurchaseResponse: receipt json:" + receipt.toJSON());
            iapManager.handlePurchase(receipt, response.getUserData());
            iapManager.refresh();
            break;
        case ALREADY_PURCHASED:
            // Customer already has an active entitlement for the item.
            // App and Appstore are out of sync. Re-sync all purchases from Appstore.
            PurchasingService.getPurchaseUpdates(true);
            break;
        case INVALID_SKU:
            Log.d(TAG, "onPurchaseResponse: invalid SKU! onProductDataResponse should have disabled buy button already.");
            final Set<String> unavailableSkus = new HashSet<String>();
            unavailableSkus.add(response.getReceipt().getSku());
            iapManager.disablePurchaseForSkus(unavailableSkus);
            break;
        case FAILED:
            // Customer exited before completing the purchase journey
            Log.d(TAG, "onPurchaseResponse: failed so remove purchase request from local storage");
            iapManager.showPurchaseFailedMessage(response.getReceipt().getSku());
            break;
        case NOT_SUPPORTED:
            Log.d(TAG, "onPurchaseResponse: failed so remove purchase request from local storage");
            iapManager.showPurchaseFailedMessage(response.getReceipt().getSku());
            // Device doesn't support IAP functionality.
            // Disable in-app purchase for this device.
            iapManager.disableAllPurchases();
            break;
        case INACTIVE_BASE_SUBSCRIPTION:
            Log.d(TAG, "onPurchaseResponse: failed so remove purchase request from local storage");
            // Developer can do custom logic as per implementation need
            break;
    }
}

Process the purchase receipt and fulfill the purchase

Process the add-on receipts the same as regular subscriptions receipts. For implementation details about how to handle the add-on receipt and fulfill the purchase, see Process the purchase receipt and fulfill the purchase in the IAP implementation documentation.

To verify the add-on receipts from the purchase, have your back-end server verify the receiptId with Amazon RVS before fulfilling the item. For details on how to verify the add-on receipt using RVS, see Handle and validate add-on subscription purchases.

Handle and validate add-on subscription purchases

Follow the same RVS implementation process for add-on subscriptions as you would for regular subscriptions. For detailed instructions about receipt processing and subscription verification, see Receipt Verification Service Overview. The request parameters remain unchanged for add-on subscriptions. When you process an add-on subscription receipt, the RVS response includes the field baseReceipts. This field contains the linked base subscription receipts. Before granting access to both the add-on and base subscription content, use the values listed in baseReceipts to confirm the validity of the base subscription.

Send fulfillment result to Amazon and grant item to the user

After you grant the subscription content to the customer, call notifyFulfillment() for the add-on subscription receipt the same way as you do for the base subscription receipt. For implementation details about how to send the fulfillment result to Amazon, see Process the purchase receipt and fulfill the purchase in the IAP implementation documentation.

Step 3: Test the add-on subscription

Amazon provides several tools and services to help you test your IAP implementation. To understand the tools and to see a suggested workflow for testing your app, see IAP Testing Overview.

App Tester for add-on subscriptions

To set up and configure App Tester for your app, see the App Tester User Guide. App Tester responds to API calls using data stored in a JavaScript Object Notation (JSON) file. The file contains purchase data for the IAP items. You can automatically create the JSON file through the Developer Console.

To set up App Tester

1. Export a JSON file of your IAP items:
   1. In the Developer Console, from your app's main page, click the In-App Items tab to view the current in-app items for the app.
   2. Select Export Multiple IAPs > JSON, and then confirm you want to export the items.
   3. Click the link to download the file.
2. To enable add-on subscription testing, in the generated JSON file, manually add the addons and bases fields.

You must manually add these fields before configuring App Tester. The addons field represents the list of add-on subscriptions applicable to the corresponding base term, and the bases field defines the list of base terms associated with the add-on subscriptions.

To test getProductData()

1. Verify that your JSON file for App Tester contains the SKUs and product definitions that you want to test.
2. In the IAP API Response Settings section, use the drop-down menu next to GetProductData API:
   • To test for a SUCCESSFUL response, set the preference to Default or SUCCESSFUL.
   • To test for a FAILED response, set the preference to FAILED.
3. Call getProductData().
4. Process the response by using the onGetProductDataResponse callback.
5. Check for the additional fields addons or bases.

Example JSON response

"your_item_SKU" : {
       ...
       "subscriptionParent": "com.amazon.subs.gold",
       "addons": ["com.example.iap.subscription.mymagazine.gold"],
       "bases": ["com.example.iap.subscription.mymagazine.silver"]
       ...
 }

To test purchase()

1. Verify that your JSON file for App Tester contains the SKUs and product definitions that you want to test.
2. In the IAP API Response Settings section, use the drop-down menu next to Purchase API:
   • To test for a SUCCESSFUL response, set the preference to Default or SUCCESSFUL.
   • To test purchasing an add-on subscription when the base subscription is inactive, set the preference to INACTIVE_BASE_SUBSCRIPTION.
3. Call the purchase() method.

4. Process the response by using the onPurchaseResponse callback.

   Successfully purchased content appears on App Tester's Manage Transactions tab.

Test the RVS response for an add-on subscription

Amazon provides the Receipt Verification Service (RVS), which you can use to validate purchases from your back-end server. To learn more about this service, see Receipt Verification Service Overview.

Use RVS Cloud Sandbox to verify receipts generated by App Tester. For details, see Use RVS Cloud Sandbox. Verify that the RVS response for an add-on receipt includes the field baseReceipts, which should match the value of the mapped base subscription's receiptId.

Test add-on subscriptions with Live App Testing

You can use Live App Testing (LAT) to test add-on subscriptions just as you can for other IAP items. Before you make the add-on subscriptions available to customers, you can test purchasing use cases in the LAT environment first.

For use cases that test add-on subscriptions, consult the following table.

Related topics

• Add-On Subscriptions Overview
• Add-On Subscriptions FAQ

Last updated: May 20, 2026