Set Up Quick Subscribe
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 consolidated and streamlined experience with app download, subscription purchase, and entitlement creation.

- User flow comparison
- How does Quick Subscribe work?
- Set up Quick Subscribe
- Test Quick Subscribe with LAT
- Quick Subscribe FAQs
User flow comparison
Without Quick Subscribe, users experience a sign in flow that bounces between Fire TV devices and third party screens. These steps describe a typical user experience when signing up for a subscription on a Fire TV:

Quick Subscribe reduces steps for users. These steps describe the user experience when signing up for a subscription on Fire TV with Quick Subscribe:

When a user chooses to subscribe, the app automatically downloads so they can enjoy content. Amazon submits the user's information to your app. Your app then creates an account for the user. Quick Subscribe uses the In App Purchasing (IAP) API to verify your user's purchase history and status.
How does Quick Subscribe work?
The following diagram demonstrates how Quick Subscribes works with Fire devices, In-App Purchasing (IAP), and your app and back-end server. See the step breakdown below for detailed information about the processes.

Step 1: The customer initiates a subscription purchase from the app detail page in the Amazon Appstore.
Step 2: Amazon informs the customer their purchase is complete.
Step 3: The app automatically downloads and the customer launches the app on their device.
Step 4: On launch, the app calls the getPurchaseUpdates()
method from Amazon's IAP API and Amazon returns the purchase data to the app.
Step 5: You update your back-end server with the purchase data and verify it with the Receipt Verification Service (RVS) by calling verifyReceiptId
.
Step 6: You allow the customer access to the content.
Step 7: You call acknowledgeReceipt
using the Acknowledge Receipt API to confirm the customer has accessed the content.
Set up Quick Subscribe
To get started with Quick Subscribe, complete four required steps:
- Contact your Amazon representative to enable Quick Subscribe.
- Configure Quick Subscribe in the Developer Console.
- If you haven't already done so, integrate the
getPurchaseUpdates()
API into your app. - Call the Acknowledge Receipt API after a customer logs into the app after a Quick Subscribe purchase. A customer who doesn't log into the app within 30 days of purchase automatically has their subscription canceled and refunded.
Additionally, there is one optional, but highly recommended step:
- 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.
See the following sections for more details about required and optional steps.
Configure Quick Subscribe in the Developer Console
To configure Quick Subscribe for your app, follow these steps.
- Log 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, select the items to open the IAP 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 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.
Integrate getPurchaseUpdates
getPurchaseUpdates()
as part of your IAP set up.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 they are entitled to access.
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)
Call the Acknowledge Receipt API
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 is a required step that 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:
|
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 FAQs
This section provides answers to questions and concerns 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 ofacknowledgeReceipt
be set toUNAVAILABLE
if it's already updated toFULFILLED
? - No, the status of
acknowledgeReceipt
can transition fromUNAVAILABLE
toFULFILLED
but not fromFULFILLED
toUNAVAILABLE
. If you realize an error in the receipt, Contact Us to request help.
Recommended - 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:
|
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, Boolean> | 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.
Test Quick Subscribe with LAT
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.
Test Quick Subscribe on the website
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.
Test Quick Subscribe on the device
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.
Quick Subscribe FAQs
This section provides answers to common questions and concerns 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.
Last updated: Oct 27, 2023