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

Copied to clipboard.

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

Request header parameter details

Field Description Type

id

Identifies the paid skill. Use Skill ID in this field.

String

apiEndpoint

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

String

locale

Set to the locale of the customer. 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

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

productId

Identifies the paid skill. Set to skill ID.

String

name

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

String

type

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

String (enum)

summary

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

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.

String (enum)

entitled

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

String (enum)

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.

String (enum)

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.

String (enum)

referenceName

(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.

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

Copied to clipboard.

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();

Copied to clipboard.

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

type

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

String

name

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

String

payload

Contains the parameters required for purchase.

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

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.

The following example shows a request to start the cancellation flow.

Copied to clipboard.

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();

Copied to clipboard.

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

type

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

String

name

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

String

payload

Contains the parameters required for purchase.

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

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

Type of request.
Always set to Connections.Response.

String

requestId

Unique identifier for the Connections.Response request.

String

timeStamp

Time of the Connections.Response request.

String

name

Name of the request to which this response applies.
Set to either Buy or Cancel (for cancellation or refund).

String

status

HTTP status result.

Object

status.code

HTTP response status such as 200, 400, 404.

String

status.message

HTTP status message, such as OK, Not Found, Not Authorized.

String

payload

Contains the results of the purchase or cancel transaction.

Object

payload.purchaseResult

Result of the purchase or cancel request.
Valid values: ACCEPTED, PENDING_PURCHASE, 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.

  • PENDING_PURCHASE – The purchase flow is in-progress and might take longer than expected. Check the customer entitlement for the skill. If the response indicates that the customer paid for the skill (entitled = ENTITLED), continue with paid content. Otherwise, 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

payload.productId

Paid skill ID sent in the request.

String

payload.message

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

String

token

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.

Property Description Type

productId

Set to your skill ID.

String

Last updated: Jun 20, 2022