Home > Services & APIs > Earn > In-App Purchasing

Integrating Subscriptions in Unity (IAP v1.0)

IAP v1.0 Deprecation Notice

In July 2014, Amazon released the In-App Purchasing (IAP) v2.0 API, which includes several important updates. As of April 30, 2016, Amazon will deprecate IAP v1.0 for new and updated app submissions. While this deprecation will not affect apps that are currently live in the Amazon Appstore, any apps submitted as either a new or updated app after May 11, 2016 will need to use IAP v2.0.

Overview of Subscriptions

In-App Purchasing v2 Unity Plugin Now Available

A Unity plugin that supports IAP v2 has been released. Please visit the Unity plugins page for more information.

Subscription content includes any type of content that carries an entitlement, is bound by a period of time, with the ability to auto-renew at the end of the period, and is available on all eligible devices registered to the customer's Amazon account.

Your app can have multiple subscriptions defined for it, with each subscription having multiple periods. For example, the Amazon-News app can have multiple subscriptions defined for it, one for the "Business" section, one for the "Electronics" section, and one for the "Books" section. Each section can, in turn, have multiple periods defined for it. "Business" can offer a weekly and monthly period, "Electronics" can offer a monthly and bi-monthly period, and "Books" can offer a quarterly and yearly period.

Under this example each subscription has a unique SKU (the parent), and each subscription period has their own SKU (children SKUs).

Once purchased, an entitlement is granted to the customer's Amazon account for a specific term. That entitlement is used to access the content from any eligible device the customer links to their account.

More detail is available on the IAP developer site: Integrating Subscription Content

Step 1: Entitle Content

As with Entitlement IAP, you need to make sure the user is entitled to content they have already purchased. However, Subscriptions need to be evaluated differently, to ensure the user has a valid subscription.

Since a user's subscription history may include several receipts (one for every time they started a new subscription), you need to examine the most recent receipt by sorting them based on the 'start date' field. Then examine the 'end date' field of that receipt -- if it is "null", then the subscription is valid. If there is an end date in the field, it has expired.

On startup, the Unity plugin will handle the registerObserver() API call. This will wire up the plugin's AmazonIAPEventListener, which serves a role analagous to the Amazon IAP PurchaseObserver. The results of the call are available in the AmazonIAPEventListener.onSdkAvailableEvent().

The plugin then calls initiatePurchaseUpdates() and makes the results available in the AmazonIAPEventListener.purchaseUpdatesResponseSuccessfulEvent() and the AmazonIAPEventListener.purchaseUpdatesResultFailedEvent().

You should entitle content for every receipt whose SKU is not in the revoked SKU list.

void onSdkAvailableEvent( bool isTestMode )
{
Debug.Log( "onSdkAvailableEvent. isTestMode: " + isTestMode );
}

void purchaseUpdatesRequestFailedEvent()
{
Debug.Log( "purchaseUpdatesRequestFailedEvent" );
}

void purchaseUpdatesRequestSuccessfulEvent( List<string> revokedSkus, List<AmazonReceipt> receipts )
{
Debug.Log( "purchaseUpdatesRequestSuccessfulEvent. revoked skus: " + revokedSkus.Count );

// Process Receipts
foreach( var receipt in receipts )
{
// Look for Subscription Receipts and entitle content as necessary
// Do not entitle any SKUs present in the list of revoked SKUs

// If you have more than one receipt for a given Subscription SKU,
// sort by receipt start date, then evaluate the most recent one
Debug.Log( receipt );
}
}

Step 2: Check Items

As with the other IAP types (Entitlement, Consumable) you query the IAP catalog to make sure the SKUs you wish to purchase are available. This is done by invoking the AmazonIAP.initiateItemDataRequest() method.

For Subscriptions, only the "Subscription Term" or "Child" SKUs are purchasable. When checking (or purchasing) a Subscription SKU, be sure to use the SKU belonging to the term you wish to purchase.

if( GUI.Button( new Rect( xPos, yPos, width, height ), "Initiate Item Data Request" ) )
{
AmazonIAP.initiateItemDataRequest( new string[] { "com.amazon.buttonclicker.subscription.1mo" } );
}

You can check the validity of all your SKUs (Entitlement, Consumable, Subscription) here in the itemDataRequestFinsihedEvent and itemDataReqeustFailedEvent.

void itemDataRequestFailedEvent()
{
// If you get this response, either retry or stop purchase attempt.
Debug.Log( "itemDataRequestFailedEvent" );
}

void itemDataRequestFinishedEvent( List<string> unavailableSkus, List<AmazonItem> availableItems )
{
// Do not continue with the purchase attempt if the your SKU is in the list of unavailable SKUs!
Debug.Log( "itemDataRequestFinishedEvent. unavailable skus: " + unavailableSkus.Count + ", avaiable items: " + availableItems.Count );
}						

Step 3: Purchase Subscription

Now that you've validated the SKU, you are ready to invoke AmazonIAP.initiatePurchaseRequest(). For Subscriptions, you always want to use the "Subscription Term" or "Child" SKU.

AmazonIAP.initiatePurchaseRequest( "com.amazon.buttonclicker.subscription.1mo" );

The response (with the purchase Receipt) will be returned via AmazonIAPEventListener methods:

Note that, like an Entitlement, the reason for failure includes "ALREADY_ENTITLED". With Subscriptions, a customer may not purchase another until they have opted-out and the current subscription has expired.

void purchaseFailedEvent( string reason )
{
// The reasons for failure on a Consumable are:
// INVALID_SKU
// ALREADY_ENTITLED
// FAILED
// You should log the reason, but in every case, do not entitle content
Debug.Log( "purchaseFailedEvent: " + reason );
}


void purchaseSuccessfulEvent( AmazonReceipt receipt )
{
// On successful purchase, you may entitle content
Debug.Log( "purchaseSuccessfulEvent: " + receipt );

// You should preserve the token for use with Receipt Verification
String purchaseToken = receipt.token;
}

If you need a Subscription history for a user, you will be able to get it later using AmazonIAPEventListner.purchaseUpdatesRequestSuccessfulEvent().