アクセスいただきありがとうございます。こちらのページは現在英語のみのご用意となっております。順次日本語化を進めてまいりますので、ご理解のほどよろしくお願いいたします。

In-Skill Product Service

These APIs provide skill developers with the ability to get information about in-skill products that a user can purchase or has already purchased.

Host endpoint

The host for all calls to the in-skill product APIs is the value of the apiEndpoint field of the System.Object.

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 HTTP/1.1
Host: api.amazonalexa.com
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; either a subscription or entitlement. No String either 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 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 an list of products. The InSkillProduct fields referenceName, type, name, and summary are set when you create the ISP with the ASK CLI. 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

{
  "inSkillProducts":[
      {
          "productId": "amzn1.adg.product.some-id",
          "referenceName": "ProductName",
          "type": "SUBSCRIPTION",
          "name": "Friendly Name",
          "summary": "Description of the product.",
          "entitled": "NOT_ENTITLED",
          "purchasable": "PURCHASABLE"
      }
  ],
  "isTruncated": true,
  "nextToken": "String"
}

Get an in-skill product by product ID

Gets a the specified in-skill product for a specified user and skill.

Request

Authorization: Bearer {event.context.System.apiAccessToken} 
Accept-Language: {event.request.locale}
Host: api.amazonalexa.com

GET  /v1/users/~current/skills/~current/inSkillProducts/{productId}

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 Requested resource not found. 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.some-id",
          "referenceName": "ProductName",
          "type": "SUBSCRIPTION",
          "name": "Friendly Name",
          "summary": "Description of the product.",
          "entitled": "NOT_ENTITLED",
          "purchasable": "PURCHASABLE"
      }
  ],
  "isTruncated": true,
  "nextToken": "String"
}
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.some-id",
          "type": "SUBSCRIPTION",
          "name": "Friendly Name",
          "summary": "Description of the product.",
          "entitled": "NOT_ENTITLED",
          "purchasable": "PURCHASABLE"
}
Name Type Description Required
productId String Product identifier Yes
name String Name of the product in the language from the "Accept-Language" header Yes
type String enumeration value Product type, either SUBSCRIPTION or ENTITLEMENT Yes
summary String Product summary in the language from the Accept-Language header Yes
purchasable String String that indicates if product can be purchased by this user. Either PURCHASABLE or NON_PURCHASABLE. Yes
entitled String Enumeration value that indicates if this user is entitled to the product. Either ENTITLED or NOT_ENTITLED. 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.
  • 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.