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 via the Alexa app. For example, a customer can tell Alexa to add items to the Alexa Shopping List at home, and then while at the store, view the items via 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
- In-session intent request
- Out-of-session interaction
Skill Messaging API Access Token
Handle missing permissions grants
List management capabilities
Throttling restrictions
General notes about using the List API
Frequently asked questions

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.
Devise 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.

A skill developer is expected to gracefully handle the cases when customer has not granted all the requested permissions. This can be accomplished via a voice prompt and a permissions missing card. See Skill Behavior When Missing Permissions for details about the use of such a card.

In addition to the list management capabilities described in this document, a skill can also access list events and skill events. These events can be used 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 a skill is managed 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 only when they are 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. This token can be obtained with an in-session request, which is 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 form of the full request is shown below. The apiAccessToken is nested in the System object, which is nested in the context object. For more information 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": {}
        }
      },
      "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.account.[unique-value-here]",
        "accessToken": "Atza|BBBBBBB..."
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "AxThk..."
    },
    "AudioPlayer": {
      "playerActivity": "PLAYING",
      "token": "audioplayer-token",
      "offsetInMilliseconds": 0
    }
  },
  "request": {}
}

Thus:

accessToken = this.event.context.System.apiAccessToken

Important: Requests from Alexa may also include a 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.

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 and ClientSecret as inputs. To get these ClientId and ClientSecret values, refer to the Permissions page for your skill in the developer console. See the request format in 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.

See:

Skill Messaging API

Note: The access token obtained from the Skill Messaging API is not the same as the access token used for account linking.

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": [
        "read::alexa:household:list",
        "write::alexa:household:list"
      ]
    }
  }
}

The list permissions are read::alexa:household:list and write::alexa:household:list 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.

Note: If a skill displays information from Alexa lists, the skill should attribute all imported data to Alexa by including the term 'Alexa' in the list display names, or by referencing or labeling the imported items with 'Alexa'.

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 to GetListsMetadata to specify the listId 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 for links 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 to GetListsMetadata.
The itemId within a list is retrieved from a GetList 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.
A custom list can have a maximum of 1000 items (including both active and completed items) at any given time.

Endpoint: v2/householdlists/{listId}/items

The customer's listId is retrieved from a GetListsMetadata 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 400 Bad Request, if customer has reached maximum number of items.

{
   "message": "Max limit of items reached",
    "type": "MaxLimitReached"
}

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 a GetListsMetadata call.
The customer's itemId is retrieved from a GetList 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"
}

Frequently asked questions

See Creating and Managing List Skills: An FAQ.

Reference materials:

Code samples:

Integrate Skills with Alexa Lists Sample Project