Access the Alexa Shopping and To-Do Lists
Alexa customers have access to two default lists: Alexa to-do and Alexa shopping. In addition, Alexa customer can create and manage custom lists in a skill that supports that.
Customers can review and modify their Alexa lists using voice through a device with Alexa or by using the Alexa app. For example, a customer can tell Alexa to add items to the Alexa Shopping List at home, and then when at the store, view the items by using the Alexa app, and check them off.
Third-party developers can make their skills have the ability to read and modify these two Alexa lists. See the code sample and tutorial that demonstrates how to integrate list management capabilities with your skill.
- Integrate list management capabilities into your skill
- Set up permissions
- Access to Alexa lists
- Skill Messaging API Access Token
- Handle missing permissions grants
- List management capabilities
- Throttling restrictions
- General notes about using the List API
- Sample code
- Related topics
Integrate list management capabilities into your skill
This document provides a technical overview of how a custom skill can integrate with Alexa lists. If you do not already have a custom skill, you can create one following Steps to Build a Custom Skill.
To integrate these list management capabilities into your custom skill, follow these steps:
- Configure your skill in the developer console to indicate that it requires Lists Read or Lists Write permissions, or both.
- Design a user intent model that uses customer Alexa lists.
- Implement the list management capabilities in your skill service code.
A customer grants permissions to a skill through the Skills section of the Alexa app. Once a customer grants permissions, the skill will have access to the customer's Alexa lists until permissions are explicitly revoked. 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.
You must gracefully handle cases when the customer has not granted all the requested permissions. Use a voice prompt and a permissions missing card. For details about using a card, see Handle missing permissions grants.
In addition to the list management capabilities described in this document, a skill can also access list events and skill events. Use these events to enhance the skill's functionality. To use SMAPI in a skill service, the developer must manage the skill through the Alexa Skills Kit Command Line Interface (ASK CLI). Once you manage your skill through ASK CLI, the developer cannot return its management to the developer console.
Set up permissions
In order for your skill to have read or write access to customers' Alexa lists, it must have the appropriate permissions which you can set up in the developer console. Request Lists Read or Lists Write permissions in your skill when required to support the features and services provided by your skill.
- Edit your skill in the developer console.
- Navigate to the Build > Permissions page.
- Select the Lists Read or Lists Write check boxes, or both, depending on the requirements of your skill.
Access to Alexa lists
To access these list management capabilities, a 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. For example, a customer voice request or an out-of-session request.
In-session intent request
Each request sent to your skill includes an API access token (apiAccessToken
) that encapsulates the permissions granted to your skill. You need to retrieve this token value and use it in the requests related to list management.
The following example shows a full request. The apiAccessToken
is nested in the System
object, which is nested in the context
object. For more details about the parameters of such a request, see: Request Body Syntax.
{
"version": "1.0",
"session": {
"new": true,
"sessionId": "amzn1.echo-api.session.[unique-value-here]",
"application": {
"applicationId": "amzn1.ask.skill.[unique-value-here]"
},
"attributes": {
"key": "string value"
},
"user": {
"userId": "amzn1.ask.account.[unique-value-here]",
"accessToken": "Atza|AAAAAAAA...",
"permissions": {
"consentToken": "ZZZZZZZ..."
}
}
},
"context": {
"System": {
"device": {
"deviceId": "string",
"supportedInterfaces": {
"AudioPlayer": {}
},
"persistentEndpointId" : "amzn1.alexa.endpoint.[unique-value-here]"
},
"application": {
"applicationId": "amzn1.ask.skill.[unique-value-here]"
},
"user": {
"userId": "amzn1.ask.account.[unique-value-here]",
"accessToken": "Atza|AAAAAAAA...",
"permissions": {
"consentToken": "ZZZZZZZ..."
}
},
"person": {
"personId": "amzn1.ask.person.[unique-value-here]",
"accessToken": "Atza|BBBBBBB..."
},
"unit": {
"unitId": "amzn1.ask.unit.[unique-value-here]",
"persistentUnitId" : "amzn1.alexa.unit.did.[unique-value-here]"
},
"apiEndpoint": "https://api.amazonalexa.com",
"apiAccessToken": "AxThk..."
},
"AudioPlayer": {
"playerActivity": "PLAYING",
"token": "audioplayer-token",
"offsetInMilliseconds": 0
}
},
"request": {}
}
Thus:
accessToken = this.event.context.System.apiAccessToken
consentToken
within session.user.permissions
and context.System.user.permissions
. This property is deprecated. Existing skills that use consentToken
continue to work, but the context.System.apiAccessToken
property should be used instead. For details, see Handling Requests Sent by Alexa.
Out-of-session interaction
Your app can request an out-of-session access token when it needs to access the customer Alexa lists outside of the customer's voice request, following these steps:
-
Obtain the Skill Messaging API access token, using the
ClientId
andClientSecret
as inputs. To get theseClientId
andClientSecret
values, refer to the Permissions page for your skill in the developer console. For details about the request format, see Configure an Application or Service to Send Messages to Your Skill. If your skill has been managed through SMAPI, you can still see these values in the developer console. Go to the list of skills. Those skills that have the appropriate permissions will show the link View Skill ID and Client Secret. When you click this link, the Skill ID, Client ID, and Client Secret appear in a popup. -
Once the access token is obtained, the app makes an asynchronous call to the Skill Messaging API using the Skill Messaging API access token and the
userId
value, which was obtained during an earlier customer voice interaction. The Skill Messaging API calls the skill back with the customer consent token.

Skill Messaging API Access Token
The third-party application requires authorization to send messages to the skill. This authorization is obtained with the following API via an HTTPS request, as described.
Request Format
This section documents the format for the request.
HTTP Header
POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Parameter | Description | Example |
---|---|---|
Content-Type |
The content type of the resource. Must be application/x-www-form-urlencoded |
Content-Type: application/x-www-form-urlencoded |
Request Body Syntax
grant_type=client_credentials&client_id=(clientID)&client_secret=(clientSecret)&scope=alexa:skill_messaging
Request Body Parameters
Parameter | Description | Example |
---|---|---|
grant_type |
Value must be client_credentials |
grant_type=client_credentials |
client_id |
The ClientId value |
client_id=amzn1.iba-client... |
client_secret |
The ClientSecret value |
client_secret=... |
scope |
Value must be alexa:skill_messaging |
scope=alexa:skill_messaging |
Sample cURL Request
curl -k -X POST -H
'Content-Type: application/x-www-form-urlencoded' -d
'grant_type=client_credentials&client_id=xxxx&client_secret=yyyy&scope=alexa:skill_messaging'
https://api.amazon.com/auth/o2/token
Response Format
If your request is not successful, you will receive a non-200 error status code. In the case of a non-200 code, the response message may contain the following parameter in the body of the JSONObject:
reason: <<The reason the request was not accepted>>
A successful response format is as follows.
HTTP Header
X-Amzn-RequestId: d917ceac-2245-11e2-a270-0bc161cb589d
Content-Type: application/json
Response Body Syntax
{
"access_token": "Atc|MQEWYJxEnP3I1ND03ZzbY_NxQkA7Kn7Aioev_OfMRcyVQ4NxGzJMEaKJ8f0lSOiV-yW270o6fnkI",
"expires_in": 3600,
"scope": "alexa:skill_messaging",
"token_type": "Bearer"
}
Request Body Parameters
Parameter | Description | Example |
---|---|---|
access_token |
An access token that must be used for all requests | "access_token":"Atc|MQEWYJxEnP3I1ND03Zz..." |
expires_in |
The duration in seconds of the access token lifetime. For example, 3600 denotes that the access token expires in one hour from the time the response was generated. | "expires_in":3600 |
scope |
Value will be alexa:skill_messaging |
"scope":"alexa:skill_messaging" |
token_type |
Only Bearer tokens are supported | "token_type":"Bearer" |
Errors
Status Code | Type | Description |
---|---|---|
400 | INVALID_REQUEST | Reasons for this response include: - The content type is not supported by the authorization server. In other words, it is not application/x-www-form-urlencoded .- The request is missing a required parameter: grant-type , scope , client_id , client_secret .- The request is otherwise malformed. |
400 | UNAUTHORIZED_CLIENT | The client is not authorized for the requested operation. |
400 | UNSUPPORTED_GRANT_TYPE | The grant type is not supported by the authorization server. In other words, it is not client_credentials . |
400 | INVALID_SCOPE | The requested scope is invalid, which means it is not alexa:skill_messaging . |
401 | INVALID_CLIENT | The client authentication failed. |
500 | SERVER_ERROR | There was an internal server error. The requester may retry the request. |
503 | SERVICE_UNAVAILABLE | The server is temporarily unavailable. The requester must retry later honoring the Retry-After header included in the response. See the HTTP/1.1 specification, section 14.37, for possible formats for the Retry-After value. |
Handle missing permissions grants
When a skill requires Lists Read or Lists Write access, and the customer has not granted access, the skill developer must gracefully handle this use case in the skill service code. As a best practice, the skill must display a permissions card in the Alexa app, and the skill should provide a voice prompt that explains to the customer to look in the Alexa app in order to grant the required access.
Here is a sample card format that a skill can issue, in this example 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.
List management capabilities
These list management capabilities provide create, read, update, and delete (CRUD) operations for your skill. This API exposes information about customer Alexa lists, and it supports list traversal. Each list item exposed through the API has properties such as value and itemId.
Skills that call this API should be resilient when API responses contain new fields. All API parameters are strings unless otherwise specified. Each itemId
is unique in a list.
Throttling restrictions
Requests are throttled at 25 TPS per skill. Thus, a skill can make a maximum of 25 requests per second to the List API at /v2/householdlists. Any requests beyond that limit will receive an HTTP 400 error code, with the message "Rate exceeded". The request can then be retried.
General notes about using the List API
- Any reference to the customer default lists refers to Alexa ToDo and Shopping Lists.
- Each of the APIs shown in this document are applicable to both default lists and custom lists.
- Because the text in the error response messages is subject to change, developers should rely on the error code, and not the text of the error message, to manage skill responses to errors.
- An HTTP 500 InternalError allows the skill to retry the request.
- Archived lists are read-only lists. An item from an archived list can only be read, but not deleted or modified.
- If a custom list is deleted, the skill will get a list deleted event, but will not get individual item deleted events for items in the deleted list.
List management quick reference
List Management Domain: https://api.amazonalexa.com/
Append the endpoint to this domain.
API | Method | URI Endpoint |
---|---|---|
Get lists metadata | GET | v2/householdlists/ |
Get a list | GET | v2/householdlists/{listId}/{status} |
Get a list item | GET | v2/householdlists/{listId}/items/{itemId} |
Update a list item | PUT | v2/householdlists/{listId}/items/{itemId} |
Create a new list item | POST | v2/householdlists/{listId}/items |
Delete a list item | DELETE | v2/householdlists/{listId}/items/{itemId} |
Create a custom list | POST | v2/householdlists/ |
Update a custom list's `name` or `status` | PUT | v2/householdlists/{listId} |
Delete a custom list | DELETE | v2/householdlists/{listId} |
HTTP methods for list management
In the following APIs, {listId}
refers to the customer's listId
and {itemId}
refers to the itemId
for the specified list item.
The default Alexa lists, ToDo and Shopping, always appear ahead of the custom lists in the API response. The Alexa ToDo List and the Alexa Shopping List cannot be archived or deleted.
In case of an error, the app should use the error code to respond. The text in the message is subject to change and should not be relied upon.
GetListsMetadata
Retrieves the metadata for all customer lists, including the customer's default lists. The following apply to the response:
- Default lists will always appear ahead of any custom lists in the API response.
- The version of the default lists will always be 1, and the state for default lists will always be active.
Endpoint: v2/householdlists/
Request format
GET v2/householdlists/
Authorization: Bearer auth_token_for_customer
Content-Type: json
Response format
HTTP 200 OK, on success.
{
"lists": [
// Default Shopping List details
{
"listId": "shopping_list_list_id",
"name": "Alexa shopping list",
"state": "active",
"version": 1,
"statusMap": [
{
"href": "url", // URL to get active list items in the list.
"status": "active"
},
{
"href": "url", // URL to get completed list items in list.
"status": "completed"
}
]
},
// Default ToDo List details
{
"listId": "todo_list_list_id",
"name": "Alexa to-do list",
"state": "active",
"version": 1,
"statusMap": [
{
"href": "url",
"status": "active"
},
{
"href": "url",
"status": "completed"
}
]
},
// Custom List Details.
{
"listId": "ff097d45-c098-44af-a2e9-7dae032b270b", // List id, String
"name": "test-list-name-veba", // List name, String
"state": "active", // List state, Enum
"version": 7,
"statusMap": [
{
"href": "url", // URL to get active list items in the list.
"status": "active"
},
{
"href": "url", // URL to get completed list items in list.
"status": "completed"
}
]
},
...
]
}
HTTP 403 Forbidden, if the customer authorization token is not valid, or has expired.
{
"Message": "Request is not authorized."
}
HTTP 500 Internal Server Error, if Alexa has encountered a server error.
{
"message": "",
"type": "InternalError"
}
GetList
The GetList
API retrieves the list metadata including the items in the list with requested status. Construct the endpoint as follows:
- Use the
listId
retrieved from a call toGetListsMetadata
to specify thelistId
in the request path. - Specify the
status
variable in the query path, which may have a value of "active" or "completed". to specify either "active" or "completed" items.
The response to a GetList
call includes a relative URL to retrieve the next page of list items, if it exists. GetList
exposes the Alexa-imposed list item order. An external app can choose to present Alexa list items in whatever order is desired.
Endpoint: v2/householdlists/{listId}/{status}
The listId
is the value of the customer's listId
. The status
is either "active" or "completed".
Request format
GET v2/householdlists/{listId}/{status}
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
Response format
HTTP 200 OK, on success.
{
"listId": , // list id (String)
"name": , // list name (String)
"state": , // "active" or "archived" (Enum)
"version":, // list version (string)
"items":
[
{
"id": , // item id (String, limit 256 characters)
"version": , // item version (Positive integer)
"value": , // item value (String, limit 256 characters)
"status": , // item status (Enum: "active" or "completed")
"createdTime": , // created time in format Wed Jul 19 23:24:10 UTC 2017
"updatedTime": , // updated time in format Wed Jul 19 23:24:10 UTC 2017
"href": // URL to retrieve the item (String)
},
...
],
"links": {
"next": "v2/householdlists/{listId}/{status}?nextToken={nextToken}"
}
}
The following apply to a successful response:
- Default page size for list items is 100 and cannot be controlled by the client.
- If the
next
property forlinks
is empty or null, then the request has reached the end of the list. - The list items are returned in reverse chronological order based on the item creation time.
- Custom ordering of list items is not possible at this time.
HTTP 400 Bad Request, if input is malformed.
{
"message": "Invalid input.",
"type": "InvalidInput"
}
HTTP 403 Forbidden, if the list is not owned by the customer.
{
"message": "Given List id is not owned by customer.",
"type": "Unauthorized"
}
HTTP 404 Not Found, if the list is not found.
{
"message": "List id does not exist.",
"type": "ObjectNotFound"
}
HTTP 500 Internal Server Error, if Alexa has encountered a server error.
{
"message": "Internal failure.",
"type": "InternalError"
}
CreateList
This API creates a custom list. The new list name must be different than any existing list name.
- The list name provided will be trimmed at both ends and this string is used to check if the list already exists.
- The list name is case-sensitive, that is the list name is persisted as it is without converting to lower case.
- The list name check is case-insensitive.
- This API does not allow the creation of archived lists. It always creates an active list regardless of the state passed.
- The list name check is against active lists only. This API allows creation of an active list when an archived list with the same name exists.
- One customer can have only 100 active lists at any time including default lists.
Endpoint: v2/householdlists/
Request format
POST v2/householdlists/
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
{
"name": "my Amazon list", // List name, String, 256 chars
"state": "active" // List state, Enum, "active" ONLY.
}
Response format
HTTP 201 OK, on success
{
"listId": "09d9d7df-05be-438c-veba-9d32968b4509", // List id, String
"name": "my Amazon list", // List name, String
"state": "active", // List state, Enum
"version": 1, // Version, Long
"statusMap": [
{
"href": "url", // URL to get active list items in the list.
"status": "active"
},
{
"href": "url", // URL to get completed list items in the list.
"status": "completed"
}
]
}
HTTP 400 Bad Request, if the input is invalid such as if the list name is too long, or the list name is blank.
{
"message": "Invalid input.",
"type": "InvalidInput"
}
HTTP 400 Bad Request, if the customer has the reached maximum number of lists.
{
"message": "Max limit of lists reached",
"type": "MaxLimitReached"
}
HTTP 403 Forbidden, if a customer authorization token is not valid or has expired
{
"message": "Request is unauthorized",
"type": "Unauthorized"
}
HTTP 409 Conflict, if a list with the same name already exists
{
"message": "List name already exists.",
"type": "NameConflict"
}
HTTP 500 Internal Server Error, if Alexa encountered a server error
{
"message": "Internal failure.",
"type": "InternalError"
}
UpdateList
This API updates a custom list. Only the list name
or state
can be updated. An Alexa customer can turn an archived list into an active one.
- To update the list name of an active list.
- To archive an active list.
- To restore an archived list to an active list.
Endpoint: v2/householdlists/{listId}
The listId
is the value of the customer's listId
retrieved from a GetListsMetadata
call.
Request format
PUT v2/householdlists/{listId} // where {listId} is the customer's list id
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
{
"name": // New list name (String, limit is 256 characters),
"state" : // List state, "active" or "archived" (Enum),
"version" : // List version when retrieved (long)
}
Response format
HTTP 200 OK, on success.
{
"listId": "09d9d7df-05be-438c-veba-9d32968b4509", // List id, String
"name": "my new list name", // List name, String
"state": "active", // List state, Enum
"version": 8, // Updated version, Long
"statusMap": [
{
"href": "url", // URL to get active list items in the list.
"status": "active"
},
{
"href": "url", // URL to get completed list items in the list.
"status": "completed"
}
],
}
HTTP 400 Bad Request, if the input is invalid such as if the list name is blank or too long.
{
"message": "Invalid input.",
"type": "InvalidInput"
}
HTTP 400 Bad Request, if customer has reached the maximum number of lists.
{
"message": "Max limit of lists reached",
"type": " MaxLimitReached"
}
HTTP 403 Forbidden, if an attempt is made to update, rather than revive, an archived list.
{
"message": "Updates to archived lists are not allowed except reviving the list.",
"type": "ImmutableDataModification"
}
HTTP 403 Forbidden, if a customer authorization token is not valid or has expired.
{
"Message": "Request is not authorized."
}
HTTP 403 Forbidden, if the list is not owned by the customer.
{
"message": "Given List id is not owned by customer.",
"type": "Unauthorized"
}
HTTP 404 ListNotFound, if listId
is not found.
{
"message": "List id does not exist.",
"type": "ObjectNotFound"
}
HTTP 409 Conflict, if the list with the same name exists.
{
"message": "List name already exists.",
"type": "NameConflict"
}
HTTP 409 Conflict, if the given list version does not match the latest list version.
{
"message": "Invalid list version.",
"type": "VersionConflict"
}
HTTP 500 Internal Server Error, if Alexa has encountered a server error.
{
"message": "Internal failure.",
"type": "InternalError"
}
DeleteList
This API deletes a customer custom list.
- A non-empty list can be deleted.
- An archived list can be deleted.
- Customer's default list cannot be deleted.
- Deleting default lists will result in an unauthorized exception.
- Deleting an already deleted list will result in a "List not found" exception.
Endpoint: v2/householdlists/{listId}
Request format
DELETE: v2/householdlists/{listId} //where {listId} is the customer's list id
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
Response format
HTTP 200 OK, on success.
HTTP 403 Forbidden, if a customer authorization token is not valid or has expired.
{
"message": "Request is unauthorized.",
"type": "Unauthorized"
}
HTTP 403 Forbidden, if trying to delete a default Alexa list.
{
"message": "Alexa ToDo or Shopping lists cannot be deleted.",
"type": "Unauthorized"
}
HTTP 403 Forbidden, if the list is not owned by the customer.
{
"message": "Given List id is not owned by customer.",
"type": "Unauthorized"
}
HTTP 404 Not Found, if the list is not found from the given listId
.
{
"message": "List id does not exist.",
"type": "ObjectNotFound"
}
HTTP 500 Internal Server Error, if Alexa has encountered a server error.
{
"message": // error message (String),
"type": "InternalError"
}
GetListItem
This API can be used to retrieve single item with in any list by listId
and itemId
.
This API can read list items from an archived list.
Attempting to read list items from a deleted list throws an ObjectNotFound
exception.
Endpoint: v2/householdlists/{listId}/items/{itemId}
- The
listId
is retrieved from a call toGetListsMetadata
. - The
itemId
within a list is retrieved from aGetList
call.
Request format
GET v2/householdlists/{listId}/items/{itemId}
where {listId} is customer's list id and {itemId} is the item id
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
Response format
HTTP 200 OK, on success.
{
"id": // item id (String, limit 60 characters)
"version": // item version (Positive integer)
"value": // item value (String, limit 256 characters)
"status": // item status (Enum: "active" or "completed")
"createdTime": // created time (Wed Sep 27 10:46:30 UTC 2017)
"updatedTime": // updated time (Wed Sep 27 10:46:30 UTC 2017)
"href": // URL to retrieve the item (String)
}
HTTP 403 Forbidden, if a customer authorization token is not valid, or has expired.
{
"message": "Request is not authorized.",
"type": "Unauthorized"
}
HTTP 403 Forbidden, if the given listId
is not owned by the customer.
{
"message": "List id does not belong to given customer.",
"type": "Unauthorized"
}
HTTP 404 Not Found, if the list is not found with the given listId
.
{
"message":"List id or Item id does not exist.",
"type": "ObjectNotFound"
}
HTTP 500 Internal Server Error, if Alexa has encountered a server error.
{
"message": "Internal failure.",
"type": "InternalError"
}
CreateListItem
This API creates an item in an active list or in a default list. The following restrictions apply to this API:
- The item value cannot be blank. For example, the item value cannot contain only spaces.
- The item name is not trimmed, and the case is persisted as it is. Thus, two list items may look like they have the same name when they do not.
- No items can be added to an archived list.
Endpoint: v2/householdlists/{listId}/items
- The customer's
listId
is retrieved from aGetListsMetadata
call.
Request format
POST v2/householdlists/{listId}/items
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
{
"value": "my item", //item value, with a string description up to 256 characters
"status": "completed" // item status (Enum: "active" or "completed")
}
Response format
HTTP 201 OK, on success
Location: v2/householdlists/{listid}/items/{itemId}
{
"id": // item id (String, limit 60 characters),
"version": // item version (Positive integer),
"value": // item value (String, limit is 256 characters),
"status": // item status (Enum: "active" or "completed"),
"createdTime": // created time (ISO 8601 time format with time zone),
"updatedTime": // updated time (ISO 8601 time format with time zone)
"href": // URL to retrieve the item (String)
}
HTTP 403 Forbidden, if a customer authorization token is not valid, or has expired.
{
"Message": "Request is not authorized."
}
HTTP 403 Forbidden, if the given listId1
is not owned by the customer.
{
"message": "Given List id is not owned by customer.",
"type": "Unauthorized"
}
HTTP 403 Forbidden, if an attempt is made to add an item to an archived list.
{
"Message": "Creation of items in archived list is not allowed.",
"type": "ImmutableDataModification"
}
HTTP 404 Not Found, if the list is not found.
{
"message": "list is not found",
"type": "ObjectNotFound"
}
HTTP 500 Internal Server Error, if Alexa has encountered a server error.
{
"message": "Internal failure",
"type": "InternalError"
}
UpdateListItem
This API is used to update an item value or item status.
The following conditions apply to this API:
- The item value cannot be blank. For example, the item value cannot contain only spaces.
- The item name is not trimmed, and the case is persisted as it is. Thus, two list items may look like they have the same name when they do not.
- No items can be added to an archived list.
- Any false update is ignored, such as if an item value or status is updated without any change to it.
Endpoint: v2/householdlists/{listId}/items/{itemId}
The listId
is the customer's list id, and itemId
is the item id to be updated in that list.
Request format
PUT v2/householdlists/{listId}/items/{itemId}
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
{
"value": "my item", // new item value (String, 256 chars)
"status": "completed", // item status (Enum: "active" or "completed")
"version": 7 // item version when it was read (Positive integer)
}
Response format
HTTP 200 OK, on success.
{
"id": // item id (String, limit 60 characters)
"version": // item version (Positive integer)
"value": // item value (String, limit 256 characters)
"status": // item status (Enum: "active" or "completed")
"createdTime": // created time (Wed Sep 27 10:46:30 UTC 2017)
"updatedTime": // updated time (Wed Sep 27 10:46:30 UTC 2017)
"href": // URL to retrieve the item (String)
}
HTTP 400 Bad Request, if input is invalid such as item value long, blank item value.
{
"message": "Must specify a valid version to update a list item.", // etc.
"type": "InvalidInput"
}
HTTP 403 Forbidden, if a customer authorization token is not valid, or has expired.
{
"Message": "Request is not authorized."
}
HTTP 403 Forbidden, if an item is being added to an archived list.
{
"Message": "Updating of items in archived list is not allowed.",
"type": "ImmutableDataModification"
}
HTTP 403 Forbidden, if the list is not owned by the customer.
{
"message": "Given List id is not owned by customer.",
"type": "Unauthorized"
}
HTTP 404 Not Found, if the listId
or the itemId
does not exist.
{
"message": "List id or Item id does not exist.",
"type": "ObjectNotFound"
}
HTTP 409 Conflict, if the given item version does not match the latest item version in Alexa.
{
"message": "Invalid item version.",
"type": "VersionConflict"
}
HTTP 500 Internal Server Error, if Alexa has encountered a server error.
{
"message": "Internal failure.",
"type": "InternalError"
}
DeleteListItem
This API deletes an item in the specified list.
- The customer's
listId
is retrieved from aGetListsMetadata
call. - The customer's
itemId
is retrieved from aGetList
call.
The following conditions apply to this API.
- List items in an archived list cannot be deleted.
- This API is not idempotent. Attempting to delete an already deleted list item will result in an Object not found exception.
- If the list item is updated in the course of deletion, an internal error may result, and the request may be retried.
Endpoint: v2/householdlists/{listId}/items/{itemId}
Request format
DELETE: v2/householdlists/{listId}/items/{itemId}
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
Response format
HTTP 200 OK, on success.
HTTP 403 Forbidden, if a customer authorization token is not valid or has expired.
{
"Message": "Request is not authorized."
}
HTTP 403 Forbidden, if item is being deleted from an archived list.
{
"Message": "Deletion of items in archived list is not allowed.",
"type": "ImmutableDataModification"
}
HTTP 403 Forbidden, if the list is not owned by the customer.
{
"message": "Given List id is not owned by customer.",
"type": "Unauthorized"
}
HTTP 404 Not Found, if the list or list item is not found.
{
"message": "List id or Item id does not exist.",
"type": "ObjectNotFound"
}
HTTP 500 Internal Server Error, if Alexa encountered a server error
{
"message": "Internal failure.",
"type": "InternalError"
}
Sample code
For sample code about how to incorporate lists in your skill, see Alexa List Access Demo.