> ## Documentation Index > Fetch the complete documentation index at: https://docs.publica.la/llms.txt > Use this file to discover all available pages before exploring further. # 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](./lists-v3-list.md) and takes products through [Manage List Items](./lists-v3-items.md). All three endpoints require an administrator token. See the [Lists API Overview](./lists-v3-overview.md) for authentication, the target user parameters and [how a list is addressed](./lists-v3-overview.md#addressing-a-list). :::info Custom lists only The favorites list cannot be created, renamed or deleted: it is created on first use by [adding a product to it](./lists-v3-items.md#favorites). The shopping cart and the save-for-later list are not reachable through this API. ::: ## List name rules {#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 {#create} 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](#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 ```json { "user_external_id": "student-1042", "name": "Summer reading" } ``` ### Response **Success (201):** The new list, in the same shape [List Lists](./lists-v3-list.md) returns. Keep its `id`: custom lists are addressed by `id` only. ```json { "data": { "id": "3c81a570-52f7-4a0e-8a0e-6b2d9f4c1177", "name": "Summer reading", "type": "custom", "private": true, "role": "owner" } } ``` ### Examples #### Create a list ```bash 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 ```bash 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": "student@example.com", "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: ```json { "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 {#rename} 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](./lists-v3-overview.md#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](#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 ```json { "user_external_id": "student-1042", "name": "Summer reading 2026" } ``` ### Response **Success (200):** The renamed list, in the same shape [List Lists](./lists-v3-list.md) returns. `role` is the target user's role on the list. ```json { "data": { "id": "3c81a570-52f7-4a0e-8a0e-6b2d9f4c1177", "name": "Summer reading 2026", "type": "custom", "private": true, "role": "owner" } } ``` ### Examples #### Rename a list ```bash 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 ```bash 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": "student@example.com", "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 {#delete} 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](./lists-v3-overview.md#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 ```bash 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 ```bash 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](./lists-v3-overview.md) - [List Lists](./lists-v3-list.md) - [Manage List Items](./lists-v3-items.md)