In-Skill Product Management
The In-Skill Product Management API allows developers to manage the in-skill products in their skills via APIs. You can create, update, and list in-skill products. You can also create and manage in-skill product and skill associations.
The API's endpoint is https://api.amazonalexa.com. Each API request must have an Authorization
header whose value should be the access token retrieved from Login with Amazon. The authentication mechanism is the same as for other Skill Management APIs.
See also:
- In-Skill Purchasing Overview
- Create and Edit In-Skill Products with the ASK CLI
- Create and Edit In-Skill Products in the Developer Console
- Alexa Skills Kit Command Line Interface (ASK CLI) Overview
- Pagination and filtering of results
- Get in-skill product definition
- Create a new in-skill product
- Get the summary information for an in-skill product
- Update an existing in-skill product
- Delete an existing in-skill product
- Get a list of in-skill products for the vendor
- Get the list of in-skill products for a specified skillId and stage
- Get the list of skills associated with an in-skill product
- Associate an in-skill product with a skill
- Disassociate an in-skill product from a skill
- Reset developer account entitlements
- Response exceptions
Pagination and filtering of results
For API calls that return a list, you can optionally control the number of results that appear at once with maxResults
, and you can use nextToken
to obtain the next set of results with the next API call. This sample request has been given line breaks here for readability, but should be concatenated without line breaks. Some of the API calls that return lists also allow additional parameters for filtering.
GET /v1/skills/AAA-xxxx-yyyy/stages/development/inSkillProducts?
nextToken=VWB111111111
&maxResults=5
Parameter | Description |
---|---|
nextToken | String. The nextToken value can be used in a subsequent API call to obtain the next values after the maxResults are shown. This token has a 24-hour expiry. |
maxResults | Integer. The maximum number of results to display in a single API call. Default of 100. The nextToken value can be used to obtain the remaining results in a subsequent API call. |
Get in-skill product definition
Returns the in-skill product definition for given productId.
Request
The stage
can have a value of development
or live
.
GET /v1/inSkillProducts/{productId}/stages/{stage}
Response
Returns the in-skill product definition, in the form of the in-skill product manifest.
Errors
Code | Description |
400 | Bad request. Returned when a required parameter is not present, or is badly formatted. |
401 | The auth token is invalid/expired or doesn't have access to the resource. |
404 | Requested resource not found. |
429 | Too many requests received. |
500 | Internal Server Error |
Create a new in-skill product
Creates a new in-skill product for a given vendorId.
Request
POST /v1/inSkillProducts
Request body example
Request body parameters
Parameter | Description | Type | Required |
---|---|---|---|
|
Identifies the vendor ID of your Amazon developer account. |
String |
Yes |
|
Product definition. Depending on the ISP payment model, include the subscription, entitlement, or consumable schema. For details about the format, see In-Skill Purchasing Schemas. |
Object |
Yes |
Response
A successful response returns 201 and the product name as follows.
{
"productId": "string"
}
Errors
Code | Description |
400 | Bad request. Returned when a required parameter is not present, or is badly formatted. |
401 | The auth token is invalid/expired or doesn't have access to the resource. |
429 | Too many requests received. |
500 | Internal Server Error |
Get the summary information for an in-skill product
Returns summary information for an in-skill product.
Request
GET /v1/inSkillProducts/{productId}/stages/{stage}/summary
Both development
and live
are supported for the {stage} value.
Response
The in-skill product summary response takes the following form.
{
"type": "SUBSCRIPTION",
"productId": "string",
"referenceName": "string",
"lastUpdated": "2018-09-20T04:13:02.326Z",
"nameByLocale": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"status": "INCOMPLETE",
"stage": "development",
"editableState": "EDITABLE",
"purchasableState": "PURCHASABLE",
"_links": {
"self": {
"href": "string"
}
},
"pricing": {
"amazon.com": {
"releaseDate": "2018-09-20T04:13:02.326Z",
"defaultPriceListing": {
"price": 0,
"primeMemberPrice": 0,
"currency": "USD"
}
}
}
}
Errors
Code | Description |
401 | The auth token is invalid/expired or doesn't have access to the resource. |
404 | Requested resource not found. |
429 | Too many requests received. |
500 | Internal Server Error |
Update an existing in-skill product
Updates an existing in-skill product definition for a specified productId
and stage
.
Request
You can only update a product definition for skills that are in the development
stage, so the {stage} value must be development
.
PUT /v1/inSkillProducts/{productId}/stages/{stage}
Request body parameters
Parameter | Description | Type | Required |
---|---|---|---|
|
Identifies the vendor ID of your Amazon developer account. |
String |
Yes |
|
Product definition. Depending on the ISP payment model, include the subscription, entitlement, or consumable schema. For details about the format, see In-Skill Purchasing Schemas. |
Object |
Yes |
Response
Returns the in-skill product definition, in the form of the in-skill product manifest.
Errors
Code | Description |
400 | Bad request. Returned when a required parameter is not present, or is badly formatted. |
401 | The auth token is invalid/expired or doesn't have access to the resource. |
403 | Request is forbidden. |
404 | Requested resource not found. |
412 | Precondition failed. |
429 | Too many requests received. |
500 | Internal Server Error |
Delete an existing in-skill product
Deletes the in-skill product for the specified productId
. This deletion is only supported for the development stage. Live in-skill products or in-skill products associated with a skill cannot be deleted by this API.
Request
DELETE /v1/inSkillProducts/{productId}/stages/{stage}
Only development
is supported for {stage}.
Response
A successful response returns 204 with no content.
Errors
Code | Description |
400 | Bad request. Returned when a required parameter is not present, or is badly formatted. |
401 | The auth token is invalid/expired or doesn't have access to the resource. |
403 | Request is forbidden. |
404 | Requested resource not found. |
412 | Precondition failed. |
429 | Too many requests received. |
500 | Internal Server Error |
Get a list of in-skill products for the vendor
Request
HTTP/1.1
GET /v1/inSkillProducts
Filtered request with parameters
As with any of the API calls that return a list, you can control the number of results that appear at once with maxResults
, and you can use nextToken to obtain the next set of results with the next API call. This sample request, which uses some of the possible parameters, has been given line breaks here for readability, but should be concatenated without line breaks.
GET /v1/inSkillProducts?
nextToken=VWB111111111
&maxResults=5
&stage=live
&type=SUBSCRIPTION
Parameter | Description |
---|---|
nextToken | String. The nextToken value can be used in a subsequent API call to obtain the next values after the maxResults are shown. This token has a 24-hour expiry.
|
maxResults | Integer. The maximum number of results to display in a single API call. Default of 100. The nextToken value can be used to obtain the remaining results in a subsequent API call.
|
productId | Array of strings. The list of in-skill product IDs to obtain the summary for. A maximum of 50 in-skill product IDs can be specified in a single listInSkillProducts call. The productId parameter must not be used with nextToken or maxResults . parameter. |
stage | One of: `development`, `live`. Filters results to include only the specified stage. |
type | One of: SUBSCRIPTION , ENTITLEMENT , CONSUMABLE . Filters results to include only the specified type of in-skill product.
|
status | One of: INCOMPLETE , COMPLETE , CERTIFICATION , PUBLISHED , SUPPRESSED . Filters by status of in-skill product.
|
isAssociatedWithSkill | One of: ASSOCIATED_WITH_SKILL , NO_ASSOCIATIONs . Filters in-skill products by whether or not they are associated to a skill.
|
Response
A successful 200 OK response returns a body like the following. The _links provide a URL to reference the current results, and a URL to reference the next set of results.
{
"_links": {
"self": {
"href": "string"
},
"next": {
"href": "string"
}
},
"inSkillProducts": [
{
"type": "SUBSCRIPTION",
"productId": "string",
"referenceName": "string",
"lastUpdated": "2018-09-19T22:56:57.937Z",
"nameByLocale": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"status": "INCOMPLETE",
"stage": "development",
"editableState": "EDITABLE",
"purchasableState": "PURCHASABLE",
"_links": {
"self": {
"href": "string"
}
},
"pricing": {
"amazon.com": {
"releaseDate": "2018-09-19T22:56:57.937Z",
"defaultPriceListing": {
"price": 0,
"primeMemberPrice": 0,
"currency": "USD"
}
}
}
}
],
"isTruncated": true,
"nextToken": "string"
}
Errors
400 | Bad request. Returned when a required parameter is not present or is badly formatted. |
401 | The auth token is invalid/expired or doesn't have access to the resource. |
429 | Too many requests received. |
500 | Internal Server Error |
Get the list of in-skill products for a specified skillId and stage
Returns the list of in-skill products for a specified skillId and stage.
Request
GET /v1/skills/{skillId}/stages/{stage}/inSkillProducts
You can control the number of results that appear at once with maxResults
, and you can use nextToken
to obtain the next set of results with the next API call. This sample request, which uses some of the parameters, has been given line breaks here for readability, but should be concatenated without line breaks.
GET /v1/skills/AAA-xxxx-yyyy/stages/development/inSkillProducts?
nextToken=VWB111111111
&maxResults=5
&stage=live
Parameter | Description |
---|---|
nextToken | String. The nextToken value can be used in a subsequent API call to obtain the next values after the maxResults are shown. This token has a 24-hour expiry.
|
maxResults | Integer. The maximum number of results to display in a single API call. Default of 100. The nextToken value can be used to obtain the remaining results in a subsequent API call.
|
Response
A successful response returns 200 and a list of in-skill products for the specified skillId
and stage
.
The _links value returns a URL for the current list, and for the next set of results, if applicable.
{
"_links": {
"self": {
"href": "string"
},
"next": {
"href": "string"
}
},
"inSkillProducts": [
{
"type": "SUBSCRIPTION",
"productId": "string",
"referenceName": "string",
"lastUpdated": "2018-09-11T10:42:07.152Z",
"nameByLocale": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"status": "INCOMPLETE",
"stage": "development",
"editableState": "EDITABLE",
"purchasableState": "PURCHASABLE",
"_links": {
"self": {
"href": "string"
}
},
"pricing": {
"amazon.com": {
"releaseDate": "2018-09-11T10:42:07.153Z",
"defaultPriceListing": {
"price": 0,
"primeMemberPrice": 0,
"currency": "USD"
}
}
}
}
],
"isTruncated": true,
"nextToken": "string"
}
Errors
Code | Description |
400 | Bad request. Returned when a required parameter is not present, or is badly formatted. |
401 | The auth token is invalid/expired or doesn't have access to the resource. |
404 | Requested resource not found. |
429 | Too many requests received. |
500 | Internal Server Error |
Get the list of skills associated with an in-skill product
Returns the list of skills associated with an in-skill product.
Request
/v1/inSkillProducts/{productId}/stages/{stage}/skills
Response
The list of skills is returned with a _links
object that provides a URL for the list of skills. If more than one page is returned, then a URL for the next page is also provided.
{
"associatedSkillIds": [
"string"
],
"_links": {
"self": {
"href": "string"
},
"next": {
"href": "string"
}
},
"isTruncated": true,
"nextToken": "string"
}
Errors
Code | Description |
401 | The auth token is invalid/expired or doesn't have access to the resource. |
404 | Requested resource not found. |
429 | Too many requests received. |
500 | Internal Server Error |
Associate an in-skill product with a skill
Associates an in-skill product with a skill.
Request
PUT /v1/inSkillProducts/{productId}/skills/{skillId}
Response
Returns 204 with no content.
Errors
Code | Description |
400 | Bad request. Returned when a required parameter is not present, or is badly formatted. |
401 | The auth token is invalid/expired or doesn't have access to the resource. |
403 | Request is forbidden. |
404 | Requested resource not found. |
429 | Too many requests received. |
500 | Internal Server Error |
Disassociate an in-skill product from a skill
Deletes the association between an in-skill product and a skill. Both the product and skill remain otherwise unchanged.
This disassociation can be done for a skill in the development stage. If you delete this association in a live skill, then the skill must be re-submitted for certification.
Request
Both the productId
and the skillId
are specified in the call.
DELETE /v1/inSkillProducts/{productId}/skills/{skillId}
Response
A successful response returns 204 with no content.
Errors
Code | Description |
400 | Bad request. Returned when a required parameter is not present, or is badly formatted. |
401 | The auth token is invalid/expired or doesn't have access to the resource. |
403 | Request is forbidden. |
404 | Requested resource not found. |
412 | Precondition failed. |
429 | Too many requests received. |
500 | Internal Server Error |
Reset developer account entitlements
If the in-skill product type is ENTITLEMENT
or CONSUMABLE
, then by default the customer who purchases that product owns that product indefinitely, as opposed to those instances where the type is SUBSCRIPTION
and the customer must pay repeatedly to maintain access to the product. To facilitate testing by skill developers, this API resets all active entitlements that the developer account has for a specified productId
. The API does not affect the product itself and only supports development stage entitlements held by the skill's developer account.
Request
DELETE /v1/inSkillProducts/{productId}/stages/{stage}/entitlement
Response
A successful response returns 204 with no content.
Errors
Code | Description |
400 | Bad request. Returned when a required parameter is not present, or is badly formatted. |
401 | The auth token is invalid/expired or doesn't have access to the resource. |
403 | Request is forbidden. |
404 | Requested resource not found. |
412 | Precondition failed. |
429 | Too many requests received. |
500 | Internal Server Error |
Response exceptions
If a request is unsuccessful, the exception takes the following form.
{
"id": string,
"message": string
}
Last updated: Mar 30, 2022