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 user entitlement status to determine whether to invoke the purchase flow or to continue with paid skill content. This interface returns ENTITLED if the user 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 user 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

Copied to clipboard.

GET /v1/users/~current/skills/~current/inSkillProducts/{id}
Host: {apiEndpoint}
Accept-Language: {locale}
Authorization: Bearer {apiAccessToken}

Request header parameter details

Property Description Type

id

Used to identify the requested skill.

string

apiEndpoint

Set to apiEndpoint property of the System object from the LaunchRequest or IntentRequest.

string

locale

Set to the locale of the user. For example, en-US.

string

apiAccessToken

Access token used for authentication and authorization. Set to apiAccessToken property of the System object from the LaunchRequest or IntentRequest.

string

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.

{
  "id": "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3",
  "type": "ENTITLEMENT",
  "name": "Your skill name",
  "summary": "Description of the skill",
  "entitled": "NOT_ENTITLED",
  "purchasable": "PURCHASABLE",
  "entitledReason": "NOT_PURCHASED",
  "activeEntitlementCount": 0,
  "purchaseMode": "TEST"
}

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.

Property Description Type

id

Used to identify the requested skill.

string

type

Skill payment model.
Valid values: SUBSCRIPTION or ENTITLEMENT (one-time purchase).

enum string

name

Name of the skill in the language provided in the locale request parameter.

string

summary

Description of the skill in the language provided in the locale request parameter.

string

entitled

Indicates if this user can use the paid skill.
Valid values: ENTITLED or NOT_ENTITLED.

enum string

entitledReason

Indicates the reason for the entitled status. When the customer is in a free trial or already purchased the skill, the entitledReason is PURCHASED. AUTO_ENTITLED means that the customer obtained the skill as part of a promotion or other reason. Valid values: PURCHASED, NOT_PURCHASED, AUTO_ENTITLED.

enum string

purchasable

Indicates if the customer can purchase the skill. If the customer already owns the skill, set to NOT_PURCHASABLE.
Valid values: PURCHASABLE or NOT_PURCHASABLE.

enum string

activeEntitlementCount

(Ignore) Always set to zero for paid skills.

integer

purchaseMode

Indicates whether the customer purchased the skill during live skill stage or during development stage. In development state, the customer isn't charged.
Valid values: LIVE or TEST.

enum string

On error, the response body might contain a message string that describes the reason for the error.

Invoke the purchase flow

To start the Amazon purchase flow, invoke the Buy task by using the skill connections interface. You might include an optional message for Alexa to play before the purchase flow.

The follow example shows a request to start the purchase flow.

Copied to clipboard.

return handlerInput.responseBuilder
        .addDirective({
            type: "Connections.SendRequest",
            name: "Buy",
            payload: {
                products: [
                    {
                     identifier: {
                        id: "amzn1.ask.skill.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
                    }      
                }
                ]
            },
            token: "correlationToken"
        })
        .getResponse();

Buy task definition

Property Description Type

type

The type of request.
Set this property to Connections.StartConnection.

string

name

The name of the task to invoke.
Set this property to Buy.

string

payload

Contains the parameters required for purchase.

A Payload request object

token

(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

Invoke the cancel and refund flows

For a cancellation and refund requests, invoke the Cancel task by using the skill connections interface.

Copied to clipboard.

return handlerInput.responseBuilder
        .addDirective({
            type: "Connections.SendRequest",
            name: "Cancel",
            payload: {
                products: [
                    {
                     id: "amzn1.ask.skill.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
                    }
                ]
            },
            token: "correlationToken"
        })
        .getResponse();

Cancel task definition

Property Description Type

type

The type of request.
Set this property to Connections.StartConnection.

string

name

The name of the task to invoke.
Set this property to Cancel.

string

payload

Contains the parameters required for purchase.

A Payload request object

token

(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

Resume your skill

Your skill receives the result of a purchase, cancel, and refund flow as a Connections.Response request. Resume the skill based on the purchaseResult included in the payload.

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.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "message": "optional additional message"
    },
    "token": "correlationToken"
}

Connections.Response definition

Property Description Type

type

The type of request. Always set to Connections.Response.

string

requestId

The unique identifier for the Connections.Response request.

string

timeStamp

The time of the Connections.Response request.

string

name

The name of the request to which this response applies.
Set to either Buy or Cancel.

string

status

The HTTP status result.

A Status object

payload

Contains the results of the purchase or cancel request.

A Payload response object

token

(Optional) An 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

products

Defines the paid skill. Include one object.

An array of InSkillProduct objects

InSkillProduct object

The InSkillProduct object defines the paid skill ID. Alexa looks up the purchase details by using the skill ID.

InSkillProduct object details

Property Description Type

identifier

Defines the paid skill. Include one object.

An Identifier object

Identifier object

The Identifier object defines the paid skill ID. Alexa looks up the purchase details by using the skill ID.

Identifier object details

Property Description Type

id

Set to your skill ID.

string

Payload response object

The Payload object included in the Connections.Response request.

Payload object details

Property Description Type

purchaseResults

The results of the purchase and cancel requests.
Valid values: ACCEPTED, DECLINED, ALREADY_PURCHASED, ERROR.

Continue with the skill based on the result as follows:

  • ACCEPTED – If the result is from a purchase request, the result indicates that the purchase flow succeeded. Continue with paid content. If the result is from a cancel request, the result indicates that the cancel flow succeeded. Continue with free content or end the skill session.

  • DECLINED – If the result is from a purchase request, the result indicates that the customer declined to purchase the skill. Continue with free content or end the skill session. If the result is from a cancel request, the result indicates that the customer declined the cancellation. Continue with paid content.

  • ALREADY_PURCHASED – This result applies to the purchase request only. The result indicates that the customer previously purchased the skill. Continue with paid content.

  • ERROR – During the purchase and cancel flows, Alexa tells the user why the error occurred. Don't repeat an error message or ask the user to try again. Instead, end the skill session.

string

productId

The paid skill ID sent in the request.

string

message

(Optional) Additional details about the cancel or purchase transaction.

string

Status object

The Status object included in the request.

Status object details

Property Description Type

code

The HTTP response status such as 200, 400, 404.

string

message

The HTTP status message, such as OK.

string