Set Up Quick Subscribe

Important: At this time, Quick Subscribe is available to select partners only.

Quick Subscribe reduces the number of clicks needed to purchase subscriptions on Fire TV devices and on your app's retail page. With Quick Subscribe, your customers enjoy a streamlined experience with app download, subscription purchase, and entitlement creation.

In a typical account creation process, a customer clicks over 150 times to sign up for an account. Quick subscribe now features one-click account creation. With Quick Subscribe's one-click account creation, it takes only one click for a customer to share their first name, last name, zip code, and email address with your app, which reduces customer friction for creating an account and signing in.

User flow comparison
How does Quick Subscribe work?
Set up Quick Subscribe
Configure Quick Subscribe in the Developer Console
Configure security profile in the Developer Console
Handle getPurchaseUpdates
Acknowledge Receipt API
Integrate with RTN and RVS
Integrate one-click account creation
Test Quick Subscribe with LAT
Quick Subscribe FAQ

User flow comparison

The following image shows a typical customer experience when signing up for a subscription on a Fire TV without Quick Subscribe.

With Quick Subscribe, customers can subscribe in the first step, directly from the app detail page. The following image shows the customer experience when signing up for a subscription on Fire TV with Quick Subscribe one-click account creation.

With one-click account creation, Amazon shows the customer a consent screen that allows them to agree to share their details with your app. If a customer provides their consent, after the app downloads and launches, it can retrieve the customer's details from Amazon and create an account. Your app can then automatically sign in the customer, bypassing the step for entering credentials.

If you've already integrated with Quick Subscribe and aren't yet using one-click account creation, instead of being automatically signed in, the customer enters their account credentials with the Fire TV remote. This experience is less user-friendly and on average requires over 150 clicks. The following image shows the customer experience when signing up for a subscription on Fire TV with Quick Subscribe without one-click account creation.

The following steps describe how Quick Subscribe works with Fire devices, Amazon In-App Purchasing (IAP), Login with Amazon (LWA), your app, and your server.

Step 1: The customer initiates a subscription purchase from the app detail page on a Fire TV.

Step 2: Amazon shows a consent screen that asks the customer permission to share their name, zip code, and email with your app.

Step 3: Amazon informs the customer their purchase is complete.

Step 4: The app automatically downloads and opens on the customer's device.

Step 5: On launch, the app determines whether the customer has signed in. If the customer hasn't signed in, the app calls the getUserData() method from Amazon IAP, and Amazon returns the customer's consent status.

If the consent status is CONSENTED, the app follows steps 6 through 8. Otherwise, the app falls back to the default sign-in experience.

Step 6: The app calls the authorize() method of the LWA SDK to start a session.

Step 7: The app uses the User.fetch() method from LWA to fetch the customer's details, which include name, zip code, and email.

Step 8: The app uses the customer's details to create a new account or map to an existing account and then automatically sign in the customer.

Step 9: After the customer has signed in, your app calls the getPurchaseUpdates() method from Amazon IAP in the onResume() method to retrieve the receipt for the purchase.

Step 10: The app calls the notifyFulfillment() method from IAP to acknowledge the receipt for the purchase and to confirm that the customer has access to the content. Or if you have previously integrated with the Acknowledge Receipt API, the app calls the acknowledgeReceipt REST API to confirm the customer has accessed the content.

Step 11: The app updates your server with the purchase data and verifies it with the Receipt Verification Service (RVS) by calling the verifyReceiptId REST API.

Step 12: The app allows the customer access to the content.

Note: Quick Subscribe is supported on Fire TV devices running Fire OS version 5 and above, and on your app's retail web page.

To set up Quick Subscribe in your app, complete these steps:

Contact your Amazon representative to enable Quick Subscribe.
Configure Quick Subscribe in the Developer Console.
Configure a security profile in the Developer Console.
If you haven't already done so, integrate the IAP APIs and make sure to handle getPurchaseUpdates in the app's onResume() method.
Call the notifyFulfillment() API after a customer signs in to the app after a Quick Subscribe purchase. A customer who doesn't sign in to the app within 30 days of purchase automatically has their subscription canceled and refunded. For more information about the notifyFulfillment() API, see Grant the item to the user.
Integrate with Real Time Notifications (RTN) and Receipt Verification Service (RVS). RTN and RVS provide you with more notifications, allowing you to better manage subscriptions.
Integrate one-click account creation.

See the following sections for more details about the required steps.

To configure Quick Subscribe for your app, follow these steps.

Sign in to the Developer Console.
In your app list, find the app you want to set up with Quick Subscribe.
In the In-App Items column, click the link to open the In-App Items screen.
Select Create Quick Subscription.
An overlay pop-up appears. In the Choose default subscription drop down, the list is populated with your existing IAP subscriptions. Choose the subscription on which you want to enable Quick Subscribe.
In the Select term drop down, choose a term for the quick subscription.
If you would like to offer additional subscriptions for Quick Subscribe, select Add another quick subscription. You can add a maximum of four quick subscriptions.
Choose your target devices for Quick Subscribe by checking the boxes.
Select Create Quick Subscription.

After you have created a quick subscription, you can delete or modify it by selecting Actions next to the Quick Subscribe item.

Configure security profile in the Developer Console

To configure a security profile for your app, follow these steps.

Sign in to the Developer Console.
Open the app list and select your app.
Select App Services and scroll to the Security Profile section.
Click Select existing security profile or create new to expand the options.
Use the drop-down to select the security profile that you want to map to this app, then click Enable Security Profile. Alternatively, you can create a new security profile by clicking Create Security Profile.

Handle getPurchaseUpdates

Important: If you already use In-App Purchasing, you likely have integrated getPurchaseUpdates() as part of your IAP setup. If not, you must call getPurchaseUpdates() in the onResume() method to properly implement Quick Subscribe.

The getPurchaseUpdates() method gets the user's receipts. Quick Subscribe uses the information from getPurchaseUpdates() to verify your user's purchase status, ensuring that the user has access to the content to which they are entitled.

Call getPurchaseUpdates() in the onResume() method. The getPurchaseUpdates() method takes one boolean parameter, reset. 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.

@Override
protected void onResume() {
  super.onResume();

//...

  PurchasingService.getUserData();

//...

  PurchasingService.getPurchaseUpdates(false);
}

For more information on how to integrate the getPurchaseUpdates() method, see IAP API documentation:

Android—Implement getPurchaseUpdates method
Web app—getPurchaseUpdates(reset)

Acknowledge Receipt API

Note: If this is the first time you're adding Quick Subscribe to your app, use the notifyfufillment() API included in the Appstore SDK rather than the Acknowledge Receipt API. If you've already integrated the Acknowledge Receipt API, you can continue to use it.

Amazon uses auto-cancellation to ensure that customers don't continue to pay for subscriptions that aren't entitled to them. A customer who doesn't log into the app within 30 days of purchase automatically has their subscription canceled and refunded. Consider a case where a customer has intentionally made a purchase and accessed the subscription, but an acknowledge notification is missing, or a delay occurs. In this case, that customer would lose access to the subscription 30 days from the purchase date through auto-cancellation. Calling the Acknowledge Receipt API prevents this from occurring.

The Acknowledge Receipt API uses the acknowledgeReceipt operation which allows you to notify Amazon that a subscription purchase has been fulfilled, so customers won't lose access.

The acknowledgeReceipt operation is a REST API, much like the verifyReceiptId operation used in RVS, but you must use a PUT request, rather than a GET request.

PUT https://appstore-sdk.amazon.com/version/1.0/acknowledgeReceipt?developer={Shared_secret}&user={UserId}=&receiptId={ReceiptId}&fulfillmentResult={FulfillmentResult}

The version number of the acknowledgeReceipt operation is 1.0. For more details on the query parameters, review the following table.

Query parameters

The Acknowledge Receipt API response uses the following query parameters.

Query Parameter	Description	Required
developer	The shared secret used to identify the developer issuing the request. Your shared secret can be found on the Shared Key page for your developer account with the Amazon Appstore.	Yes
user	ID representing a distinct Amazon customer for your Appstore app: `PurchaseResponse.getUserData().getUserId()`.	Yes
receiptId	Unique ID for the purchase: `PurchaseResponse.getReceipt().getReceiptId()` or `PurchaseUpdatesResponse.getReceipts()` → `Receipt.getReceiptId()`.	Yes
fulfillmentResult	The status of Fulfillment. Valid Values: `FULFILLED`: You provided the content and the customer consumed the content. `UNAVAILABLE`: You were unable to provide the content to the customer. Sending this value doesn't immediately cancel the order. It will be canceled and refunded after 30 days.	Yes

Response codes

After making the HTTP request, the Acknowledge Receipt API responds with one of the following codes.

Response Code	Description
HTTP 200	Success: The Receipt ID, User ID, and shared secret are all valid. The subscription is marked as fulfilled.
HTTP 400	The transaction represented by this receiptId is invalid, or no transaction was found for this receiptId.
HTTP 410	The transaction represented by this receiptId is no longer valid. Treat it as a canceled receipt.
HTTP 429	The request was throttled. Reduce your calling rate and retry after some time.
HTTP 496	Invalid sharedSecret
HTTP 497	Invalid User ID
HTTP 500	There was an Internal Server Error

Acknowledge Receipt FAQ

The following are frequently asked questions (FAQ) about the Acknowledge Receipt API.

Q: Should the Acknowledge Receipt API be called after every renewal, or only after purchase?: You should call the Acknowledge Receipt API after a quick subscribe enabled purchase.
Q: What response is sent if the Acknowledge Receipt API is invoked with status FULFILLED when it has already been acknowledged?: Calling the Acknowledge Receipt API multiple times with status FULFILLED is an idempotent operation, and you get the same response every time.
Q: Is there a way to revert the acknowledgeReceipt operation? Can the status of acknowledgeReceipt be set to UNAVAILABLE if it's already updated to FULFILLED?: No, the status of acknowledgeReceipt can transition from UNAVAILABLE to FULFILLED but not from FULFILLED to UNAVAILABLE. If you realize an error in the receipt, Contact Us to request help.

Integrate with RTN and RVS

With Quick Subscribe, customers subscribe to your app through Amazon, rather than through your app. This could lead to your app missing some information about a customer's purchase state. The getPurchaseUpdates() API only sends data when an app is opened.

Real Time Notifications (RTN) provides customer purchase information for all transactions, including the ones that occur outside your app. When your server receives a purchase notification from Amazon's RTN server, use the Receipt Verification Service (RVS) to validate the receipt. When you make a request to the RVS server, the JSON response returned includes a purchaseMetadataMap field. If the purchase was initiated using Quick Subscribe, the purchaseMetadataMap appears as {"QuickSubscribe":"true"}, as seen in the following example.

{
  "autoRenewing": true,
  "betaProduct": false,
  "binCountryCode": null,
  "cancelDate": 1641131573000,
  "cancelReason": 2,
  "deferredDate": null,
  "deferredSku": null,
  "freeTrialEndDate": null,
  "fulfillmentDate": 1641131345000,
  "fulfillmentResult": "FULFILLED",
  "gracePeriodEndDate": null,
  "parentProductId": null,
  "productId": "IntroFreeTrial.sku",
  "productType": "SUBSCRIPTION",
  "promotions": null,
  "purchaseDate": 1641131345000,
  "purchaseMetadataMap": {
      "QuickSubscribe": "true"
  },
  "quantity": null,
  "receiptId": "k9om1rUS7gZJIg8RMfw7AlbxA3aP56ay-vdgeLU40zw=:3:11",
  "renewalDate": null,
  "term": "1 Month",
  "termSku": null,
  "testTransaction": false
}

If the purchase wasn't initiated using Quick Subscribe, purchaseMetadataMap appears as null. The following table provides a description for all fields in the response object.

Field	Data Type	Description
`autoRenewing`	Boolean	Indicates if customer's subscription will auto renew.
`betaProduct`	Boolean	Indicates whether the product purchased is a Live App Testing product.
`cancelDate`	Long integer	The date the purchase was canceled, or the subscription expired. The field is null if the purchase was not canceled. Time is in milliseconds.
`cancelReason`	Integer	Indicates why a product was canceled. Possible values are null, 0, 1, or 2, where each integer represents a cancellation reason: `null` - The purchase was not canceled. `0` - The cancel reason is currently unavailable and will render at a later time. `1` - Your customer canceled the order. `2` - The purchase was canceled by Amazon's system. For example, a customer purchases a subscription with an invalid payment and the purchase could not be completed in the grace period. This code is also returned if Amazon customer support canceled the order at the request of a customer.
`freeTrialEndDate`	Long integer	Indicates that the subscription is in a free trial. Provides the free trial end date of the subscription in epoch (milliseconds). The field is null if the subscription is not in a free trial period.
`fulfillmentDate`	Long integer	In a subscription purchase, the date of the acknowledgement of fulfillment. Stored as the number of milliseconds since the epoch. Null if subscription fulfillment isn't confirmed. Always null for consumables and entitlements.
`fulfillmentResult`	String	In a subscription purchase, the status of fulfillment. Valid values: `FULFILLED`: You provided the content and the customer consumed the content. `UNAVAILABLE`: You were unable to provide the content to the customer. Null if subscription fulfillment isn't confirmed. Always null for consumables and entitlements.
`gracePeriodEndDate`	Long integer	Indicates that the subscription is in grace period. Provides the grace period end date of the subscription in epoch (milliseconds). The field is null if the subscription is not in a grace period.
`parentProductId`	String	Null. Reserved for future use.
`productId`	String	The SKU that you defined for this item in your app.
`productType`	String	Type of product purchased. Valid product types are `CONSUMABLE`, `SUBSCRIPTION`, and `ENTITLED`.
`promotions`	List<Promotion>	Details of the promotional pricing of subscription purchase. Null if there is no promotion. See Promotional pricing in RVS.
`purchaseDate`	Long integer	The date of the purchase, stored as the number of milliseconds since the epoch. For subscription items, `purchaseDate` represents the initial purchase date, not the purchase date of subsequent renewals.
`purchaseMetadataMap`	Map <String, String>	If the purchase was initiated via Quick Subscribe, the value is `{"QuickSubscribe":"true"}`. Otherwise null.
`quantity`	Integer	Quantity purchased. Always null or 1.
`receiptId`	String	Unique identifier for the purchase.
`renewalDate`	Long integer	The date that a subscription purchase needs to be renewed. The date is stored as the number of milliseconds since the epoch.
`term`	String	Duration that a subscription IAP will remain valid (the term starts on the date of purchase). The term consists of a number and a time period (Day, Week, Month, Year), such as 1 Week or 2 Months.
`termSku`	String	Unique SKU that corresponds to the subscription term.
`testTransaction`	Boolean	Indicates whether this purchase was made as a part of Amazon's publishing and testing process.

For more details on RVS, see Receipt Verification for IAP Apps.

Integrate one-click account creation

Use this guide to integrate your app with the one-click account creation feature.

Pre-requisites

Integrate with the Login with Amazon SDK. For details, see Install the Login with Amazon SDK for Android.
Integrate with the Appstore SDK version 3.0.5 or higher. For details, see Integrate the Appstore SDK.

Update app manifest

To indicate to the Appstore that your app supports the one-click account creation feature, update your app's manifest with the following code.

<uses-feature android:name="amazon.lwa.quicksignup.supported"/>

To determine if a customer provided consent to share their Amazon account details, in the onCreate method of your app's main activity, call the getUserData() method with the setFetchLWAConsentStatus() flag of the UserDataRequest object set to true.

The following example shows how to build a UserDataRequest object and pass it to getUserData() when the customer has given consent to Login with Amazon (LWA) to obtain their details.

@Override
protected void onCreate(Bundle savedInstanceState) 
{
  super.onCreate(savedInstanceState);

//...

  PurchasingService.registerListener(this.getApplicationContext(), purchasingListener);
  if (!isLoggedIn()) {
     PurchasingService.getUserData(UserDataRequest.newBuilder().setFetchLWAConsentStatus(true).build());
  }
//...
}

If a customer provided their consent, the LWAConsentStatus of the UserData object has the status CONSENTED. If a customer hasn't provided consent or if the consent token expired, LWAConsentStatus has the status UNAVAILABLE.

Note: A consent token expires after the first query or on device restart.

The following code shows how to handle the consent data received from the UserDataResponse object.

@Override
public void onUserDataResponse( final UserDataResponse response) {

 final UserDataResponse.RequestStatus status = response.getRequestStatus();

 switch (status) {
   case SUCCESSFUL:
     if (LWAConsentStatus.CONSENTED.equals(response.getUserData().getLWAConsentStatus())) {
        lwaManager.startAutoLoginWorkflow();
     }
     break ;

   case FAILED:
   case NOT_SUPPORTED:
     // Fail gracefully.
     break ;
 }
}

If the customer provides consent, call the authorize() method from LWA to start a session and call the User.fetch() method to get customer details. Create an account in your back-end system with the user information shared.

The following code shows how to use the LWAManager to enable automatic sign in for a customer who has provided consent.

//..
private RequestContext requestContext;
private Context context;
//..

LWAManager(RequestContext requestContext, Context context) {
   this.requestContext = requestContext;
   this.context = context;
   requestContext.registerListener(new AuthorizeListener() {
      //..
      @Override
      public void onSuccess(AuthorizeResult authorizeResult) {
           fetchUserProfileInfo();
      }
      
      //..
   });
}

public void startAutoLoginWorkflow() {
    AuthorizationManager.authorize(
          new AuthorizeRequest.Builder(requestContext)
                  .addScopes(ProfileScope.profile(), ProfileScope.postalCode())
                  .build()
   );
           
}

private void fetchUserProfileInfo() {
    User.fetch(context, new Listener<User, AuthError>() {
      //..
      
      @Override
      public void onSuccess(User user) {
          final String name = user.getUserName();
          final String email = user.getUserEmail();
          final String zipCode = user.getUserPostalCode();
          
          // Create or map account in your back end and sign in customer
      }
      
      //..
   });

}

If the customer doesn't provide consent, show the sign-in screen with a Login with Amazon button. The customer can then enter their credentials using the keyboard or use the Login with Amazon button to sign in to your app.

Flow diagram

The following diagram shows the code flow for Quick Subscribe with one-click account creation.

You can test Quick Subscribe using Live App Testing (LAT). To do this, ask your Amazon representative to enable Quick Subscribe for your LAT app ASIN. You can test the Quick Subscribe flow through either the Amazon retail website, or on a Fire TV device. When you start a live app test, you can send invitations to testers. Testers receive an email with a link to the Amazon website with the LAT version of the app.

From the LAT invitation email, select the Amazon website for your marketplace. On the app detail page, select the subscription option, which appears as a paid option for a subscription term, such as $20.00 monthly. Then, select a device to deliver to, and click Get App.

To get started with testing Quick Subscribe on the device, you can use the LAT invitation email or the device notification.

To test from the LAT invitation:

Use the link in the invitation email to go to the app detail page on the Amazon website.
Select the App Only option.
In the Deliver to: drop-down menu, select Cloud Only.
Click Get App.
On a Fire TV device associated with the Amazon account, click the icon for Your Apps & Channels (the icon appears on the navigation bar as three squares and a plus sign).
Find the LAT version of your app, which has a TEST banner on the app icon. You might need to click App Library to see the app.
Select the app icon to open the app detail page on the device.
Select Subscription Options and download the app.

To test from the notification:

After you send a LAT invite, the test devices associated with the tester email receive a notification. If you open the notification when it appears, you are taken to the LAT app detail page. This notification appears for 5-10 seconds. If you miss the notification when it first appears, you can click the settings icon (the gear icon) and select Notifications to see it. You can then read the notification and go to the app detail page. Select Subscription Options and download the app.

Important

Testing Quick Subscribe through LAT isn't supported in the following cases:
- Using the App Only option on the website when you choose a specific device to deliver to.
- Using the App Only option on a device.
To test the app through LAT for a purpose other than Quick Subscribe, you can use the App Only option and select a specific device to deliver the app to.
Turn off accelerated subscriptions while testing Quick Subscribe.
To reset Quick Subscribe for a test account, contact your Amazon representative, or go to the Developer Console to reset subscriptions for LAT. For details, see Reset in-app items for all testers in the LAT or Manage individual testers.
If you want to accelerate the 30-day cancellation window to a 1-day window for testing, contact your Amazon representative.

The following are frequently asked questions (FAQ) about Quick Subscribe.

Q: Is Amazon mandating that developers remove app account creation to use Quick Subscribe?: No, the initial launch of Quick Subscribe does not support skipping app account creation.
Q: Can I offer Quick Subscribe if I also offer a free trial?: Yes, you can offer both Quick Subscribe and a free trial on the same subscription product. However, Quick Subscribe doesn't support 60-day free trials.
Q: What if my customer used a free trial previously?: Quick Subscribe can detect a free trial created previously on the Amazon Appstore and does not allow the customer to enter into an additional trial period. However, if the customer started a trial outside of Amazon, Quick Subscribe cannot detect this information and the customer may enter into an additional free trial.
Q: What happens if a customer purchases a subscription through Quick Subscribe and wants to download the app on a second device?: The subscription is added to the customer's account after they subscribe through Quick Subscribe. Customers can use the "app only" option to download the app on additional devices. Customers can then access their subscription on those devices.
Q: Can I offer Quick Subscribe if I also offer promotional pricing?: Yes, you can offer both Quick Subscribe and promotional pricing on the same subscription product. However, Quick Subscribe doesn't support promotional pricing at weekly or biweekly intervals.

One-click account creation FAQ

Q: Do I need to integrate my server with Login with Amazon (LWA) for OAuth?: No, you only need to integrate with LWA in your app. Use the data your app retrieves to create a customer account. Manage future sign-ins for customers with your account management system.
Q: What is the difference between the Acknowledge Receipt API and the notifyFulfillment() API? Do I need to integrate with both?: The notifyFulfillment() method is a client-side API included in the Appstore SDK that confirms fulfillment of an item. The Acknowledge Receipt API achieves the same objective but through a server-to-server call using the acknowledgeReceipt operation. The Appstore strongly recommends that you implement the notifyFulfillment() API in your app. If you haven't implemented notifyFulfillment(), you can use the Acknowledge Receipt API on the sever side as a back-up option.
Q: What is the experience for a customer who uses Login with Amazon (LWA) with only a mobile number?: If a customer uses LWA with only a mobile number, LWA returns an empty email and the app must fall back to the default sign-in experience.
Q: What if I need information in addition to email, name, and zip code to create an account?: If you need additional information, your app must request the required information from customer.
Q: Does IAP SDK v2.0 support one-click account creation?: No. You must integrate with the Appstore SDK to use one-click account creation. If your app uses Quick Subscribe with IAP SDK v2.0, you must upgrade to the Appstore SDK. One-click account creation is supported in the Appstore SDK v3.0.5 and higher.
Q: Can I test one-click account creation with Live App Testing (LAT)? Can I reset consent of LAT testers to restart testing?: Yes, you can test one-click account creation with LAT. To reset consent, the LAT tester must go to Manage Login with Amazon and click Remove in the Manage Connection column. There isn't an option to revoke consent status in bulk.
Q: Can I test one-click account creation using App Tester?: You can use App Tester to mock the consent status attribute of the getUserData() API. To test your integration, set the response for consent status to CONSENTED or UNAVAILABLE. If the returned status is CONSENTED, your app should call Login with Amazon APIs to fetch customer data and automatically sign them in. If the returned status is UNAVAILABLE, your app should fall back to the default sign-in experience.

Last updated: Mar 27, 2024

Set Up Quick Subscribe

User flow comparison

How does Quick Subscribe work?