Note: Sign in to the developer console to build or publish 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.
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:
In the URL for the product detail page in the format <Domain-Name>/dp/<asin>
In the product information section
Note: Each product has a unique product page for each marketplace where you sell the item. The skill must keep track of the ASINs for every locale where you use Alexa Shopping Actions.
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.
Note: Amazon recommends this action because it has little room for error. For example, the customer can add items to the cart even if they don't define customer settings — including payment method and delivery address.
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.
Note:Connections.StartConnection exits the current skill session. Before you send the request, save important details about the session. Also, you can save any information required to restore the session in the token parameter.
The following example shows a request to add the specified product to the cart.
Copied to clipboard.
/**
* Handler for RecommendAndAddToCart intent.
*/constRecommendAndAddToCartHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='IntentRequest'&&(request.intent.name==='RecommendAndAddToCart');},handle(handlerInput){console.log("AmazoRecommendAndAddToCartreceived.");constspeechText="<Product intro>"+" Would you like to add this to your cart on Amazon?"returnhandlerInput.responseBuilder.speak(speechText).reprompt(speechText).getResponse();}};/**
* Handler for YesIntent and NoIntent.
*/constYesAndNoIntentHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='IntentRequest'&&(request.intent.name==='AMAZON.YesIntent'||request.intent.name==='AMAZON.NoIntent');},handle(handlerInput){constintentName=handlerInput.requestEnvelope.request.intent.name;console.log("User said : "+intentName);if(intentName==='AMAZON.YesIntent'){varactionText="Staging item with Amazon"letactionTask={'type':'Connections.StartConnection','uri':'connection://AMAZON.AddToShoppingCart/1','input':{'products':[{'asin':'ASN1'}]},'token':'AddToShoppingCartToken'};returnhandlerInput.responseBuilder.speak(actionText).addDirective(actionTask).getResponse();}constspeechText="All right. Please come back if you need more product recommendations."returnhandlerInput.responseBuilder.speak(speechText).getResponse();}};
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.
Copied to clipboard.
/**
* Handler for SessionResumedRequest.
*/constSessionResumedRequestHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='SessionResumedRequest';},handle(handlerInput){// Session attributes and ID are same as previous IntentRequestconstsessionAttributes=handlerInput.attributesManager.getSessionAttributes();console.log("sessionAttributes : "+JSON.stringify(sessionAttributes));consttoken=handlerInput.requestEnvelope.request.cause.token;letrequest=handlerInput.requestEnvelope.request;letspeechText="Sorry, I had trouble doing what you asked. Please try again.";if(request.cause){consttoken=request.cause.token;conststatus=request.cause.status;constcode=status.code;constmessage=status.message;constpayload=request.cause.result;console.info(`[Shopping Response] ${JSON.stringify(request)}`);console.info(`[INFO] Shopping Action Result: Code - ${code}, Message - ${message}, Payload - ${payload}`);switch(code){case'200':if(typeofpayload!=="undefined"){if(payload.code==="AlexaShopping.RetryLaterError"){speechText="Looks like there was an issue. Let's get back to the skill.";}elseif(payload.code==="AlexaShopping.AssociatesInvalidInputError"&&token==="AddToShoppingCartToken"){console.info(`[INFO] Shopping Action had an issue while performing Associates attribution. ${payload.message}`);speechText="Thank you for shopping with Alexa.";}else{speechText="I'm sorry, shopping indicated an issue while performing your request. Please try again later.";console.info(`[INFO] Shopping Action had an issue while performing the request. ${payload.message}`);}}elseif(token==="AddToShoppingCartToken"){console.info(`[INFO] Shopping Action: Add to cart action was a success for ${token}.`);speechText="Thank you for shopping with Alexa.";}break;default:console.info(`[INFO] Shopping Action: There was a problem performing the shopping action.`);speechText="There was a problem adding the item to your cart.";}}returnhandlerInput.responseBuilder.speak(speechText).getResponse();},};
Implement add-to-list
Important: The AMAZON.AddToList 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.
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.
Note: At this time, the AMAZON.AddToList shopping action supports the Amazon Wish List only.
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.
Note:Connections.StartConnection exits the current skill session. Before you send the request, save important details about the session. Also, you can save any information required to restore the session in the token parameter.
The following example shows a request to add the specified product to the list.
Copied to clipboard.
/**
* Handler for RecommendAndAddToList intent.
*/constRecommendAndAddToListHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='IntentRequest'&&(request.intent.name==='RecommendAndAddToList');},handle(handlerInput){console.log("AmazoRecommendAndAddToList received.");constspeechText="<Product intro>"+" Would you like to add this to your wish list on Amazon?"returnhandlerInput.responseBuilder.speak(speechText).reprompt(speechText).getResponse();}};/**
* Handler for YesIntent and NoIntent.
*/constYesAndNoIntentHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='IntentRequest'&&(request.intent.name==='AMAZON.YesIntent'||request.intent.name==='AMAZON.NoIntent');},handle(handlerInput){constintentName=handlerInput.requestEnvelope.request.intent.name;console.log("User said : "+intentName);if(intentName==='AMAZON.YesIntent'){varactionText="Staging item with Amazon"letactionTask={'type':'Connections.StartConnection','uri':'connection://AMAZON.AddToList/1','input':{'products':[{'asin':'ASN1'}],"listType":"WISHLIST"},'token':'AddToListToken'};returnhandlerInput.responseBuilder.speak(actionText).addDirective(actionTask).getResponse();}constspeechText="All right. Please come back if you need more product recommendations."returnhandlerInput.responseBuilder.speak(speechText).getResponse();}};
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.
Copied to clipboard.
/**
* Handler for SessionResumedRequest.
*/constSessionResumedRequestHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='SessionResumedRequest';},handle(handlerInput){// Session attributes and ID are same as previous IntentRequestconstsessionAttributes=handlerInput.attributesManager.getSessionAttributes();console.log("sessionAttributes : "+JSON.stringify(sessionAttributes));consttoken=handlerInput.requestEnvelope.request.cause.token;letrequest=handlerInput.requestEnvelope.request;letspeechText="Sorry, I had trouble doing what you asked. Please try again.";if(request.cause){consttoken=request.cause.token;conststatus=request.cause.status;constcode=status.code;constmessage=status.message;constpayload=request.cause.result;console.info(`[Add to List Response] ${JSON.stringify(request)}`);console.info(`[INFO] Shopping Action Result: Code - ${code}, Message - ${message}, Payload - ${payload}`);switch(code){case'200':if(typeofpayload!=="undefined"){if(payload.code==="AlexaShopping.RetryLaterError"){speechText="Looks like there was an issue. Let's get back to the skill.";}else{speechText="I'm sorry, shopping indicated an issue while performing your request. Please try again later.";console.info(`[INFO] Shopping Action had an issue while performing the request. ${payload.message}`);}}elseif(token==="AddToListToken"){console.info(`[INFO] Shopping Action: Add to list action was a success for ${token}.`);speechText="Thank you for shopping with Alexa.";}break;default:console.info(`[INFO] Shopping Action: There was a problem performing the shopping action.`);speechText="There was a problem adding the item to your list.";}}returnhandlerInput.responseBuilder.speak(speechText).getResponse();},};
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.
Note:Connections.StartConnection exits the current skill session. Before you send the request, save important details about the session. Also, you can save any information required to restore the session in the token parameter.
The follow example shows a request to start the product purchase flow.
Copied to clipboard.
/**
* Handler for RecommendAndShopForProducts intent.
*/constRecommendAndShopForProductsHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='IntentRequest'&&(request.intent.name==='RecommendAndShopForProducts');},handle(handlerInput){console.log("RecommendAndShopForProducts received.");constspeechText="<Product intro>"+" Would you like to know how to purchase this on Amazon?"returnhandlerInput.responseBuilder.speak(speechText).reprompt(speechText).getResponse();}};/**
* Handler for YesIntent and NoIntent.
*/constYesAndNoIntentHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='IntentRequest'&&(request.intent.name==='AMAZON.YesIntent'||request.intent.name==='AMAZON.NoIntent');},handle(handlerInput){constintentName=handlerInput.requestEnvelope.request.intent.name;console.log("User said : "+intentName);if(intentName==='AMAZON.YesIntent'){varactionText="Staging item with Amazon"letactionTask={'type':'Connections.StartConnection','uri':'connection://AMAZON.BuyShoppingProducts/1','input':{'products':[{'asin':'ASN1'}]},'token':'PurchaseProductToken'};returnhandlerInput.responseBuilder.speak(actionText).addDirective(actionTask).getResponse();}constspeechText="All right. Please come back if "+"you need more product recommendations."returnhandlerInput.responseBuilder.speak(speechText).getResponse();}};
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.
Copied to clipboard.
/**
* Handler for SessionResumedRequest.
*/constSessionResumedRequestHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='SessionResumedRequest';},handle(handlerInput){// Session attributes and ID are same as previous IntentRequestconstsessionAttributes=handlerInput.attributesManager.getSessionAttributes();console.log("sessionAttributes : "+JSON.stringify(sessionAttributes));consttoken=handlerInput.requestEnvelope.request.cause.token;letrequest=handlerInput.requestEnvelope.request;letspeechText="Sorry, I had trouble doing what you asked. Please try again.";if(request.cause){consttoken=request.cause.token;conststatus=request.cause.status;constcode=status.code;constmessage=status.message;constpayload=request.cause.result;console.info(`[Shopping Response] ${JSON.stringify(request)}`);console.info(`[INFO] Shopping Action Result: Code - ${code}, Message - ${message}, Payload - ${payload}`);switch(code){case'200':if(typeofpayload!=="undefined"){if(payload.code==="AlexaShopping.RetryLaterError"){speechText="Looks like there was an issue. Let's get back to the skill.";}elseif(payload.code==="AlexaShopping.AssociatesInvalidInputError"&&token==="PurchaseProductToken"){console.info(`[INFO] Shopping Action had an issue while performing Associates attribution. ${payload.message}`);speechText="Thank you for shopping with Alexa.";}else{speechText="I'm sorry, shopping indicated an issue while performing your request. Please try again later.";console.info(`[INFO] Shopping Action had an issue while performing the request. ${payload.message}`);}}elseif(token==="PurchaseProductToken"){console.info(`[INFO] Shopping Action: Buy action was a success for ${token}.`);speechText="Thank you for shopping with Alexa.";}break;default:console.info(`[INFO] Shopping Action: There was a problem performing the shopping action.`);speechText="I'm sorry, shopping indicated an issue while performing your request. Please try again later.";}}returnhandlerInput.responseBuilder.speak(speechText).getResponse();},};
Implement recommend-products
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.
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.
Note:Connections.StartConnection exits the current skill session. Before you send the request, save important details about the session. Also, you can save any information required to restore the session in the token parameter.
The following example shows a request to add the specified product to the list.
Copied to clipboard.
/**
* Handler for RecommendProducts intent.
*/constRecommendProductsHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='IntentRequest'&&(request.intent.name==='RecommendProducts');},handle(handlerInput){console.log("RecommendProducts received.");constspeechText="<Product intro>"+" Would you like hear more?"returnhandlerInput.responseBuilder.speak(speechText).reprompt(speechText).getResponse();}};/**
* Handler for YesIntent and NoIntent.
*/constYesAndNoIntentHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='IntentRequest'&&(request.intent.name==='AMAZON.YesIntent'||request.intent.name==='AMAZON.NoIntent');},handle(handlerInput){constintentName=handlerInput.requestEnvelope.request.intent.name;console.log("User said : "+intentName);if(intentName==='AMAZON.YesIntent'){varactionText="Transferring product recommendations to Alexa"letactionTask={'type':'Connections.StartConnection','uri':'connection://AMAZON.RecommendShoppingProducts/1','input':{'products':[{'asin':'ASN1'},{'asin':'ASN2'}]},'token':'RecommendProducts','onCompletion':'SEND_ERRORS_ONLY'};returnhandlerInput.responseBuilder.speak(actionText).addDirective(actionTask).withShouldEndSession(true).getResponse();}constspeechText="All right. Please come back if you need more product recommendations."returnhandlerInput.responseBuilder.speak(speechText).getResponse();}};
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.
*/constSystemExceptionEncounteredHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='System.ExceptionEncountered';},handle(handlerInput){console.dir(handlerInput.requestEnvelope.request);returnhandlerInput.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.
*/constRefundHandler={canHandle(handlerInput){constrequest=handlerInput.requestEnvelope.request;returnrequest.type==='IntentRequest'&&(request.intent.name==='RefundIntent');},handle(handlerInput){console.log("RefundIntent received.");returnhandlerInput.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: