List Lists
Read every list the store shows a given user, or find one of them by id or name.
The endpoint requires an administrator token. See the Lists API Overview for authentication and the target user parameters.
List a user's lists
Returns the favorites list plus every named list of the target user, private lists included. The shopping cart and the save-for-later collection are never returned.
Endpoint
GET /api/v3/lists
Headers
| Header | Required | Description |
|---|---|---|
X-User-Token | Yes | API token of a store administrator |
Accept | No | application/json |
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
user_external_id | string | - | Your identifier for the user. Required unless user_email is sent |
user_email | string | - | Email of the user. Required unless user_external_id is sent |
filter[type] | string | - | Only lists of this type: favorites or custom |
filter[id] | string | - | Only the list with this id |
filter[name] | string | - | Only lists with exactly this name, case as stored |
per_page | integer | 100 | Lists per page, between 1 and 500 |
cursor | string | - | Cursor token, taken from links.next |
Exactly one of user_external_id and user_email must be sent.
See List types for the two values.
There is no single-list endpoint. To read one list, filter the index: filter[type]=favorites for the favorites list, filter[id] for any list whose id you already hold, filter[name] for a custom list by its exact name. A filter that matches nothing returns an empty data array, never 404; that includes ids of lists that belong to another user or to the hidden storefront collections.
Response
Success (200):
{
"data": [
{
"id": "9f2d4b1e-6c3a-4f58-9b77-1d0a2e5c8b34",
"name": "favorites",
"type": "favorites",
"private": false,
"role": "owner"
},
{
"id": "3c81a570-52f7-4a0e-8a0e-6b2d9f4c1177",
"name": "my picks",
"type": "custom",
"private": true,
"role": "owner"
}
],
"links": {
"next": null,
"prev": null
},
"meta": {
"has_more": false
}
}
A user with no lists at all returns an empty data array with meta.has_more set to false.
Examples
The favorites list of a user
curl -X GET "https://yourstore.publica.la/api/v3/lists?user_external_id=student-1042&filter[type]=favorites" \
-H "X-User-Token: your-api-token" \
-H "Accept: application/json"
Identify the user by email
curl -X GET "https://yourstore.publica.la/api/v3/[email protected]&filter[type]=favorites" \
-H "X-User-Token: your-api-token" \
-H "Accept: application/json"
Every list of a user
curl -X GET "https://yourstore.publica.la/api/v3/lists?user_external_id=student-1042" \
-H "X-User-Token: your-api-token" \
-H "Accept: application/json"
A custom list by its exact name
curl -X GET "https://yourstore.publica.la/api/v3/lists?user_external_id=student-1042&filter[name]=Summer%20reading" \
-H "X-User-Token: your-api-token" \
-H "Accept: application/json"
A list by id
curl -X GET "https://yourstore.publica.la/api/v3/lists?user_external_id=student-1042&filter[id]=9f2d4b1e-6c3a-4f58-9b77-1d0a2e5c8b34" \
-H "X-User-Token: your-api-token" \
-H "Accept: application/json"
Next page
curl -X GET "https://yourstore.publica.la/api/v3/lists?user_external_id=student-1042&per_page=100&cursor=eyJsaXN0cy5pZCI6MTQ..." \
-H "X-User-Token: your-api-token" \
-H "Accept: application/json"
Errors
| Status | Message | Cause |
|---|---|---|
401 | Unauthenticated. | Missing or invalid X-User-Token |
403 | This store cannot access the integrations API. | The store does not have the integrations API enabled |
403 | This token cannot operate on other users' lists. | The token does not belong to a store administrator |
404 | The specified user does not exist in this store. | No user matches the identifier sent |
422 | First validation error | Neither or both user identifiers, an unknown filter[type], a filter[id] that is not a uuid, or per_page outside 1 to 500 |
429 | Too Many Requests | Rate limit or daily read quota exceeded |