Implement Alexa Shopping Actions in Your Skill


After the customer confirms interest in a product, you hand off the shopping interaction to Alexa by using Alexa Shopping Actions APIs. All actions start a multi-turn interaction between Alexa and the customer to complete the shopping experience.

Follow these instructions to implement the hand-over to Alexa and resume the skill session for each shopping action that your skill uses.

How to identify the product

Alexa Shopping Actions operate on a common ProductEntity object that represents a unique product within Amazon. When you invoke the API, you include an Amazon Standard Identification Number (ASIN) to identify the product. 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

Use skill connections with shopping tasks

You delegate the Alexa shopping flow to Alexa by using the skill connections interface to invoke one of the following predefined tasks:

  • To add a product to the customer's Cart, use AMAZON.AddToShoppingCart.
  • To add a product to the customer's Amazon list, use AMAZON.AddToList.
  • To enable the customer to purchase a product, use the AMAZON.BuyShoppingProducts action to transfer the shopping and checkout process to Alexa.
  • To recommend up to 10 products to the customer to hear more about, use the AMAZON.RecommendShoppingProducts action.

All actions start a multi-turn interaction between Alexa and the customer to complete the shopping experience. Before you transfer control to Alexa, make sure that you save any important session information. After the action completes, Alexa hands control back to your skill. Resume your skill based on the results of the action. Make sure that your skill handles decline and errors gracefully. For more details about the shopping action tasks, see Shopping Actions API Reference.

Implement add-to-cart

When your skill invokes the AMAZON.AddToShoppingCart action, Alexa presents the purchase details of the recommended product and asks for confirmation to add the product to the customer's Cart. The customer can review this item later by visiting the Amazon retail website. The customer doesn't make the purchasing decision during the skill session.

Send a directive to add a product to a shopping cart

After you ask the customer for permission to add the product to their Cart, you can send the Connections.StartConnection directive to Alexa with the AMAZON.AddToShoppingCart payload.

The following example shows a request to add the specified product to the cart.

Handle a session resumed request

Your skill receives the result of the AMAZON.AddToShoppingCart request as a SessionResumedRequest response. Implement a handler to receive the response.

The response includes the token given in the AMAZON.AddToShoppingCart request. Use the token value to restore the previous session of the skill before you invoked the action. Resume the skill based on the result included in the payload. You can use the result to alter the skill experience and handle errors. For more details, see Receive a response from a skill connections request.

The following example shows how to handle a session resumed request response.

Implement add-to-list

When your skill invokes the AMAZON.AddToList action, Alexa presents details of the recommended product and asks for confirmation to add the product to the customer's Amazon list. The customer can review this item later by visiting the Amazon retail website. Customers can add items to the list even if they don't define customer settings, such as payment method and delivery address.

Send a directive to add a product to a list

After you ask the customer for permission to add the product to their list, you can send the Connections.StartConnection directive to Alexa with the AMAZON.AddToList payload.

The following example shows a request to add the specified product to the list.

Handle a session resumed request

Your skill receives the result of the AMAZON.AddToList request as a SessionResumedRequest response. Implement a handler to receive the response.

The response includes the token given in the AMAZON.AddToList request. Use the token value to restore the previous session of the skill before you invoked the action. Resume the skill based on the result included in the payload. You can use the result to alter the skill experience and handle errors. For more details, see Receive a response from a skill connections request.

The following example shows how to handle a session resumed request response.

Implement purchase-product

The AMAZON.BuyShoppingProducts action helps the customer purchase a recommended product. When you invoke the action, Alexa takes the customer through a multi-turn interaction that presents the product and final price, and asks for confirmation to purchase the product. The purchasing workflow incorporates various checks. These checks include valid payment method, delivery address, and voice PIN authorization associated with the customer account.

Send a directive to buy a product

After your skill receives permission from the customer to shop for the product, you send the Connections.StartConnection directive to Alexa with the AMAZON.BuyShoppingProducts payload.

The follow example shows a request to start the product purchase flow.

Handle a session resumed request

Your skill receives the result of a purchase as a SessionResumedRequest. Implement a handler to receive the response.

The response includes the token given in the AMAZON.BuyShoppingProducts request. Use the token value to restore the previous session of the skill before you invoked the action. Resume the skill based on the result included in the payload. For more details, see Receive a response from a skill connections request.

If the action fails, Alexa informs the customer of the error and provides available recovery mechanisms to the customer. Alexa returns the error to your skill in the payload of the response. Don't notify the customer about the error, but use the result to alter the flow of skill execution.

The following example shows how to handle a session resumed request response.

Implement recommend-products

When your skill invokes the AMAZON.RecommendShoppingProducts action, Alexa presents details of the recommended products. Then, the customer can add one or more items to their Cart, buy the items, or continue with the skill. Customers can add items to the Cart even if they don't define customer settings, such as payment method and delivery address.

Send a directive to recommend products

After you ask the customer for permission to learn more about recommended products, you can send the Connections.StartConnection directive to Alexa with the AMAZON.RecommendShoppingProducts payload. Here, you request a response on error only by setting oncompletion = SEND_ERRORS_ONLY.

The following example shows a request to add the specified product to the list.

Handle a session error

For the AMAZON.RecommendShoppingProducts action, Alexa only sends a response on skill connection failure. Your skill receives the response as a System.ExceptionEncountered response. For details, see System.ExceptionEncountered. If you want to know if an error occurred, implement a handler to receive the response.

The following example shows how to receive a System.ExceptionEncountered response.

Copied to clipboard.

/**
* Handler for ExceptionEncountered.
*/
const SystemExceptionEncounteredHandler = {
   canHandle(handlerInput) {
      const request = handlerInput.requestEnvelope.request;
      return request.type === 'System.ExceptionEncountered';
   },
   handle(handlerInput) {
      console.dir(handlerInput.requestEnvelope.request);
      return handlerInput.responseBuilder
         .getResponse();
   },
};

Handle a refund request

If you implement the purchase-product or recommend-products shopping actions, you must also implement a refund intent to receive the refund request and provide instructions to the customer. In your handler, direct the customer to review the order in their Amazon account on the Amazon retail page. No Alexa Shopping Actions task exists to process a refund.

The following example shows a refund handler.

Copied to clipboard.

 /**
* Handler for Refund intent.
*/
 const RefundHandler = {
     canHandle(handlerInput) {
        const request = handlerInput.requestEnvelope.request;
        return request.type === 'IntentRequest'
            && (request.intent.name === 'RefundIntent');
     },
     handle(handlerInput) {
        console.log("RefundIntent received.");
        return handlerInput.responseBuilder
        .speak("Please go to the orders section of your Amazon account to review or cancel your order.")
        .getResponse();
     },
 }

Sample code

The following sample code demonstrates how to use the add-to-cart and purchase-product actions:


Was this page helpful?

Last updated: Nov 23, 2023