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 list. At this time, this action works for the Amazon 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 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",
"attribution": {
"associateId": "some.associate.id",
"trackingId": "some.tracking.id"
}
}
]
},
"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. |
String |
Yes |
|
|
Include if your skill is part of the Amazon Associates on Alexa program. |
|
No |
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 |
|---|---|---|
|
|
Associates parameter invalid, please check. |
(For skills that attribute purchases to the Associates program only.) An attribution parameter is invalid and the shopping action wasn't attributed to your Associates account. Important: This issue doesn't impact the requested shopping action, but the error does override other potential errors. It's important that you address this error so that your skill can receive other error codes.
|
|
|
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 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",
"attribution": {
"associateId": "some.associate.id",
"trackingId": "some.tracking.id"
}
}]
},
"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. |
String |
Yes |
|
|
Include if your skill is part of the Amazon Associates on Alexa program. |
|
No |
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 |
|---|---|---|
|
|
Associates parameter invalid, please check. |
(For skills that attribute purchases to the Associates program only.) An attribution parameter is invalid and the shopping action wasn't attributed to your Associates account. Important: This issue doesn't impact the requested shopping action, but the error does override other potential errors. It's important that you address this error so that your skill can receive other error codes.
|
|
|
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 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"
}
],
"attribution": {
"associateId": "some.associate.id.1",
"trackingId": "some.tracking.id.1"
}
},
"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. |
String |
Yes |
|
|
Include if your skill is part of the Amazon Associates on Alexa program. This attribution applies to all products. |
|
No |
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
No task-specific response parameters are defined. Use the cause.requestId to correlate the error with the request.
Object definitions
Attribution object
To earn commission on qualifying purchases, include the Attribution object in your shopping action request.
Include this object for live skills that are part of the Amazon Associates on Alexa program only.
Attribution object in your request, you don't earn commission on the purchase.The following table shows the definition of the Attribute object.
| Field | Description | Type | Required |
|---|---|---|---|
|
|
Identifies your Associates account. |
String |
Yes |
|
|
Optional identifier to track this skill. |
String |
No |
ProductEntity object
The ProductEntity object represents a unique product within Amazon. To find the product identifier, locate the Amazon Standard Identification Number (ASIN) on the product detail page on the Amazon retail website. For details, see Product identity.
| Field | Description | Type | Required |
|---|---|---|---|
|
|
Amazon system identifier for a product. For details, see ASIN for a product. |
String |
Yes |
Related topics
Last updated: Nov 23, 2023