Paid Skills Interface Reference
The paid skill interface contains APIs to confirm skill entitlement and to invoke the Amazon purchase and cancellation flows.
Customer entitlement query
At the start of each skill session, get the customer entitlement status to determine whether to invoke the purchase flow or to continue with paid skill content. This interface returns ENTITLED
if the customer purchased the skill, or if a free trial is in progress. If the free trial expired, the customer canceled the subscription, or the customer hasn't purchased the skill, the interface returns NOT_ENTITLED
and an indication of whether the customer can purchase the skill.
To retrieve the customer entitlement state for a specific activity, you make an HTTP GET
request for the inSkillProducts
resource.
Request
GET /v1/users/~current/skills/~current/inSkillProducts/{id}
Host: {apiEndpoint}
Accept-Language: {locale}
Authorization: Bearer {apiAccessToken}
Request header parameter details
Field | Description | Type |
---|---|---|
|
Identifies the paid skill. Use Skill ID in this field. |
String |
|
Set to |
String |
|
Set to the locale of the customer. For example, |
String |
|
Access token used for authentication and authorization. Set to apiAccessToken property of the |
String |
This request body is empty.
Response
Use the response to determine whether to make a purchase suggestion or to continue with paid skill content. The following example shows a successful response for a skill in the development stage that's available for purchase.
{
"productId": "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3",
"name": "Your skill name",
"type": "ENTITLEMENT",
"summary": "Description of the skill",
"purchasable": "PURCHASABLE",
"entitled": "NOT_ENTITLED",
"entitledReason": "NOT_PURCHASED",
"activeEntitlementCount": 0,
"purchaseMode": "TEST",
"referenceName": ""
}
The following table shows the response codes.
HTTP status code | HTTP status | Description |
---|---|---|
200 |
Success |
Returns the requested skill and entitlement status. |
400 |
Invalid Request |
Indicates the request is invalid. The response body might include a specific error message that indicates why the request is invalid. |
401 |
Unauthorized |
The request didn't include the authorization token, the token is invalid or expired, or the skill doesn't have permission to make the request. |
404 |
Not Found |
A skill with the specified activity ID not found. This error might happen if you published an updated version of the skill and the skill isn't available in production. |
500 |
Server Error |
An error occurred on the server. The skill can retry by using exponential back-off. |
Response body parameter details
On success, the response body includes the details of the skill purchase.
Field | Description | Type |
---|---|---|
|
Identifies the paid skill. Set to skill ID. |
String |
|
Name of the skill in the language provided in the |
String |
|
Skill payment model. |
String (enum) |
|
Description of the skill in the language provided in the |
String |
|
Indicates if the customer can purchase the skill. If the customer already owns the skill, set to |
String (enum) |
|
Indicates if this customer can use the paid skill. |
String (enum) |
|
Indicates the reason for the entitled status. When the customer is in a free trial or already purchased the skill, the |
String (enum) |
|
(Ignore) Always set to zero for paid skills. |
integer |
|
Indicates whether the customer purchased the skill during live skill stage or during development stage. In development state, the customer isn't charged. |
String (enum) |
|
(Ignore) Always set to empty string for paid skills. |
String |
On error, the response body might contain a message
string that describes the reason for the error.
Buy request
To start the Amazon purchase flow, include the Connections.SendRequest
directive in your response to Alexa from an intent handler. The directive invokes the Buy
task by using the skill connections interface. To identify your paid skill, set the productID
to your Skill ID.
Buy
request. Make sure that you save any relevant user data in a persistent data store. After the purchase flow completes, Alexa launches your skill again. You can use the stored data to continue the skill. For details about persistent attributes, see
ASK SDK documentation for Node.js, Java, or Python.The following example shows a request to start the purchase flow.
This sample code uses the Alexa Skills Kit SDK for Node.js (v2).
return handlerInput.responseBuilder
.addDirective({
type: "Connections.SendRequest",
name: "Buy",
payload: {
InSkillProduct: {
productId: "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3",
}
},
token: "correlationToken"
})
.getResponse();
JSON syntax for a Connections.SendRequest
directive for a purchase request.
{
"directives": [
{
"type": "Connections.SendRequest",
"name": "Buy",
"payload": {
"InSkillProduct": {
"productId": "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3"
}
},
"token": "correlationToken"
}
]
}
Buy task definition
Property | Description | Type |
---|---|---|
|
The type of request. |
String |
|
The name of the task to invoke. |
String |
|
Contains the parameters required for purchase. |
|
|
(Optional) An optional string that Alexa returns in the response when the purchase flow completes. For example, you might use the token to store information to help you resume the skill after the purchase. |
String |
Cancel request
For a cancellation request, include the Connections.SendRequest
directive in your response to Alexa from an intent handler. The directive invokes the Cancel
task by using the skill connections interface. To identify your paid skill, set the productID
to your Skill ID.
Cancel
request. Make sure that you save any relevant user data in a persistent data store. After the purchase flow completes, Alexa launches your skill again. You can use the stored data to continue the skill. For details about persistent attributes, see
ASK SDK documentation for Node.js, Java, or Python.The following example shows a request to start the cancellation flow.
This sample code uses the Alexa Skills Kit SDK for Node.js (v2).
return handlerInput.responseBuilder
.addDirective({
type: 'Connections.SendRequest',
name: 'Cancel',
payload: {
InSkillProduct: {
productId: "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3",
}
},
token: "correlationToken"
})
.getResponse();
JSON syntax for a Connections.SendRequest
directive for a cancel request.
{
"directives": [
{
"type": "Connections.SendRequest",
"name": "Cancel",
"payload": {
"InSkillProduct": {
"productId": "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3"
}
},
"token": "correlationToken"
}
]
}
Cancel task definition
Property | Description | Type |
---|---|---|
|
The type of request. |
String |
|
The name of the task to invoke. |
String |
|
Contains the parameters required for purchase. |
|
|
(Optional) An optional string that Alexa returns in the response when the purchase flow completes. For example, you might use the token to store information to help you resume the skill after the cancellation. |
String |
Buy and cancel response
Your skill receives the result of the purchase or cancel request as a Connections.Response
request. Resume the skill based on the purchaseResult
included in the payload
.
Connections.Response example
The following example shows a successful response to the purchase flow.
{
"type": "Connections.Response",
"requestId": "string",
"timestamp": "string",
"name": "Buy",
"status": {
"code": "200",
"message": "OK"
},
"payload": {
"purchaseResult": "ACCEPTED",
"productId": "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3",
"message": "optional additional message"
},
"token": "correlationToken"
}
Connections.Response parameters
Property | Description | Type |
---|---|---|
|
Type of request. |
String |
|
Unique identifier for the Connections.Response request. |
String |
|
Time of the Connections.Response request. |
String |
|
Name of the request to which this response applies. |
String |
|
HTTP status result. |
Object |
|
HTTP response status such as |
String |
|
HTTP status message, such as |
String |
|
Contains the results of the purchase or cancel transaction. |
Object |
|
Result of the purchase or cancel request. |
String |
|
Paid skill ID sent in the request. |
String |
|
(Optional) Additional details about the cancel or purchase transaction. |
String |
|
Optional string that Alexa returns in the response when the purchase or cancel flow completes. For example, you might use the token to store information to help you resume the skill after the purchase. |
String |
Object definitions
Payload request object
The Payload
object included in the request defines the paid skill.
Payload object details
Property | Description | Type |
---|---|---|
|
Defines the paid skill. Include one object. |
An array of |
InSkillProduct object
The InSkillProduct
object defines the paid skill ID. Alexa looks up the purchase details by using the skill ID.
Property | Description | Type |
---|---|---|
|
Set to your skill ID. |
String |
Related topics
Last updated: Jun 20, 2022