Developer Console
Sign In
Sign In
Developer Console

RVS for Consumables and Entitlements

The Receipt Verification Service (RVS) for the Appstore Billing Compatibility SDK lets you validate purchases made by your app's users. For an overview of RVS, see Receipt Verification Service Overview.

RVS for the Appstore Billing Compatibility SDK has two REST APIs, one for verifying consumable and entitlement purchases, and another for verifying subscription purchases. This page describes the requests and responses of the REST API used for consumable and entitlement purchases.

purchases.products.get API request

Use the purchases.products.get API to verify the receipts of consumable or entitlement purchases made through the Appstore Billing Compatibility SDK. Upon successful purchase of an item, the Appstore Billing Compatibility SDK returns a Purchase object. To perform a server-side validation of the purchase, extract the purchase token from this object and pass it, along with the app package name, the product ID (the SKU value you used to create the in-app item), and your shared secret to the RVS server. For security, when you make a request from your server, you must pass a shared secret to confirm your identity.

The request uses the following format:

https://appstore-sdk.amazon.com/version/{operation-version-number}/get/developer/{shared-secret}/applications/{package-name}/purchases/products/{product-id}/tokens/{token}

The curly brackets contain placeholders for the request parameters. In your request, replace the placeholders with the values from the transaction you want to verify. The following table lists descriptions of the request parameters.

Request parameter Description
operation-version-number Version number of the purchases.products.get operation. This version number is independent of the Appstore Billing Compatibility SDK version number. The current purchases.products.get version number is "1.0".
shared-secret Shared secret used to identify the developer issuing the request. Your shared secret can be found on the Shared Key page in the Developer Console: https://developer.amazon.com/sdk/shared-key.html.
package-name The package name of the application in which the in-app product was sold. For example, 'com.amazon.sample.iap.consumable'. You can get the package name from your app by calling getApplicationContext().getPackageName() or you can find it in the AndroidManifest.xml file.
product-id The in-app product SKU that you created for your app in the Developer Console. For example 'iapsamplev2.gold_medal'. For a subscription product, use the term SKU. You can fetch the product ID from the Purchase object using the Purchase.getSkus().get(0) method.
token Unique ID for the purchase obtained from the Purchase object's getPurchaseToken() method.

purchases.products.get API response

The purchases.products.get API provides a RESTful JSON API interface. As a best practice, use a JSON parser class, such as OkHttp or Apache HttpClient, for reading the JSON responses from the RVS server.

After you make a request to the RVS server to verify a transaction, the RVS server returns a response code indicating if the request was successful. If successful, the returned JSON response includes information about the transaction.

The following example shows a successful response:

{
    "cancelDate": null,
    "cancelReason": null,
    "kind": "androidpublisher#productPurchase",
    "parentProductId": null,
    "productId": "com.amazon.iapsamplev2.expansion_set_1",
    "productType": "ENTITLED",
    "purchaseState": 0,
    "purchaseTimeMillis": "1399070753509",
    "purchaseToken": "mINy5VRd1FqjVOz-WBtTqw9FBGWhnuVx07kzTBMR600=:2:11",
    "purchaseType": null,
    "quantity": 1,
    "testTransaction": false
}

Response codes and error messages

The Receipt Verification Service responds with one of the following codes, which indicate the result of the validation check.

HTTP response code Description
200 The purchase is valid.
400 The purchase token or product ID is invalid.
401 The developer secret is invalid or doesn't match the given purchase token.
404 The package name is invalid or doesn't match the given purchase token.
410 The transaction represented by this receiptId is no longer valid. Treat it as a canceled receipt.
429 The request was throttled. Reduce your calling rate and retry after some time.
500 There was an Internal Server Error.

Response fields for successful transactions

The following table describes the fields included in a purchases.products.get response for a successful transaction. Some fields have the same name and data type as Google's purchases.products.get API. Those fields are listed under Fields that match Google's purchases.products.get API. Fields listed under Additional fields are different from Google APIs and present purchase details provided by the Amazon Appstore.

Field Data type Description
Fields that match Google's purchases.products.get API
kind String Represents a ProductPurchase object in the androidpublisher service.
purchaseTimeMillis String The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).
purchaseState Integer The purchase state of the order. Possible values:
0 - Purchased
1 - Canceled
purchaseType Integer The type of purchase of the in-app product. This field is set only if this purchase wasn't made using the standard in-app purchase flow. Possible value:
0 - Test (purchased from a license testing account).
purchaseToken String Unique identifier for the purchase.
productId String The SKU that you defined for this item in your app.
quantity Integer Quantity purchased. Always null or 1.
Additional fields
parentProductId String Null. Reserved for future use.
productType String Type of product purchased. Valid product types are CONSUMABLE and ENTITLED.
cancelDate Long integer The date the purchase was canceled. Time is in milliseconds. In a valid receipt, the cancel date contains the null value. If the cancel date field is not null, it contains the date that Amazon customer service canceled the purchase.
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. This code is also returned if Amazon customer support canceled the order at the request of a customer.
testTransaction Boolean Indicates whether this purchase was made as a part of Amazon's publishing and testing process.

Unsupported fields for purchases.products.get API

The following fields that are available in the Google Play Developer API, aren't supported in the Appstore Billing Compatibility RVS API.

  • consumptionState
  • regionCode
  • orderId
  • developerPayload
  • acknowledgementState
  • obfuscatedExternalAccountId
  • obfuscatedExternalProfileId

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 4.0 Attribution License. Sources: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/get, https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products.

Last updated: Oct 14, 2024