Multi-Wishlist

Multi-wishlist lets customers create named lists like “Birthday Gifts” or “Home Renovation” to organize their saved products. Available on Growth and Scale plans.

Merchants must also enable multi-wishlist from the Settings page in the dashboard.

Limits

Limit	Value
Max wishlists per customer	20
Max total items across all lists	2,500
Max list name length	100 characters

When multi-wishlist is enabled, every customer automatically has a default list. All existing items are associated with this default list.

List all wishlists

GET /v1/wishlists/{customerId}/lists

Response

{
  "ok": true,
  "data": {
    "wishlists": [
      {
        "wishlistId": "default",
        "name": "My Wishlist",
        "itemCount": 5,
        "createdAt": "2026-01-15T10:30:00.000Z",
        "updatedAt": "2026-01-16T14:22:00.000Z"
      },
      {
        "wishlistId": "abc123def456",
        "name": "Birthday Gifts",
        "itemCount": 3,
        "createdAt": "2026-02-01T09:00:00.000Z",
        "updatedAt": "2026-02-10T11:15:00.000Z"
      }
    ]
  }
}

Create a wishlist

POST /v1/wishlists/{customerId}/lists

Request body

{
  "name": "Birthday Gifts"
}

Field	Required	Description
name	Yes	List name (1-100 characters)

Response

{
  "ok": true,
  "data": {
    "wishlist": {
      "wishlistId": "abc123def456",
      "name": "Birthday Gifts",
      "itemCount": 0,
      "createdAt": "2026-02-01T09:00:00.000Z",
      "updatedAt": "2026-02-01T09:00:00.000Z"
    }
  }
}

Returns 400 with error WISHLIST_LIMIT if the customer already has 20 wishlists.

Rename a wishlist

PUT /v1/wishlists/{customerId}/lists/{listId}

Request body

{
  "name": "Holiday Gifts"
}

Response

{
  "ok": true,
  "data": {
    "updated": true
  }
}

The default list can be renamed.

Delete a wishlist

DELETE /v1/wishlists/{customerId}/lists/{listId}

Deletes the list and all its items. The default wishlist cannot be deleted.

Response

{
  "ok": true,
  "data": {
    "deleted": true
  }
}

Move an item between lists

POST /v1/wishlists/{customerId}/items/move

Request body

{
  "product_id": "8012345678",
  "from": "default",
  "to": "abc123def456"
}

Field	Required	Description
product_id	Yes	Product ID to move
from	Yes	Source wishlist ID
to	Yes	Destination wishlist ID

Response

{
  "ok": true,
  "data": {
    "moved": true
  }
}

Returns 400 if the item is not found in the source list or if from and to are the same.

Using a specific list with existing endpoints

When multi-wishlist is enabled, you can pass a wishlist_id query parameter to any existing wishlist endpoint to target a specific list:

# Get items from a specific list
GET /v1/wishlists/{customerId}?wishlist_id=abc123def456

# Add an item to a specific list
POST /v1/wishlists/{customerId}/items?wishlist_id=abc123def456

# Remove an item from a specific list
DELETE /v1/wishlists/{customerId}/items/{productId}?wishlist_id=abc123def456

# Share a specific list
GET /v1/wishlists/{customerId}/share?wishlist_id=abc123def456

When wishlist_id is omitted, operations target the default list.