Use In-Skill Product Service APIs
Use these APIs to get information about in-skill products that a user can purchase or has already purchased at skill runtime.
Host endpoint
The host for all calls to the in-skill product APIs is the value of the apiEndpoint field of the System.Object. Example: api.amazonalexa.com
.
Get all in-skill products
Gets all of the products available for purchase in this skill and whether the items have been purchased by this user.
Request
GET /v1/users/~current/skills/~current/inSkillProducts
Host: {event.context.System.apiEndpoint}
Accept-Language: {event.request.locale}
Authorization: Bearer {event.context.System.apiAccessToken}
Parameters
Name | Located in | Description | Required | Schema |
---|---|---|---|---|
authorization |
header | Access token used for authentication and authorization. This is passed to the user in the SPI call. | Yes | String |
Accept-Language |
header | User's locale/language in context | Yes | String |
purchasable |
query | Filter products based on whether they are purchasable by the user. | No | String either PURCHASABLE or NOT_PURCHASABLE |
entitled |
query | Filter products based on whether the user is entitled to the product. | No | String either ENTITLED or NOT_ENTITLED |
productType |
query | Product type; consumable, subscription or entitlement. | No | String CONSUMABLE, SUBSCRIPTION, or ENTITLEMENT |
nextToken |
query | Indicates the response is truncated. The token value is used in the next request as the continuation-token to list the next set of objects. This token is an opaque value intended for use by the service. Token expires in 24 hours. | No | String |
maxResults |
query | Sets the maximum number of results returned in the response body. Set this value to retrieve less than the upper limit of 100. If there are additional results that satisfy the search criteria, but they were not returned because maxResults was exceeded, the response contains isTruncated = true . |
No | Number between 1 and 100 |
Response
Code | Description | Schema |
---|---|---|
200 | Returns a list of In-Skill products on success. | InSkillProductsResponse |
400 | Invalid request | Error |
401 | The authentication token is invalid or doesn't have access to make this request | Error |
500 | Internal Server Error | Error |
A successful response will contain an object, inSkillProducts, which contains a list of products. The InSkillProduct fields referenceName
, type
, name
, and summary
are set when you create the ISP. The productId
is guaranteed to be unique and should be used for initiating product offer. Only products with a purchasable
value of PURCHASABLE
should be offered to the user. It is set based on a variety of inputs including the user's country/region of residence and the device from which the request was made. Users should only be given access to the premium content if the value of entitled is set to ENTITLED
.
Sample 200 response
In this sample response, the skill has three products – one entitlement, one subscription, and a consumable. The user has purchased the subscription and two units of the consumable.
{
"inSkillProducts": [
{
"productId": "amzn1.adg.product.unique-id-1",
"referenceName": "your_product_name_1",
"type": "ENTITLEMENT",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "NOT_ENTITLED",
"purchasable": "PURCHASABLE",
"activeEntitlementCount": 0,
"purchaseMode": "TEST"
},
{
"productId": "amzn1.adg.product.unique-id-2",
"referenceName": "your_product_name_2",
"type": "SUBSCRIPTION",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "ENTITLED",
"purchasable": "NOT_PURCHASABLE",
"activeEntitlementCount": 1,
"purchaseMode": "TEST"
},
{
"productId": "amzn1.adg.product.unique-id-3",
"referenceName": "your_product_name_3",
"type": "CONSUMABLE",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "ENTITLED",
"purchasable": "PURCHASABLE",
"activeEntitlementCount": 2,
"purchaseMode": "TEST"
}
],
"nextToken": null,
"truncated": false
}
Get an in-skill product by product ID
Gets a the specified in-skill product for a specified user and skill.
Request
GET /v1/users/~current/skills/~current/inSkillProducts/{productId}
Host: {event.context.System.apiEndpoint}
Accept-Language: {event.request.locale}
Authorization: Bearer {event.context.System.apiAccessToken}
Parameters
Name | Located in | Description | Required | Type/Schema |
---|---|---|---|---|
Authorization |
header | access token used for authentication and authorization. This is provided in the System.Object of the incoming message. | Yes | String |
Accept-Language |
header | User's locale from the Launch or Intent request | Yes | String |
productId |
path | Product Id. | Yes | String |
Response
Code | Description | Type/Schema |
---|---|---|
200 | Returns the specified in skill product on success. | InSkillProduct |
400 | Invalid request. | Error |
401 | The authentication token is invalid or doesn't have access to make this request | Error |
404 | The requested productId is not available for discovery. This may happen if you have published an updated version of the skill with product that has not yet been fully provisioned in production (rare). | Error |
500 | Internal Server Error. | Error |
Type schemas
Error
Name | Type | Description | Required |
---|---|---|---|
message |
String | Readable description of error | No |
InSkillProducts
{
"inSkillProducts": [
{
"productId": "amzn1.adg.product.unique-id-1",
"referenceName": "your_product_name_1",
"type": "ENTITLEMENT",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "NOT_ENTITLED",
"purchasable": "PURCHASABLE",
"activeEntitlementCount": 0,
"purchaseMode": "TEST"
}
],
"nextToken": null,
"truncated": false
}
Name | Type | Description | Required |
---|---|---|---|
inSkillProductsResponse |
A list of InSkillProduct objects | A list of products for this skill. | No |
isTruncated |
String | True to indicate the results are truncated across multiple responses; otherwise false. | Yes |
nextToken |
String | When response to this API call is truncated (that is, isTruncated response element value is true), the response also includes the nextToken element, the value of which can be used in the next request as the continuation-token to list the next set of objects. The continuation token is an opaque value that In-Skill Products API understands. Token has expiry of 24 hours. |
No |
InSkillProduct
{
"productId": "amzn1.adg.product.unique-id-1",
"referenceName": "your_product_name_1",
"type": "ENTITLEMENT",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "NOT_ENTITLED",
"purchasable": "PURCHASABLE",
"entitlementReason": "NOT_PURCHASED",
"activeEntitlementCount": 0,
"purchaseMode": "TEST"
}
Name | Type | Description | Required |
---|---|---|---|
productId |
String | Product identifier, guaranteed to be unique. Used for initiating product offers and purchases. | Yes |
referenceName |
String | The name of the product, as provided by you when you created the product. | Yes |
type |
String enumeration value | Product type. Can be CONSUMABLE , SUBSCRIPTION or ENTITLEMENT |
Yes |
name |
String | Name of the product in the language from the Accept-Language header |
Yes |
summary |
String | Product summary in the language from the Accept-Language header. This is the summary that you provided in the one-sentence description for the product. |
Yes |
entitled |
String | Enumeration value that indicates if this user is entitled to the product. Either ENTITLED or NOT_ENTITLED . |
Yes |
entitlementReason |
String | Enumeration value that indicates the reason for the entitlement status. Possible values are PURCHASED (the user has purchased the product), NOT_PURCHASED (the user has not purchased the product), or AUTO_ENTITLED (the user is automatically entitled to the product, for example by subscribing to a service that includes the product). |
Yes |
purchasable |
String enumeration value | Indicates if product can be purchased by this user. Either PURCHASABLE or NOT_PURCHASABLE . |
Yes |
activeEntitlementCount |
Integer | Number of entitlements the user has to this product. For a CONSUMABLE , this is the total number of times the user purchased the product. Note that this does not reflect the user's consumption of the purchased units, so you must manage the user's inventory. For a SUBSCRIPTION or ENTITLEMENT , this is always either 0 or 1. |
Yes |
purchaseMode |
String enumeration value | Indicates the environment in which this purchase was made. Either TEST (for development or beta test purchases) or LIVE (for purchases in live skills) |
Yes |
Enumeration Value Definitions
SUBSCRIPTION
: Once purchased, customers will own the content for the subscription period.ENTITLEMENT
: Once purchased, customers will own the content forever.CONSUMABLE
: Once purchased, customers can consume the content and purchase it again. Customers can stack multiple purchases of the product.PURCHASABLE
: The product is purchasable by the user.NOT_PURCHASABLE
: The product is not purchasable by the user.ENTITLED
: The user is entitled to the product.NOT_ENTITLED
: The user is not entitled to the product.TEST
: The user made this purchase in a test environment (development stage skill or beta test).LIVE
: The user made this purchase in a live skill.
Last updated: Mar 29, 2022