Access the Alexa Shopping and To-Do Lists

Alexa customers have access to two default lists: Alexa Shopping list and Alexa To-Do list. Customers can also create and manage custom lists. Customers can review and modify their Alexa lists with voice or the Alexa app. For example, a customer can ask Alexa to add items to the Alexa Shopping List at home, and then, at the store, view and update the items in the Alexa app. Similarly, you might implement an app, along with your custom skill, to access the Alexa lists. You can use out-of-session messaging from your app to your skill to keep these lists in sync.

You can access the Alexa Shopping and Alexa To-Do list lists in your custom skill. And, you can create and manage custom lists. For details about list management see, List Skills.

Complete the following steps to build access the Alexa Shopping and To-Do lists and custom lists.

Prerequisites

To access Alexa, you need a custom skill. For details about how to create a custom skill, see Steps to Build a Custom Skill. Also, design a custom voice interaction intent model that uses Alexa lists.

Steps to add list management capabilities

Complete the following steps to add list management capabilities to your custom skill:

  1. Configure permissions to access Alexa lists.
  2. Handling missing permissions.
  3. Get access to Alexa lists.
  4. Implement list management capabilities

Step 1: Configure permissions to access Alexa lists

Use the Alexa developer console to set the appropriate permissions to access the customer's Alexa lists. To support the features of your skill, request Lists Read or Lists Write permissions, or both.

Set up permission for list access in the developer console

  1. Sign in to the Alexa developer console.
  2. From the skill list, locate your custom skill, and then, in the dropdown under ACTIONS, select Edit.
  3. In the left pane, click TOOLS, and then click Permissions.
  4. To enable read permission, toggle Lists Read.
  5. To enable writer permission, toggle Lists Write.

Step 2: Handle missing permissions

To access the customer's Alexa lists, the customer must grants permissions to a skill in the Skills section of the Alexa app. Your skill has access until the customer revokes permissions. At any time, the customer can change the allowed access for that skill in Manage Settings on the skill's page in the Alexa app.

If the customer hasn't granted your skill access to their Alexa lists, you must handle this case gracefully. As a best practice, provide a voice prompt and display a permissions card in the Alexa app that explains to the customer to grant the required access in the Alexa app.

The following example code shows a card format for write permissions to a customer's Alexa lists.

{
  "version": "1.0",
  "response": {
    "card": {
      "type": "AskForPermissionsConsent",
      "permissions": [
        "alexa::household:lists:read",
        "alexa::household:lists:write"
      ]
    }
  }
}

The list permissions are alexa::household:lists:read and alexa::household:lists:write for read and write respectively.

Step 3: Get access to Alexa lists

To access Alexa lists, your skill requires an access token that indicates that the customer has granted the skill permission to access the customer's Alexa lists. Obtain this token with an in-session request, such as a customer voice request. To access Alexa lists outside of a skill session, your app or website needs a user-specific access token. Obtain this token by using reciprocal authorization.

In-session access tokens

Each request sent to your skill includes an API access token that encapsulates the permissions granted to your skill by the user. You can find the access token in the context.System.apiAccessToken parameter. For more details about the parameter, see Request Body Syntax. Use this token value in the List Management REST API.

Out-of-session access tokens

Your app can request an out-of-session access token when it needs to update customer lists outside of a skill session. For example, the customer might add milk to their Shopping List with voice, and then, at the store update the list in your app.

To call the List Management API outside of a skill session, your skill must store and refresh user-specific Alexa access tokens asynchronously. After the customer authorizes your skill to access Alexa lists, Alexa provides an authorization code to your skill. You exchange the authorization code and client credentials for an access token by using the OAuth 2.0 code grant flow. For detailed steps, see Get a User-Specific Access Token for Out-of-Session Calls to Alexa. Make sure that you store the authorization code so that you can get another access token after the token expires.

Step 4: Implement list management capabilities

Use the List Management REST APIs to create, read, update, delete, and traverse custom and default Alexa lists. Archived lists are read-only lists. You can read, but not update or delete, items from an archived list. Use the access token that you obtained in Step 3 in the REST Authorization header.

In addition to the List Management REST APIs, your skill can access list events and skill events. Use these events to enhance the skill's functionality.

Throttling restrictions

List API requests must not exceed 25 TPS per skill. Any requests beyond that limit receive HTTP 429 Too Many Requests error code. You can retry the request by using exponential back-off.

Sample code

For sample code about how to incorporate lists in your skill, see Alexa List Access Demo.

Last updated: Mar 14, 2023