List Management FAQ
The following frequently asked questions (FAQ) answer common questions about list management.
- Q: Can a customer grant access to a single Alexa list?
No, a customer can't limit the lists that they share with a skill. However, a skill might choose to interact only with those lists that are of interest.
- 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 details about Amazon households, see Household Profiles on Alexa Devices.
- Q. Can a customer grant just one of list read or list write permissions?
A customer can grant one or both of the list read and list write permissions.
- Q: Can an Alexa customer grant access to the Alexa Shopping and To-Do lists to more than one skill?
- Q. Are IDs such as
listItemIdpersistent after the customer generates a skill event?
userIdvalue can change when a customer disables, and then re-enables the skill. Account linking or unlinking doesn't change the
listItemIdvalues are persistent and don't change when a skill is disabled and re-enabled.
- Q. How should the developer handle localization of the Alexa Shopping and To-Do lists?
On the default lists, such as the Alexa Shopping and To-Do lists,
listIdvalues are base-64 encoded strings with these formats:
<Internal_identifier>-TASKfor the to-do list
<Internal_identifier>-SHOPPING_ITEMfor the shopping list
You can base64 decode the
listIdvalue and look for the specific string at the end. This string is constant and agnostic to localization.
- Q: Do the list management capabilities support custom list metadata?
You can access custom list metadata with the Get lists metadata REST API.
- Q: Can a customer delete their Alexa list?
A customer can't delete a default Alexa list, although a customer can delete all the items on the default Alexa Shopping and To-Do lists. A customer can delete a custom list, if all the items on the list are deleted first.
- Q. Are List Management APIs idempotent? Can a deleted item be deleted again?
After an item is deleted, that item is no longer in the system and subsequent calls to delete the item result in an "Object not found" exception. Similarly, multiple calls to create an item creates multiple items, even if each call is identical.
- Q. Can a customer change regions and thus require a different API endpoint for calling the List APIs?
Yes, a customer can change regions, but you can continue to use the same endpoint for List Management REST APIs. The system internally routes the requests per the customer's preferred marketplace. When a customer changes their preferred marketplace, the data controlled by the skill isn't migrated automatically.
- Q. Does the
datetimeformat differ for List API calls and for list events?
The List Management REST API returns ISO8061
datetimeformat. List events use
datetimesin UTC format:
Sat Jul 22 10:41:04 UTC 2017.
- Q. What are some sample calls to get an out-of-session access token to call List Management APIs?
For details about the message format and code examples to obtain an out-of-session access token to access List Management APIs directly, see Get a User-Specific Access Token for Out-of-Session Calls to Alexa.
- Q: Can a skill use both account linking and list management capabilities?
Yes. This feature allows you to reference customer Alexa lists in your external apps. To set up account linking, see Understand Account Linking.
- 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 can't view or edit list skills on the Alexa developer console.
- Q. When is an event generated by a customer action?
A list event is generated when the customer adds, modifies, or deletes an item from their lists. A skill event is generated when the 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 list item moves represented as a delete list item and create list item event? Is the
When a customer moves an item across lists using the Alexa app, two events are generated for the operation. These events are
ItemsDeletedon the source list, and an
ItemsCreatedevent on the destination list. The
listItemIdvalue is maintained.
- 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's 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
expiresAfterSecondsfield, and can be set to be up to 24 hours (86400 seconds).
- 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 app 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 the
householdlistresource and list items.
In response to the POST, the skill service records the
ItemsCreateevent also occurs as a list item was just created. Alexa triggers an event even if a list item is created by calling the List Management REST API. Skill developers can use the
listItemIdvalue returned by
CreateListItemto uniquely identify an item.
- Q. What are some sample calls to get an out-of-session access token to call Skill Messaging APIs?
For details about the message format and code examples to obtain an out-of-session access token, see Request Format to Obtain Access Token.
- Q. Is a client id unique to a skill?
ClientSecretare unique to a skill, means there is a one-to-one mapping between a
ClientIdvalue and a skill. Similarly, there is a one-to-one mapping between an actual customer and the
userIdfor a skill. If a customer has multiple Alexa skills enabled, the customer has a separate and unique
userIdvalue for each of these skills.
For example, suppose a customer has two skills:
When the customer has enabled ABCSkill and XYSSkill, each has a separate
userId, such as
If you call the Skill Messaging API with
AlexaUserId_AB, you get the correct response, and the same applies for
- Q. How should the skill service verify the authenticity of events received by skill endpoints?
Don't depend solely on the access token to validate the incoming request. All third-party skills must validate the request signature to make sure that the request was sent by Alexa. Otherwise the skill can't pass certification to go live. For details, see Alexa Skills Kit Security Testing.
Last updated: Oct 14, 2022