Alexa Shopping Actions API Reference
To add a shopping experience to your skill, use the Alexa Shopping Actions API to recommend products from the Amazon retail website. 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.
Shopping actions
The Alexa Shopping actions include the following tasks.
| Shopping action | Task name and version |
|---|---|
|
| |
|
| |
|
| |
|
|
Add to list
Add the specified items to the customer's Amazon Wish List. At this time, the action works for the Wish List only, not for the Amazon Shopping List.
This feature is a developer preview and might change as Amazon receives feedback and iterates on the feature. To use this feature, contact your Amazon business representative.
Request
To add products to the customer's Wish List, add a Connections.StartConnection directive to your response.
Request example
{
"type": "Connections.StartConnection",
"uri": "connection://AMAZON.AddToList/1",
"input": {
"products": [
{
"asin": "ASIN1"
}
],
"listType": "WISHLIST"
},
"token": "Skill-specific session information"
}
Request parameters
The following table shows the definition of the task-specific input parameter.
| Field | Description | Type | Required |
|---|---|---|---|
|
|
Input parameters for the task request. |
Object |
Yes |
|
|
List of Amazon products. |
Array of |
Yes |
|
|
Amazon system identifier for a product. For details, see ASIN for a product. |
String |
Yes |
|
|
Identifies the list type. |
String |
Yes |
Response
The task returns a SessionResumedRequest response that contains the result of the action.
To determine if the action succeeded, check the cause.status and task-specific cause.result parameters. The cause.status parameter includes an HTTP status code. For a list of status codes, see Status code attributes in SessionResumedRequest.
cause.result parameter. The cause.status parameter might return a 200 OK even if there's a problem with the request. The cause.result parameter indicates if there's an issue performing the shopping action.Response example
The following example shows a successful response.
{
"type": "SessionResumedRequest",
"requestId": "Unique id for the request",
"timestamp": "2022-04-11T15:15:25Z",
"locale": "en-US",
"cause": {
"type": "ConnectionCompleted",
"token": "Skill-specific session information to restore the skill session",
"status": {
"code": "200",
"message": "OK"
}
}
}
Response parameters
The following table shows the definition of the task-specific result parameter. The result parameter is optional. For details about the return values, see Result codes.
| Field | Description | Type | Required |
|---|---|---|---|
|
|
Identifies the error. |
String |
Yes |
|
|
Human-readable description of the error. |
String |
Yes |
Result codes
| Code | Message | Description |
|---|---|---|
|
|
We're unable to process your request at this time. Please retry your request. If you encounter this error repeatedly, please reach out to Customer Support. |
Internal problem or outage prevented Alexa Shopping from completing your request. |
|
|
This operation is not available for this locale. |
Requested Alexa Shopping action isn't supported in this locale. |
|
|
The item you specified is not eligible for Alexa Shopping Actions. |
Indicates that the item isn't eligible for use with Alexa Shopping. |
|
|
We did not find any matches for your request. |
Request item wasn't found. For example, the item is out of stock. |
|
|
We encountered an error when trying to process the request, please try again later. |
Issue occurred while executing the task. For example, the customer has invalid settings or Alexa Shopping had a temporary issue. |
Add to shopping cart
Add the specified items to the customer's Amazon Shopping Cart. This action works for non-digital products only. For details, see the Alexa Shopping Actions for Alexa Skills FAQ.
Request
To add products to the customer's shopping cart, add a Connections.StartConnection directive to your response.
Request example
{
"type": "Connections.StartConnection",
"uri": "connection://AMAZON.AddToShoppingCart/1",
"input": {
"products": [
{
"asin": "ASIN1"
}
]
},
"token": "Skill-specific session information"
}
Request parameters
The following table shows the definition of the task-specific input parameter.
| Field | Description | Type | Required |
|---|---|---|---|
|
|
Input parameters for the task request. |
Object |
Yes |
|
|
List of Amazon products. |
Array of |
Yes |
|
|
Amazon system identifier for a product. For details, see ASIN for a product. |
String |
Yes |
Response
The task returns a SessionResumedRequest response that contains the result of the action.
To determine if the action succeeded, check the cause.status and task-specific cause.result parameters. The cause.status parameter includes an HTTP status code. For a list of status codes, see Status code attributes in SessionResumedRequest.
cause.result parameter. The cause.status parameter might return a 200 OK even if there's a problem with the request. The cause.result parameter indicates if there's an issue performing the shopping action.Response example
The following example shows an error response.
{
"type": "SessionResumedRequest",
"requestId": "Unique id for the request",
"timestamp": "2022-04-11T15:15:25Z",
"locale": "en-US",
"cause": {
"type": "ConnectionCompleted",
"token": "Skill-specific session information to restore the skill session",
"status": {
"code": "200",
"message": "OK"
},
"result": {
"code": "AlexaShopping.RetryLaterError",
"message": "Encountered an error when trying to process the request, please try again later."
}
}
}
Response parameters
The following table shows the definition of the task-specific result parameter. The result parameter is optional. For details about the return values, see Result codes.
| Field | Description | Type | Required |
|---|---|---|---|
|
|
Identifies the error. |
String |
Yes |
|
|
Human-readable description of the error. |
String |
Yes |
Result codes
| Code | Message | Description |
|---|---|---|
|
|
We're unable to process your request at this time. Please retry your request. If you encounter this error repeatedly, please reach out to Customer Support. |
Internal problem or outage prevented Alexa Shopping from completing your request. |
|
|
This operation is not available for this locale. |
Requested Alexa Shopping action isn't supported in this locale. |
|
|
The item you specified is not eligible for Alexa Shopping Actions. |
Indicates that the item isn't eligible for use with Alexa Shopping. |
|
|
We did not find any matches for your request. |
Request item wasn't found. For example, the item is out of stock. |
|
|
We encountered an error when trying to process the request, please try again later. |
Issue occurred while executing the task. For example, the customer has invalid settings or Alexa Shopping had a temporary issue. |
Buy products action
Purchase the specified products. Include the request as a directive input from your response handler.
Request
To enable the customer to purchase the product, add a Connections.StartConnection directive to your response.
Request example
{
"type": "Connections.StartConnection",
"uri": "connection://AMAZON.BuyShoppingProducts/1",
"input": {
"products": [{
"asin": "ASIN1"
}]
},
"token": "PurchaseProductToken"
}
Request parameters
The following table shows the definition of the task-specific input parameter.
| Field | Description | Type | Required |
|---|---|---|---|
|
|
Input parameters for the task request. |
Object |
Yes |
|
|
List of Amazon products. |
Array of |
Yes |
|
|
Amazon system identifier for a product. For details, see ASIN for a product. |
String |
Yes |
Response
The task returns a SessionResumedRequest response that contains the result of the action.
To determine if the action succeeded, check the cause.status and task-specific cause.result parameters. The cause.status parameter includes an HTTP status code. For a list of status codes, see Status code attributes in SessionResumedRequest.
cause.result parameter. The cause.status parameter might return a 200 OK even if there's a problem with the request. The cause.result parameter indicates if there's an issue performing the shopping action.Response example
The following example shows an error response.
{
"type": "SessionResumedRequest",
"requestId": "Unique id for the request",
"timestamp": "2022-04-11T15:15:25Z",
"locale": "en-US",
"cause": {
"type": "ConnectionCompleted",
"token": "Skill-specific session information to restore the skill session",
"status": {
"code": "200",
"message": "OK"
},
"result": {
"code": "AlexaShopping.RetryLaterError",
"message": "Encountered an error when trying to process the request, please try again later."
}
}
}
Response parameters
The following table shows the definition of the task-specific result parameter. The result parameter is optional. For details about the return values, see Result codes.
| Field | Description | Type | Required |
|---|---|---|---|
|
|
Identifies the error. |
String |
Yes |
|
|
Human-readable description of the error. |
String |
Yes |
Result codes
| Code | Message | Description |
|---|---|---|
|
|
We're unable to process your request at this time. Please retry your request. If you encounter this error repeatedly, please reach out to Customer Support. |
Internal problem or outage prevented Alexa Shopping from completing your request. |
|
|
This operation is not available for this locale. |
Requested Alexa Shopping action isn't supported in this locale. |
|
|
The item you specified is not eligible for Alexa Shopping Actions. |
Indicates that the item isn't eligible for use with Alexa Shopping. |
|
|
We did not find any matches for your request. |
Request item wasn't found. For example, the item is out of stock. |
|
|
We encountered an error when trying to process the request, please try again later. |
Issue occurred while executing the task. For example, the customer has invalid settings or Alexa Shopping had a temporary issue. |
Recommend products
Recommend products to the customer. Include the request as a directive input from your response handler.
AMAZON.RecommendShoppingProducts Alexa Shopping action is a developer preview and might change as Amazon receives feedback and iterates on the feature. To use this feature, contact your Amazon business representative.Request
To enable the customer to hear recommendations for specific products, add a Connections.StartConnection directive to your response.
Request example
{
"type": "Connections.StartConnection",
"uri": "connection://AMAZON.RecommendShoppingProducts/1",
"input": {
"products": [{
"asin": "ASIN1"
},
{
"asin": "ASIN2"
},
{
"asin": "ASIN3"
}
]
},
"token": "RecommendProducts",
"onCompletion": "SEND_ERRORS_ONLY"
}
Request parameters
The following table shows the definition of the task-specific input parameter.
| Field | Description | Type | Required |
|---|---|---|---|
|
|
Input parameters for the task request. |
Object |
Yes |
|
|
List of Amazon products. |
Array of |
Yes |
|
|
Amazon system identifier for a product. For details, see ASIN for a product. |
String |
Yes |
Response
Alexa sends a response on skill connection failure only. For details, see System.ExceptionEncountered.
Response example
The following example shows an error response.
{
"type": "System.ExceptionEncountered",
"requestId": "Unique id for the request",
"timestamp": "2022-04-11T15:15:25Z",
"locale": "en-US",
"error": {
"type": "error code",
"message": "description of the error that occurred"
},
"cause": {
"requestId": "unique identifier for the task that caused the error"
}
}
Response parameters
There are no task-specific response parameters. Use the cause.requestId to correlate the error with the request.