In-Skill Product Management REST API Reference

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

Use the In-Skill Product Management REST API to create and manage your in-skill products. To sell content in your custom skill, use the API to associate products with your skill. For more details about in-skill products, see In-Skill Purchasing Overview.

To create and manage your in-skill products in the Alexa developer console, see Create and Edit In-Skill Products in the Developer Console. To create and manage your in-skill products with the Alexa Skills Kit Command Line Interface (ASK CLI), see Create and Edit In-Skill Products with the ASK CLI.

If you want to view paid skills and in-skill products that the customer purchased already or get in-skill products available to the customer to purchase, use the Monetization REST API.

API endpoint

The endpoint of the In-Skill Product Management API is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Get an Access Token for SMAPI.

Operations

The In-Skill Product Management API includes the following operations.

Operation	HTTP method and URI
Associate in-skill product	`PUT /v1/inSkillProducts/{productId}/skills/{skillId}`
Create in-skill product	`POST /v1/inSkillProducts`
Delete in-skill product	`DELETE /v1/inSkillProducts/{productId}/stages/{stage}`
Disassociate in-skill product	`DELETE /v1/inSkillProducts/{productId}/skills/{skillId}`
Get in-skill product definition	`GET /v1/inSkillProducts/{productId}/stages/{stage}`
Get in-skill product summary	`GET /v1/inSkillProducts/{productId}/stages/{stage}/summary`
List associated products	`GET /v1/skills/{skillId}/stages/{stage}/inSkillProducts&maxResults={maxResults}&nextToken={nextToken}`
List associated skills	`GET /v1/inSkillProducts/{productId}/stages/{stage}/skills&maxResults={maxResults}&nextToken={nextToken}`
List in-skill products	`GET /v1/inSkillProducts?vendorId={vendorId}&stage={stage}&type={type}&referenceName={referenceName}&status={status}&isAssociatedWithSkill={isAssociatedWithSkill}&productId={productId}&maxResults={maxResults}&nextToken={nextToken}`
Reset entitlements	`DELETE /v1/inSkillProducts/{productId}/stages/{stage}/entitlement`
Update in-skill product	`PUT /v1/inSkillProducts/{productId}/stages/{stage}`

Associate in-skill product

Link the specified product to the specified skill. Your skill can offer linked products to the customer.

Request

To link the product, you make a PUT request to the inSkillProducts resource.

Request path and header example

Copied to clipboard.

PUT /v1/inSkillProducts/{productId}/skills/{skillId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`productId`	Path	Identifies the product.	String	Yes
`skillId`	Path	Identifies the skill. Valid values: 1 – 255 characters.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Product associated with the skill successfully.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create in-skill product

Create a new in-skill product for the specified vendor.

Request

To create an in-skill product, you make a POST request to the inSkillProducts resource.

Request path and header example

Copied to clipboard.

POST /v1/inSkillProducts
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "vendorId": "your.vendor.id.1",
    "inSkillProductDefinition": {
        "version": "1.0",
        "type": "SUBSCRIPTION",
        "referenceName": "Fact subscription",
        "purchasableState": "PURCHASABLE",
        "subscriptionInformation": {
            "subscriptionPaymentFrequency": "MONTHLY",
            "subscriptionTrialPeriodDays": 0
        },
        "publishingInformation": {
            "locales": {
                "en-US": {
                    "name": "Fact subscription",
                    "smallIconUri": "https://smallUri.com",
                    "largeIconUri": "https://largeUri.com",
                    "summary": "This is a sample subscription product.",
                    "description": "Challenge yourself with premium facts.",
                    "examplePhrases": [
                        "Alexa, get premium facts.",
                        "Alexa, use premium facts. "
                    ],
                    "keywords": [
                        "facts"
                    ],
                    "customProductPrompts": {
                        "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} includes <emphasis level=\"moderate\"> an assortment of fifty questions on a broad range of historical topics.<break time=\"150ms\">",
                        "boughtConfirmationPrompt": "Enjoy your new {PREMIUM_CONTENT_TITLE}! To play anytime say Alexa, ask Quick Trivia for my premium facts."
                    }
                }
            },
            "distributionCountries": ["US", "GB"],
            "pricing": {
                "amazon.com": {
                    "releaseDate": "2018-09-19T23:06:48.107Z",
                    "defaultPriceListing": {
                        "price": 0.99,
                        "currency": "USD"
                    }
                }
            },
            "taxInformation": {
                "category": "SOFTWARE"
            }
        },
        "privacyAndCompliance": {
            "locales": {
                "en-US": {
                    "privacyPolicyUrl": "https://example.com"
                }
            }
        },
        "testingInstructions": "Add the subscription, and then say get premium facts."
    }
}

Request body properties

Property	Description	Type	Required
`vendorId`	Identifies the vendor ID of the Amazon developer account that owns the product.	String	Yes
`inSkillProductDefinition`	Definition of the product. Depending on the payment model, include the subscription object.	Product object	Yes

Response

A successful response returns HTTP 201 Created, along with the ID of the new product. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The following example shows a response.

{
  "productId": "amzn1.adg.product.1"
}

Response body properties

Property	Description	Type
`productId`	Primary identifier for the product assigned by Amazon.	String

HTTP status codes

Status	Description
`201 Created`	Product created successfully.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete in-skill product

Delete the specified in-skill product. You can delete development stage products only. You can't delete live products or products associated with a skill.

Request

To delete a product, you make a DELETE request to the inSkillProducts resource.

Request path and header example

Copied to clipboard.

DELETE /v1/inSkillProducts/{productId}/stages/{stage}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`productId`	Path	Identifies the product.	String	Yes
`stage`	Path	Stage of the product. Valid value: `development`.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Product deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Disassociate in-skill product

Delete an association between the skill and the product. Both the product and skill remain unchanged otherwise.

Important: If you delete the association with a live skill, you must resubmit your skill for certification.

Request

To delete an association, you make a DELETE request to the inSkillProducts resource.

Request path and header example

Copied to clipboard.

DELETE /v1/inSkillProducts/{productId}/skills/{skillId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`productId`	Path	Identifies the product.	String	Yes
`skillId`	Path	Identifies the skill. Valid values: 1 – 255 characters.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Association between the product and skill deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get in-skill product definition

Get the in-skill product definition for the specified product.

Request

To get the in-skill product definition, you make a GET request to the inSkillProducts resource.

Request path and header example

Copied to clipboard.

GET /v1/inSkillProducts/{productId}/stages/{stage}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`productId`	Path	Identifies the product.	String	Yes
`stage`	Path	Stage of the product. Valid values: `development`, `live`.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the product definition. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "inSkillProductDefinition": {
        "version": "1.0",
        "type": "SUBSCRIPTION",
        "referenceName": "Fact subscription",
        "purchasableState": "PURCHASABLE",
        "subscriptionInformation": {
            "subscriptionPaymentFrequency": "MONTHLY",
            "subscriptionTrialPeriodDays": 10
        },
        "publishingInformation": {
            "locales": {
                "en-US": {
                    "name": "Fact subscription",
                    "smallIconUri": "https://smallUri.com",
                    "largeIconUri": "https://largeUri.com",
                    "summary": "This is a sample subscription product.",
                    "description": "Challenge yourself with premium facts.",
                    "examplePhrases": [
                        "Alexa, get premium facts.",
                        "Alexa, use premium facts. "
                    ],
                    "keywords": [
                        "facts"
                    ],
                    "customProductPrompts": {
                        "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} includes <emphasis level=\"moderate\"> an assortment of fifty questions on a broad range of historical topics.<break time=\"150ms\">",
                        "boughtConfirmationPrompt": "Enjoy your new {PREMIUM_CONTENT_TITLE}! To play anytime say Alexa, ask Quick Trivia for my premium facts."
                    }
                }
            },
            "distributionCountries": ["US", "GB"],
            "pricing": {
                "amazon.com": {
                    "releaseDate": "2018-09-19T23:06:48.107Z",
                    "defaultPriceListing": {
                        "price": 0.99,
                        "currency": "USD"
                    }
                }
            },
            "taxInformation": {
                "category": "SOFTWARE"
            }
        },
        "privacyAndCompliance": {
            "locales": {
                "en-US": {
                    "privacyPolicyUrl": "https://example.com"
                }
            }
        },
        "testingInstructions": "Add the subscription, and then say get premium facts."
    }
}

Response body properties

Property	Description	Type
`inSkillProductDefinition`	Definition of the product. For subscription products, the definition includes the subscription object.	Product object

HTTP status codes

Status	Description
`200 OK`	Response body contains the product definition.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get in-skill product summary

Get the summary definition of the specified in-skill product.

Request

To get an in-skill product, you make a GET request to the inSkillProducts resource.

Request path and header example

Copied to clipboard.

GET /v1/inSkillProducts/{productId}/stages/{stage}/summary
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`productId`	Path	Identifies the product.	String	Yes
`stage`	Path	Stage of the product. Valid values: `development`, `live`.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the summary definition of the in-skill product. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "type": "CONSUMABLE",
    "productId": "amzn1.adg.product.1",
    "referenceName": "Fact subscription",
    "lastUpdated": "2018-09-19T22:56:57.937Z",
    "nameByLocale": {
        "en-US": "Premium Facts Pack",
        "en-GB": "Premium Facts Pack"
    },
    "status": "INCOMPLETE",
    "stage": "development",
    "editableState": "EDITABLE",
    "purchasableState": "NOT_PURCHASABLE",
    "pricing": {
        "amazon.co.uk": {
            "defaultPriceListing": {
                "price": 1.54,
                "currency": "GBP"
            },
            "releaseDate": "2018-12-28T01:25:00Z"
        },
        "amazon.com": {
            "defaultPriceListing": {
                "price": 1.99,
                "currency": "USD"
            },
            "releaseDate": "2018-12-28T01:25:00Z"
        }
    }
}

Response body properties

Property	Description	Type
`type`	Product type. Valid values: `CONSUMABLE`, `ENTITLEMENT`, `SUBSCRIPTION`.	String
`productId`	Primary identifier for the product assigned by Amazon.	String
`referenceName`	Product reference name selected by the developer. Valid value: 1–255 alphanumeric characters and underscore.	String
`lastUpdated`	Date and time of the last product definition update. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`nameByLocale`	List of product names by locale.	Map of objects
`nameByLocale.<locale>`	Name of the product in the specified locale. Locale is the 2-letter language code and 2-letter country/region code, for example, `en-US`. For valid string values, see Locales that support in-skill products. Formatted as: `XX-XX`	String
`status`	Status of the product. Valid values: `CERTIFICATION`, `COMPLETE`, `INCOMPLETE`, `PUBLISHED`, `SUPPRESSED`.	String
`stage`	Stage of the product. Valid values: `development`, `certified`, `live`.	String
`editableState`	Indicates whether you can edit the product. Valid values: `EDITABLE`, `NOT_EDITABLE`.	String
`purchasableState`	Indicates whether customers can purchase the product. Valid values: `PURCHASABLE`, `NOT_PURCHASABLE`.	String
`promotableState`	Indicates whether this product is available on the Amazon retail site. Valid values: `IN_SKILL_ONLY`, `ALL_AMAZON_CHANNELS`.	String
`pricing`	Localized pricing information defined for the product.	Map of Pricing objects

HTTP status codes

Status	Description
`200 OK`	Response body contains the summary definition of the specified in-skill product.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List associated products

List the products associated with the specified skill and skill stage.

Request

To list associated products, you make a GET request to the inSkillProducts resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/stages/{stage}/inSkillProducts&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`skillId`	Path	Identifies the skill. Valid values: 1 – 255 characters.	String	Yes
`stage`	Path	Filter on the stage of the skill. Valid values: `development`, `live`.	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. If you include this parameter, don't include `productId`. Valid values: 1–50. Default: 50.	Integer	No
`nextToken`	Query	Token from the previous response. If not included, the Alexa service returns the first page of results. Include if iterating over a paginated response. If you include this parameter, don't include `productId`.	String	No
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a summary list of in-skill products for the specified skill and stage. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "inSkillProducts": [{
        "type": "CONSUMABLE",
        "productId": "amzn1.adg.product.1",
        "referenceName": "Fact subscription",
        "lastUpdated": "2018-09-19T22:56:57.937Z",
        "nameByLocale": {
            "en-US": "Premium Facts Pack",
            "en-GB": "Premium Facts Pack"
        },
        "status": "INCOMPLETE",
        "stage": "development",
        "editableState": "EDITABLE",
        "purchasableState": "NOT_PURCHASABLE",
        "pricing": {
            "amazon.co.uk": {
                "defaultPriceListing": {
                    "price": 1.54,
                    "currency": "GBP"
                },
                "releaseDate": "2018-12-28T01:25:00Z"
            },
            "amazon.com": {
                "defaultPriceListing": {
                    "price": 1.99,
                    "currency": "USD"
                },
                "releaseDate": "2018-12-28T01:25:00Z"
            }
        }
    }],
    "isTruncated": true,
    "nextToken": "someToken2",
    "_links": {
        "self": {
            "href": "/v1/skills/amzn1.ask.skill.1/stages/development/inSkillProducts"
        },
        "next": {
            "href": "/v1/skills/amzn1.ask.skill.1/stages/development/inSkillProducts?nextToken=someToken2"
        }
    }
}

Response body properties

Property	Description	Type
`inSkillProducts`	List of products that meet the filter criteria specified in the request.	Array of objects
`inSkillProducts[].type`	Product type. Valid values: `CONSUMABLE`, `ENTITLEMENT`, `SUBSCRIPTION`.	String
`inSkillProducts[].productId`	Primary identifier for the product assigned by Amazon.	String
`inSkillProducts[].referenceName`	Product reference name selected by the developer. Valid value: 1–255 alphanumeric characters and underscore.	String
`inSkillProducts[].lastUpdated`	Date and time of the last product definition update. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`inSkillProducts[].nameByLocale`	List of product names by locale.	Map of objects
`inSkillProducts[].nameByLocale.<locale>`	Name of the product in the specified locale. Locale is the 2-letter language code and 2-letter country/region code, for example, `en-US`. For valid string values, see Locales that support in-skill products. Formatted as: `XX-XX`	String
`inSkillProducts[].status`	Status of the product. Valid values: `CERTIFICATION`, `COMPLETE`, `INCOMPLETE`, `PUBLISHED`, `SUPPRESSED`.	String
`inSkillProducts[].stage`	Stage of the product. Valid values: `development`, `certified`, `live`.	String
`inSkillProducts[].editableState`	Indicates whether you can edit the product. Valid values: `EDITABLE`, `NOT_EDITABLE`.	String
`inSkillProducts[].purchasableState`	Indicates whether customers can purchase the product. Valid values: `PURCHASABLE`, `NOT_PURCHASABLE`.	String
`inSkillProducts[].promotableState`	Indicates whether this product is available on the Amazon retail site. Valid values: `IN_SKILL_ONLY`, `ALL_AMAZON_CHANNELS`.	String
`inSkillProducts[].pricing`	Localized pricing information defined for the product.	Map of Pricing objects
`_links`	Links for item navigation. Defined in JSON Hypertext Application Language specification.	_links object
`isTruncated`	Indicates whether there are more items to return. If set to `true`, include `nextToken` a subsequent request. Or, you can get the remaining items by using the `next` link in the `_links` object.	Boolean
`nextToken`	(Optional) Included when there are more results to return. Use this value in a subsequent request.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of products associated with the specified skill.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List associated skills

List the skills associated with the specified product.

Request

To list associated skills, you make a GET request to the inSkillProducts resource.

Request path and header example

Copied to clipboard.

GET /v1/inSkillProducts/{productId}/stages/{stage}/skills&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`productId`	Path	Identifies the product.	String	Yes
`stage`	Path	Stage of the product. Valid values: `development`, `certified`, `live`.	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. If you include this parameter, don't include `productId`. Valid values: 1–50. Default: 50.	Integer	No
`nextToken`	Query	Token from the previous response. If not included, the Alexa service returns the first page of results. Include if iterating over a paginated response. If you include this parameter, don't include `productId`.	String	No
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of skills associated with the specified product. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "associatedSkillIds": [
        "amzn1.ask.skill.1",
        "amzn1.ask.skill.2",
        "amzn1.ask.skill.3"
    ],
    "isTruncated": true,
    "nextToken": "someToken2",
    "_links": {
        "self": {
            "href": "/v1/inSkillProducts/amzn1.adg.product.1/stages/development/skills"
        },
        "next": {
            "href": "/v1/inSkillProducts/amzn1.adg.product.1/stages/development/skills&nextToken=someToken2"
        }
    }
}

Response body properties

Property	Description	Type
`associatedSkillIds`	List of skill IDs associated with the product. The associations are stage specific.	Array of string
`_links`	Links for item navigation. Defined in JSON Hypertext Application Language specification.	_links object
`isTruncated`	Indicates whether there are more items to return. If set to `true`, include `nextToken` a subsequent request. Or, you can get the remaining items by using the `next` link in the `_links` object.	Boolean
`nextToken`	(Optional) Included when there are more results to return. Use this value in a subsequent request.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of skills associated with the specified product.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List in-skill products

Get a list of your in-skill products based on the filter criteria.

Request

To list the in-skill products, you make a GET request to the inSkillProducts resource.

Request path and header example

Copied to clipboard.

GET /v1/inSkillProducts?vendorId={vendorId}&stage={stage}&type={type}&referenceName={referenceName}&status={status}&isAssociatedWithSkill={isAssociatedWithSkill}&productId={productId}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`vendorId`	Query	Filter on the vendor to which the product belongs.	String	Yes
`stage`	Query	Filter on the stage of the product. Valid values: `development`, `certified`, `live`.	String	No
`type`	Query	Filter on the product type. Valid values: `CONSUMABLE`, `ENTITLEMENT`, `SUBSCRIPTION`.	String	No
`referenceName`	Query	Filter on the product reference name selected by the developer. Valid value: 1–255 alphanumeric characters and underscore.	String	No
`status`	Query	Filter on the status of the product. Valid values: `CERTIFICATION`, `COMPLETE`, `INCOMPLETE`, `PUBLISHED`, `SUPPRESSED`.	String	No
`isAssociatedWithSkill`	Query	Filter to find products linked with a skill. Valid values: `ASSOCIATED_WITH_SKILL`, `NO_SKILL_ASSOCIATIONS`, `NOT_ASSOCIATED_WITH_SKILL`.	String	No
`productId`	Query	Filter for the specified products. You can specify up to 50 IDs. If you include this parameter, don't include `maxResults` and `nextToken`.	String	No
`maxResults`	Query	Maximum number of results to return in the response. If you include this parameter, don't include `productId`. Valid values: 1–50. Default: 50.	Integer	No
`nextToken`	Query	Token from the previous response. If not included, the Alexa service returns the first page of results. Include if iterating over a paginated response. If you include this parameter, don't include `productId`.	String	No
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of products that match the filter criteria. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "inSkillProducts": [{
        "type": "CONSUMABLE",
        "productId": "amzn1.adg.product.1",
        "referenceName": "Fact subscription",
        "lastUpdated": "2018-09-19T22:56:57.937Z",
        "nameByLocale": {
            "en-US": "Premium Facts Pack",
            "en-GB": "Premium Facts Pack"
        },
        "status": "INCOMPLETE",
        "stage": "development",
        "editableState": "EDITABLE",
        "purchasableState": "NOT_PURCHASABLE",
        "pricing": {
            "amazon.co.uk": {
                "defaultPriceListing": {
                    "price": 1.54,
                    "currency": "GBP"
                },
                "releaseDate": "2018-12-28T01:25:00Z"
            },
            "amazon.com": {
                "defaultPriceListing": {
                    "price": 1.99,
                    "currency": "USD"
                },
                "releaseDate": "2018-12-28T01:25:00Z"
            }
        }
    }],
    "isTruncated": true,
    "nextToken": "someToken2",
    "_links": {
        "self": {
            "href": "/v1/inSkillProducts?vendorId=your.vendor.id.1"
        },
        "next": {
            "href": "/v1/skills/amzn1.ask.skill.1/stages/development/inSkillProducts?vendorId=your.vendor.id.1&nextToken=someToken2"
        }
    }
}

Response body properties

Property	Description	Type
`inSkillProducts`	List of products that meet the filter criteria specified in the request.	Array of objects
`inSkillProducts[].type`	Product type. Valid values: `CONSUMABLE`, `ENTITLEMENT`, `SUBSCRIPTION`.	String
`inSkillProducts[].productId`	Primary identifier for the product assigned by Amazon.	String
`inSkillProducts[].referenceName`	Product reference name selected by the developer. Valid value: 1–255 alphanumeric characters and underscore.	String
`inSkillProducts[].lastUpdated`	Date and time of the last product definition update. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`inSkillProducts[].nameByLocale`	List of product names by locale.	Map of objects
`inSkillProducts[].nameByLocale.<locale>`	Name of the product in the specified locale. Locale is the 2-letter language code and 2-letter country/region code, for example, `en-US`. For valid string values, see Locales that support in-skill products. Formatted as: `XX-XX`	String
`inSkillProducts[].status`	Status of the product. Valid values: `CERTIFICATION`, `COMPLETE`, `INCOMPLETE`, `PUBLISHED`, `SUPPRESSED`.	String
`inSkillProducts[].stage`	Stage of the product. Valid values: `development`, `certified`, `live`.	String
`inSkillProducts[].editableState`	Indicates whether you can edit the product. Valid values: `EDITABLE`, `NOT_EDITABLE`.	String
`inSkillProducts[].purchasableState`	Indicates whether customers can purchase the product. Valid values: `PURCHASABLE`, `NOT_PURCHASABLE`.	String
`inSkillProducts[].promotableState`	Indicates whether this product is available on the Amazon retail site. Valid values: `IN_SKILL_ONLY`, `ALL_AMAZON_CHANNELS`.	String
`inSkillProducts[].pricing`	Localized pricing information defined for the product.	Map of Pricing objects
`_links`	Links for item navigation. Defined in JSON Hypertext Application Language specification.	_links object
`isTruncated`	Indicates whether there are more items to return. If set to `true`, include `nextToken` a subsequent request. Or, you can get the remaining items by using the `next` link in the `_links` object.	Boolean
`nextToken`	(Optional) Included when there are more results to return. Use this value in a subsequent request.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains list of in-skill products that match the filter criteria.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Reset entitlements

Reset all active entitlements in your development account, including consumables, one-time purchases and subscriptions. Use this operation to test your skill in the development stage.

Request

To reset your entitlements, you make a DELETE request to the inSkillProducts resource.

Request path and header example

Copied to clipboard.

DELETE /v1/inSkillProducts/{productId}/stages/{stage}/entitlement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`productId`	Path	Identifies the product.	String	Yes
`skillId`	Path	Identifies the skill. Valid values: 1 – 255 characters.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Entitlements reset successfully.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update in-skill product

Update the product definition for the specified in-skill product. You can update products in the development stage only.

Request

To update a product definition, you make a PUT request to the inSkillProducts resource.

Request path and header example

Copied to clipboard.

PUT /v1/inSkillProducts/{productId}/stages/{stage}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`productId`	Path	Identifies the product.	String	Yes
`stage`	Path	Stage of the product. Valid values: `development`, `certified`, `live`.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "inSkillProductDefinition": {
        "version": "1.0",
        "type": "SUBSCRIPTION",
        "referenceName": "Fact subscription",
        "purchasableState": "PURCHASABLE",
        "subscriptionInformation": {
            "subscriptionPaymentFrequency": "MONTHLY",
            "subscriptionTrialPeriodDays": 10
        },
        "publishingInformation": {
            "locales": {
                "en-US": {
                    "name": "Fact subscription",
                    "smallIconUri": "https://smallUri.com",
                    "largeIconUri": "https://largeUri.com",
                    "summary": "This is a sample subscription product.",
                    "description": "Challenge yourself with premium facts.",
                    "examplePhrases": [
                        "Alexa, get premium facts.",
                        "Alexa, use premium facts. "
                    ],
                    "keywords": [
                        "facts"
                    ],
                    "customProductPrompts": {
                        "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} includes <emphasis level=\"moderate\"> an assortment of fifty questions on a broad range of historical topics.<break time=\"150ms\">",
                        "boughtConfirmationPrompt": "Enjoy your new {PREMIUM_CONTENT_TITLE}! To play anytime say Alexa, ask Quick Trivia for my premium facts."
                    }
                }
            },
            "distributionCountries": ["US", "GB"],
            "pricing": {
                "amazon.com": {
                    "releaseDate": "2018-09-19T23:06:48.107Z",
                    "defaultPriceListing": {
                        "price": 0.99,
                        "currency": "USD"
                    }
                }
            },
            "taxInformation": {
                "category": "SOFTWARE"
            }
        },
        "privacyAndCompliance": {
            "locales": {
                "en-US": {
                    "privacyPolicyUrl": "https://example.com"
                }
            }
        },
        "testingInstructions": "Add the subscription, and then say get premium facts."
    }
}

Request body properties

Property	Description	Type	Required
`inSkillProductDefinition`	Definition of the product. Depending on the payment model, include the subscription object.	Product object	Yes

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Product definition updated successfully.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Last updated: May 25, 2023