In-Skill Product Management REST API Reference


Use the In-Skill Product Management REST API to create and manage your in-skill products. To sell premium 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 aren't valid.
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 included token expired or isn't valid. Or, you don'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 aren't valid.
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 included token expired or isn't valid. Or, you don'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 aren't valid.
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 included token expired or isn't valid. Or, you don'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.

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 aren't valid.
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 included token expired or isn't valid. Or, you don'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 aren't valid.
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 included token expired or isn't valid. Or, you don'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 aren't valid.
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 included token expired or isn't valid. Or, you don'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 aren't valid.
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 included token expired or isn't valid. Or, you don'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 aren't valid.
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 included token expired or isn't valid. Or, you don'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 aren't valid.
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 included token expired or isn't valid. Or, you don'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 aren't valid.
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 included token expired or isn't valid. Or, you don'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 aren't valid.
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 included token expired or isn't valid. Or, you don'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.


Was this page helpful?

Last updated: Nov 23, 2023