Creating and Managing List Skills FAQ

This list of Frequently Asked Questions describes various aspects of creating and managing list skills.

Q: Can a skill use both account linking and these list management capabilities?

Yes. This feature allows the skill developer to reference customer Alexa lists in their external apps. To set up account linking, see Understand Account Linking.

Q: Can an Alexa customer grant access to Alexa to-do and shopping lists to more than one skill?


Q: Can a customer delete their Alexa list?

A customer cannot delete a default Alexa list, although a customer can delete all the items on an Alexa list. A customer can delete a custom list, if all of the items have been deleted first.

Q: Can a customer grant access to a single Alexa list?

No, a customer cannot limit the lists they share with a skill. However, a skill may choose to interact only with those lists that are of interest.

Q: Do these list management capabilities support custom list metadata?


Q: Can Alexa customers share their lists with other customers within Amazon?

Yes, if the other customers are within the same Amazon household. For a discussion of Amazon Household, see Household Profiles on Alexa Devices.

Q. How can you view a list skill created using the Skill Management API (SMAPI) in the developer console?

List skills must be created using SMAPI, and are viewable and editable only through SMAPI. You cannot view or edit list skills on the developer console.

Q. When is an event generated by a customer action?

Any customer with a list skill enabled causes a list event to be generated whenever the customer adds, modifies, or deletes an item from their lists. A skill event is generated whenever a customer enables or disables the skill, links or unlinks a third-party account with the skill, grants permissions to a skill, or changes the permissions grant to the skill.

Q. Are IDs such as userId, listId, and listItemId persistent after the customer generates a skill event?

The userId value changes whenever a customer disables and then re-enables the skill. Account linking or unlinking does not change the userId value. The listId and listItemId values are unchanged when a skill is disabled and re-enabled.

Q. How should the developer handle localization of the To-Do and Shopping lists?

The default lists (To-Do and Shopping List) listId values are base-64 encoded strings with these formats:

  • <Internal_identifier>-TASK for the to-do list
  • <Internal_identifier>-SHOPPING_ITEM for the shopping list

You can base64 decode the listId value and look for the specified string at the end. This string is constant and agnostic to localization.

Q. Can a customer grant just one of list read or list write permissions?

A customer may decide to grant one or both of list read and list write permissions.

Q. Are List APIs idempotent? Can a deleted item be deleted again?

After an item is deleted, it is no longer in the system and subsequent calls to delete the item will result in the system throwing an "Object not found" exception. Similarly, multiple calls to create an item will create multiple items, even if each call is identical.

Q. What timeouts are enforced on the Event calls? In particular, on initial linking, a first "sync" might be quite large and slow.

The timeout period is 30 seconds for AWS Lambda skill services, by default. This value can be changed in the skill service settings. The timeout is 10 seconds for HTTPS endpoints.

Q. What is the server retry logic for list events and skill events?

The system retries with an exponentially increasing delay, starting at 30 seconds and doubling each time the endpoint fails to receive the message. The maximum period of time for which these retries occur is one hour. The maximum delay between retries is 30 minutes. For messages sent through the Skill Messaging API, the maximum retry time is set using the expiresAfterSeconds field, and can be set to be up to 24 hours (86400 seconds).

Q. Does the datetime format differ for List API calls and for list events?

List events use the ISO8061 datetime format. The List API returns datetimes in this format: "Sat Jul 22 10:41:04 UTC 2017"

Q. Can a customer change regions and thus require a different API endpoint for calling the List APIs?

Yes, a customer can change the region, but you can continue using the same endpoint for calling List APIs. The system will internally route the requests as per the customer's preferred market place. When a customer changes the preferred market place, the data controlled by the skill will not be migrated automatically.

Q. Are list item moves represented as a delete list item and create list item event? Is the listItemId maintained?

When a customer moves an item across lists using the Alexa app, two events are generated for the operation. These events are ItemsDeleted on the source list, and an ItemsCreated event on the destination list. The listItemId value is maintained.

Q. Can a developer determine that an event has been triggered due to their skill?

Consider this scenario:

  • The customer creates a to-do in the app.
  • The skill service uses the Skill Messaging API to send a message to the skill to create a list item in Alexa.
  • The skill receives the Skill Messaging API message and POSTs to householdlist and list items.

In response to the POST, the skill service records the listItemId locally. An ItemsCreate event also occurs as a list item was just created. Alexa triggers an event even if a list item is created by calling List API. Skill developers can use the listItemId value returned by CreateListItem to uniquely identify an item.

Q. What are some sample calls to get an out-of-session consent token to call List APIs?

To obtain an out-of-session Skill Messaging API token:

POST /auth/o2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache


    "access_token": "Atc|XXXXXXXXXXXXXXXXXUSyLA",
    "scope": "alexa:skill_messaging",
    "token_type": "bearer",
    "expires_in": 3600

To POST a message to the Skill Messaging API:

POST /v1/skillmessages/users/amzn1.ask.account.XXXXXXXXXXXXXX HTTP/1.1
Authorization: Bearer Atc|XXXXXXXXXX
Content-Type: application/json
Cache-Control: no-cache
Postman-Token: 98b62082-ff25-a7de-f33b-95d9424beb22
{"data":{"notificationTitle":"NewMessagefromBackend","spokenOutput":"Hi,This is the message sent from Backend."},"expiresAfterSeconds":60}
Response: 202 Accepted
Q. Is a client id unique to a skill?

The ClientId and ClientSecret are unique to a skill, means there is a one-to-one mapping between a ClientId value and a skill. Similarly, there is a one-to-one mapping between an actual customer and the userId for a skill. If a customer has multiple Alexa skills enabled, the customer has a separate and unique userId value for each of these skills.

For example, suppose a customer has two skills: ABCSkill and XYSSkill with ClientId_ABC and ClientId_XYS.

When the customer has enabled ABCSkill and XYSSkill, each has a separate userId, such as AlexaUserId_ABC for ABCSkill and AlexaUserId_XYS for XYZSkill, and these are not the same.

If you call the Skill Messaging API with (ClientId_ABC and ClientSecret_ABC and AlexaUserId_ABC), you will get the correct response, and the same applies for ClientId_XYZ, ClientSecret_XYZ and AlexaUserId_XYZ.

Q. How should the skill service verify the authenticity of events received by skill endpoints?

See Alexa Skills Kit Security Testing. Do not depend solely on the access token to validate the incoming request. All third-party skills must validate the request signature to ensure that the request was sent by Alexa. Otherwise the skill cannot pass certification to go live.