Alexa Shopping Actions API Reference

Note: Submit your skill and see it come to life.

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	`connection://AMAZON.AddToList/1`
Add to shopping cart	`connection://AMAZON.AddToShoppingCart/1`
Buy products	`connection://AMAZON.BuyShoppingProducts/1`
Recommend products	`connection://AMAZON.RecommendShoppingProducts/1`

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.

Important: Amazon Confidential. Amazon licensed these materials to you as Restricted Program Materials under the Program Materials License Agreement in connection with the Alexa Skills Program.

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`	Input parameters for the task request.	Object	Yes
`input.products`	List of Amazon products. Maximum items: 1.	Array of `ProductEntity` objects	Yes
`input.products[].asin`	Amazon system identifier for a product. For details, see ASIN for a product.	String	Yes
`input.listType`	Identifies the list type. Valid value: `WISHLIST`	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.

Note: Always check the 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
`code`	Identifies the error.	String	Yes
`message`	Human-readable description of the error.	String	Yes

Result codes

Code	Message	Description
`AlexaShopping.InternalError`	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.
`AlexaShopping.InvalidTaskForMarketplace`	This operation is not available for this locale.	Requested Alexa Shopping action isn't supported in this locale.
`AlexaShopping.ItemNotEligible`	The item you specified is not eligible for Alexa Shopping Actions. Or, the item is not accessible through Alexa Shopping.	Indicates that the item isn't eligible for use with Alexa Shopping. For example, the item is digital or the item isn't supported for legal reasons.
`AlexaShopping.NoOffersFound`	We did not find any matches for your request.	Request item wasn't found. For example, the item is out of stock.
`AlexaShopping.RetryLaterError`	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. The issue is recoverable. Try again later.

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`	Input parameters for the task request.	Object	Yes
`input.products`	List of Amazon products. Maximum items: 1.	Array of `ProductEntity` objects	Yes
`input.products[].asin`	Amazon system identifier for a product. For details, see ASIN for a product.	String	Yes
`input.products[].attribution`	Include if your skill is part of the Amazon Associates on Alexa program.	`Attribution` object	No

Response

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
`code`	Identifies the error.	String	Yes
`message`	Human-readable description of the error.	String	Yes

Result codes

Code	Message	Description
`AlexaShopping.InternalError`	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.
`AlexaShopping.InvalidTaskForMarketplace`	This operation is not available for this locale.	Requested Alexa Shopping action isn't supported in this locale.
`AlexaShopping.ItemNotEligible`	The item you specified is not eligible for Alexa Shopping Actions. Or, the item is not accessible through Alexa Shopping.	Indicates that the item isn't eligible for use with Alexa Shopping. For example, the item is digital or the item isn't supported for legal reasons.
`AlexaShopping.NoOffersFound`	We did not find any matches for your request.	Request item wasn't found. For example, the item is out of stock.
`AlexaShopping.RetryLaterError`	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. The issue is recoverable. Try again later.

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`	Input parameters for the task request.	Object	Yes
`input.products`	List of Amazon products. Maximum items: 1.	Array of `ProductEntity` objects	Yes
`input.products[].asin`	Amazon system identifier for a product. For details, see ASIN for a product.	String	Yes
`input.products[].attribution`	Include if your skill is part of the Amazon Associates on Alexa program.	`Attribution` object	No

Response

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
`code`	Identifies the error.	String	Yes
`message`	Human-readable description of the error.	String	Yes

Result codes

Code	Message	Description
`AlexaShopping.InternalError`	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.
`AlexaShopping.InvalidTaskForMarketplace`	This operation is not available for this locale.	Requested Alexa Shopping action isn't supported in this locale.
`AlexaShopping.ItemNotEligible`	The item you specified is not eligible for Alexa Shopping Actions. Or, the item is not accessible through Alexa Shopping.	Indicates that the item isn't eligible for use with Alexa Shopping. For example, the item is digital or the item isn't supported for legal reasons.
`AlexaShopping.NoOffersFound`	We did not find any matches for your request.	Request item wasn't found. For example, the item is out of stock.
`AlexaShopping.RetryLaterError`	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. The issue is recoverable. Try again later.

Recommend products to the customer. Include the request as a directive input from your response handler.

Important: The 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.

{
    "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"
}

The following table shows the definition of the task-specific input parameter.

Field	Description	Type	Required
`input`	Input parameters for the task request.	Object	Yes
`input.products`	List of Amazon products. Maximum items: 10.	Array of `ProductEntity` objects	Yes
`input.products[].asin`	Amazon system identifier for a product. For details, see ASIN for a product.	String	Yes
`input.attribution`	Include if your skill is part of the Amazon Associates on Alexa program. This attribution applies to all products.	`Attribution` object	No

Alexa sends a response on skill connection failure only. For details, see System.ExceptionEncountered.

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"
    }
}

There are no task-specific response parameters. 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.

Important: If you provide invalid attribution parameter values or don't include the 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
`associateId`	Identifies your Associates account.	String	Yes
`trackingId`	Optional identifier to track this skill. For more detail about tracking IDs in your Associates account, see Using Tracking IDs.	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
`asin`	Amazon system identifier for a product. For details, see ASIN for a product.	String	Yes

Last updated: Oct 07, 2022

Alexa Shopping Actions API Reference

Shopping actions

Add to list

Request

Request example

Request parameters

Response

Response example

Response parameters

Result codes

Add to shopping cart

Request

Request example

Request parameters

Response

Response example

Response parameters

Result codes

Buy products action

Request

Request example

Request parameters

Response

Response example

Response parameters

Result codes

Recommend products

Request

Request example

Request parameters

Response

Response example

Response parameters

Object definitions

Attribution object

ProductEntity object

Related topics