Alexa Shopping Actions API Reference

To add a shopping experience to your skill, use the Alexa Shopping Actions API. Your skill uses skill connections to invoke Amazon predefined tasks to start the Alexa shopping interaction. Skill connections enable a skill to use another skill to perform a specific task. Before you use the Alexa Shopping Actions API, review the following topics:

For examples of how to implement the API in your skill, see Implement Alexa Shopping Actions in Your Skill.

For a list of possible errors, see Alexa Shopping Actions Error Reference.

The ProductEntity object

Alexa Shopping Actions operate on a common ProductEntity object. The ProductEntity represents a unique product within Amazon. When you invoke the API, you include an Amazon Standard Identification Number (ASIN) to identify the object. The ASIN is a 10-character alphanumeric unique identifier assigned by Amazon for product identification within Amazon.

You can find an ASIN for a product on the product detail page in two locations:

  1. In the URL for the product detail page in the format <Domain-Name>/dp/<asin>
  2. In the Product information section

ProductEntity object parameter details

Name Required? Type Description
asin Yes String

An Amazon System Identifier for a product.
For details, see Amazon Standard Identification Number.

AddToShoppingCart action

Add the given items to the Amazon Shopping Cart of the customer. This action works for non-digital products only. For details, see the Alexa Shopping Actions for Alexa Skills FAQ.

AddToShoppingCart action parameter details

Name Required? Type Description
products Yes

array of ProductEntity

Contains a list of Amazon product entities. Currently, the list supports a single item.
type Yes

String

Type of the directive, which is Connections.StartConnection in this example.
uri Yes

String

Resource that defines the task and the task version, which is connections://AMAZON.AddToShoppingCart/1 in this example.
input Yes

object containing products

The request object for the task request.
token No

String

A token that comes back to the skill as-is in the SessionResumedRequest. You can use it to resume the skill after the task request is complete.

Example request with payload

Include the request as a directive input from your response handler.

{
  "type": "Connections.StartConnection",
  "uri": "connection://AMAZON.AddToShoppingCart/1",
  "input": {
    "products": [
      {
        "asin": "B01962MDHA"
      }
    ]
  },
  "token": "AddToShoppingCartToken"
}

BuyShoppingProducts action

Purchase the given products.

BuyShoppingProducts action parameter details

Name Required? Type Description
products Yes

array of ProductEntity

Contains a list of Amazon product entities. Currently, the list supports a single item.
type Yes

String

Type of the directive, which is Connections.StartConnection in this example.
uri Yes

String

Resource that defines the task and the task version, which is connections://AMAZON.BuyShoppingProducts/1 in this example.
input Yes

object containing products

The request object for the task request.
token No

String

A token that comes back to the skill as-is in the SessionResumedRequest. You can use it to resume the skill after the task request is complete.

Example request with payload

Include the request as a directive input from your response handler.

{
  "type": "Connections.StartConnection",
  "uri": "connection://AMAZON.BuyShoppingProducts/1",
  "input": {
    "products": [
      {
        "asin": "B01962MDHA"
      }
    ]
  },
  "token": "PurchaseProductToken"
}

Skill connections response

Both AddToShoppingCart and BuyShoppingProducts return a Connections.Response. Your skill must implement a SessionResumedHandler handler to receive the response. In your handler, use the token to restore the previous session of the skill before you invoked the action. Inspect the cause under handlerInput.requestEnvelope.request. To determine if the action succeeded, look at the result and status parameters.

The result parameter

The result parameter is optional and might not be present.

result parameter details

Name Required? Type Description
code Yes

String

A unique string that identifies the error.
message Yes

String

A human-readable description of the error to help the requester debug the issue.

The status parameter

For details about the status parameter in the skill connections response, see Status code attributes.

status parameter details

Name Required? Type Description
code Yes

Number

The status code defined in the skill connections response.
message No

Object that contains a domain-specific response

If there is a failure, the message object indicates the domain-specific error status code and message.

Example response

The following is an example response for a returned error.

{
   "type": "Connections.Response",
   "status": {
      "code": "200",
      "message": "Success"
   },
   "result": {
      "code": "AlexaShopping.RetryLaterError",
      "message": "Encountered an error when trying to process the request, please try again later."
   },
   "token": "PurchaseProductToken"
}