In-Skill Product Management

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

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.

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
`vendorId`	Identifies the vendor ID of your Amazon developer account.	String	Yes
`inSkillProductDefinition`	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
`vendorId`	Identifies the vendor ID of your Amazon developer account.	String	Yes
`inSkillProductDefinition`	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
  }