Alexa Skills Kit    >    Shopping and To Do Lists

Integrate Your Skills with Alexa Lists

Customers on tens of millions of Alexa-enabled devices are increasingly using voice interfaces as a hands-free way to manage their lives, and keep track of items to buy and things to do. Alexa provides a set of built-in list capabilities that customers use to manage their Shopping and To-do lists. In addition, customers can create their own lists for any purpose or occasion.

Now, you can make it easier for customers to keep track of their tasks, shopping needs and other important items through your Alexa skill. With Lists Read and Lists Write permissions, you can create new lists, read, add, and delete items to any Alexa list from within your skill. For example, if you had a drink recipe skill, customers could ask Alexa to send the ingredients for their chosen drink to the Alexa Shopping list, or to any other list of their choice—all without leaving your skill.

How It Works

The List Skill API comprises of Lists ReadLists Write permissions and Lists EventsLists Read permissions allows read-only access to any of the customer’s Alexa lists so that your skill can read list items on command. Lists Write permissions enable customers to add and remove items from their Alexa lists using your skill or create new lists. Lists Events, available for list skills, allows you to receive notifications when customers add or remove items to their lists on Alexa. This enables you to understand and react to changes that happen to lists from top-level utterances on Alexa (for example: “Alexa, add bananas to my shopping list”) without building a voice interaction model to handle customer requests. You can use Lists Events to enable two-way sync between Alexa Lists and an external web/mobile interface, to ensure lists are updated across all channels.

Lists Read, Write permissions and Lists Events are available worldwide for developers building skills in US English, UK English, and German languages.

Getting Started

If you have an existing Alexa custom skill, or are building a new custom skill, you can easily integrate with Alexa lists by following these steps:

  1. Configure your skill in the Amazon Developer Portal to indicate that it requires Lists Read or Lists Write permissions, or both.
  2. Devise a user intent model that uses customer's Alexa lists.
  3. Implement the Lists Read or Lists Write permissions.


To subscribe to Lists Events:

  1. Use SMAPI to create a new list skill or to update your existing Custom skill to subscribe to Lists Events.
  2. Request Lists Read and Lists Write permissions and use the APIs to read and update Alexa lists.
  3. Implement handlers to respond to Lists Events.
  4. Implement account linking to associate customers who enabled your skill with their identity within your app.
  5. Add an intent model to your skill if you would like to extend it beyond syncing lists. Custom interaction model is not required for List Skills that consume list events.

Once a customer grants permissions, your skill can access the customer’s Alexa shopping and to do lists. You can use the Lists Read and Lists Write permissions as part of a response to a voice interaction (in-session), or in an out-of-session flow, initiated by your skill. When you add permissions to your skill, you’ll want to save the state of the customer’s previous session to ensure the customer experience is consistent when they reopen your skill and want to access or change the list. You may also want to link your system’s account to Alexa to ensure your customer has a consistent experience across devices. You can find best practices on account linking and preserving state in your Alexa skill in our technical documentation.


  1. How do I add List capabilities to my custom skill? 
    Developers can select the list capabilities they need as part of the custom skill creation flow in the developer portal. Lists Read/Write permissions will be available in the Skill Configuration section, under Permissions. Learn more about adding list permissions to your skill
    Event capabilities will initially be exposed to developers through SMAPI (Skill Management API). Developers who create a list skill to subscribe to List Events will have to supply a Lambda/HTTPS endpoint for receiving the events. 

  2. Why do I need to use the List Events? 
    List Events are most useful for applications that want to provide an external web/mobile interface for customers to manage their Alexa lists and support two-way sync. This allows the applications to receive events when customers add or remove items from their lists so they can refresh the app. 

  3. Do I have to choose an invocation name and define a voice model if I only use my skill to provide a mobile/web interface for managing lists? 
    List Events available for list skills gives you access to top level voice intents which do not require an invocation name or voice model. You would still be required to add sample top level utterances that will be used in your skill details page. If you decide to add custom intents to your skill you would have to supply an invocation name and voice model so customers can access your skill. 

  4. How will customers discover and enable my skill? 
    Customers will discover your skill by browsing or searching the Alexa Skills Store. We highly encourage you to advertise the skill by deep linking to the skill’s detail page from your website/mobile app. Upon enablement of the skill, customers would have to allow the skill to read or manage their Alexa lists based on the list permissions your skill is using. 

  5. Do you support account linking for custom and list skills? 
    Yes. List management applications will typically require the ability to connect the identity of an Alexa end customer with a customer in the list management app. To accomplish that, developers should use a process called account linking, which provides a secure way for Alexa skills to connect with third-party systems requiring authentication. 

  6. What are the certification requirements for skills that are using the List API capabilities?
     The certification process is the same for all custom Alexa skills. Learn more about certification requirements for list skills.