Use In-Skill Product Service APIs

Note: Sign in to the developer console to build or publish your skill.

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