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:
- In the URL for the product detail page in the format
<Domain-Name>/dp/<asin>
- In the Product information section
ProductEntity object parameter details
Name | Required? | Type | Description |
---|---|---|---|
asin |
Yes | String |
An Amazon System Identifier for a product. |
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 |
Contains a list of Amazon product entities. Currently, the list supports a single item. |
type |
Yes |
String |
Type of the directive, which is |
uri |
Yes |
String |
Resource that defines the task and the task version, which is |
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 |
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 |
Contains a list of Amazon product entities. Currently, the list supports a single item. |
type |
Yes |
String |
Type of the directive, which is |
uri |
Yes |
String |
Resource that defines the task and the task version, which is |
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 |
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. The skill connections response operates on an HTTP level and might return a 200 status code even if there's a problem with the request. The result
parameter indicates if there's any underlying issue while performing the request.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"
}