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