Paid Skills Task Reference

Use the paid skill tasks with skill connections to invoke the Amazon purchase and cancellation flows. Before you invoke the purchase flow, make sure to get customer entitlement status to determine if the customer already purchased the skill.

Skill connections enable a skill to use another skill to perform a specific task. Before you implement the paid skills tasks, review the following topics:

Tasks

The paid skills interface include the following tasks.

Task Task name

Buy request

Buy

Cancel request

Cancel

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 code example 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 code example 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.

Array objects

products[].productId

Set to your skill ID.

String

Was this page helpful?

Last updated: Mar 26, 2024