Manage Lists

Create, rename and delete the custom lists of any user of your store. A list created here is one of the user's lists from then on: it appears in List Lists and takes products through Manage List Items.

All three endpoints require an administrator token. See the Lists API Overview for authentication, the target user parameters and how a list is addressed.

Custom lists only

The favorites list cannot be created, renamed or deleted: it is created on first use by adding a product to it. The shopping cart and the save-for-later list are not reachable through this API.

List name rules

Creating and renaming validate name the same way:

• It is required, and must be between 3 and 255 characters long.
• Leading and trailing spaces are removed before the name is checked and stored.
• It must not match any list the target user already has, lists shared with them included. The comparison ignores case, so Summer Reads and summer reads are the same name.
• It must not be one of the reserved names favorites, shopping-cart or buy-later, in any case.

---

Create a list

Creates a custom list for the target user.

Endpoint

POST /api/v3/lists

Headers

Header	Required	Description
X-User-Token	Yes	API token of a store administrator
Content-Type	Yes	application/json
Accept	No	application/json

Body parameters

Parameter	Type	Required	Description
user_external_id	string	Conditional	Your identifier for the user. Required unless user_email is sent
user_email	string	Conditional	Email of the user. Required unless user_external_id is sent
name	string	Yes	Name of the new list. See List name rules

Exactly one of user_external_id and user_email must be sent.

The list is always created private, with the target user as its owner. There is no parameter to create a public list.

Request example

{
  "user_external_id": "student-1042",
  "name": "Summer reading"
}

Response

Success (201):

The new list, in the same shape List Lists returns. Keep its id: custom lists are addressed by id only.

{
  "data": {
    "id": "3c81a570-52f7-4a0e-8a0e-6b2d9f4c1177",
    "name": "Summer reading",
    "type": "custom",
    "private": true,
    "role": "owner"
  }
}

Examples

Create a list

curl -X POST "https://yourstore.publica.la/api/v3/lists" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"user_external_id": "student-1042", "name": "Summer reading"}'

Identify the user by email

curl -X POST "https://yourstore.publica.la/api/v3/lists" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"user_email": "[email protected]", "name": "Summer reading"}'

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	The list name must be between 3 and 255 characters.	name is shorter than 3 or longer than 255 characters
422	This user already has a list with that name.	The user already has a list with that name, ignoring case, or name is a reserved name
422	First validation error	Neither or both user identifiers, or no name (The name field is required.)
429	Too Many Requests	Rate limit exceeded

An invalid name returns:

{
  "message": "The list name must be between 3 and 255 characters.",
  "errors": {
    "name": ["The list name must be between 3 and 255 characters."]
  }
}

When two calls create the same name for the same user at the same time, both can pass validation. Usually the second one then returns 422 with This user already has a list with that name. in errors.name, the same shape as above. If both calls pass the check before either one creates the list, both succeed and the user ends up with two lists with the same name.

---

Rename a list

Changes the name of one of the target user's lists. The name belongs to the list, so every user who shares it sees the new name.

Endpoint

PUT /api/v3/lists/{list}

Path parameters

Parameter	Type	Description
list	string	The id of one of the user's custom lists. See Addressing a list

Headers

Header	Required	Description
X-User-Token	Yes	API token of a store administrator
Content-Type	Yes	application/json
Accept	No	application/json

Body parameters

Parameter	Type	Required	Description
user_external_id	string	Conditional	Your identifier for the user. Required unless user_email is sent
user_email	string	Conditional	Email of the user. Required unless user_external_id is sent
name	string	Yes	New name of the list. See List name rules

Exactly one of user_external_id and user_email must be sent.

The target user must be the owner or an editor of the list. A viewer cannot rename it.

The list's current name does not count as taken: sending the same name again, or the same name with different case, renames the list without a 422.

The name is validated before the permission checks run, so an invalid name returns 422 even on a call that would otherwise be refused with 403.

Request example

{
  "user_external_id": "student-1042",
  "name": "Summer reading 2026"
}

Response

Success (200):

The renamed list, in the same shape List Lists returns. role is the target user's role on the list.

{
  "data": {
    "id": "3c81a570-52f7-4a0e-8a0e-6b2d9f4c1177",
    "name": "Summer reading 2026",
    "type": "custom",
    "private": true,
    "role": "owner"
  }
}

Examples

Rename a list

curl -X PUT "https://yourstore.publica.la/api/v3/lists/3c81a570-52f7-4a0e-8a0e-6b2d9f4c1177" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"user_external_id": "student-1042", "name": "Summer reading 2026"}'

Identify the user by email

curl -X PUT "https://yourstore.publica.la/api/v3/lists/3c81a570-52f7-4a0e-8a0e-6b2d9f4c1177" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"user_email": "[email protected]", "name": "Summer reading 2026"}'

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
403	Favorites cannot be renamed or deleted.	{list} is the favorites list, addressed by the favorites slug or by its id
403	Only the list owner or an editor can rename it.	The target user is a viewer of the list
404	The specified user does not exist in this store.	No user matches the identifier sent
404	Not found	{list} is not a list of the target user (another user's list among them), an unknown slug, or a reserved storefront collection (cart, save for later)
422	The list name must be between 3 and 255 characters.	name is shorter than 3 or longer than 255 characters
422	This user already has a list with that name.	Another list of the user already has that name, ignoring case, or name is a reserved name
422	First validation error	Neither or both user identifiers, or no name (The name field is required.)
429	Too Many Requests	Rate limit exceeded

---

Delete a list

Deletes one of the target user's lists.

Endpoint

DELETE /api/v3/lists/{list}

Path parameters

Parameter	Type	Description
list	string	The id of one of the user's custom lists. See Addressing a list

Query parameters

Parameter	Type	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

Exactly one of user_external_id and user_email must be sent.

Only the owner of the list can delete it. Deleting removes the list for everyone: the products it held and every collaborator's access to it go with it. The products themselves stay in your store, and the user's other lists, favorites included, are not touched.

Response

Success (204):

No body.

Examples

Delete a list

curl -X DELETE "https://yourstore.publica.la/api/v3/lists/3c81a570-52f7-4a0e-8a0e-6b2d9f4c1177?user_external_id=student-1042" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"

Identify the user by email

curl -X DELETE "https://yourstore.publica.la/api/v3/lists/3c81a570-52f7-4a0e-8a0e-6b2d9f4c1177?user_email=student%40example.com" \
  -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
403	Favorites cannot be renamed or deleted.	{list} is the favorites list, addressed by the favorites slug or by its id
403	Only the list owner can delete it.	The target user is an editor or a viewer of the list
404	The specified user does not exist in this store.	No user matches the identifier sent
404	Not found	{list} is not a list of the target user (another user's list among them), an unknown slug, or a reserved storefront collection (cart, save for later)
422	First validation error	Neither or both user identifiers
429	Too Many Requests	Rate limit exceeded

---

See also

• Lists API Overview
• List Lists
• Manage List Items