Wishlist API

Shoppers can save products to a wishlist without creating an account. The storefront keeps the wishlist on the server and remembers it with a cookie, so the same wishlist follows the shopper between visits. A shopper with an optional storefront account keeps their wishlist in the account instead, so it follows them to other devices, and logging in merges what they saved as a guest into it. A wishlist link only works once the shopper chooses to share it; until then it stays private to the shopper. A shared link lets anyone see the wishlist, but only its owner can change it.

A customer who opted in to marketing email is emailed, at most once a day, when variants on their account wishlist go on sale. A guest’s cookie-only wishlist is anonymous and never triggers one. See Wishlist Sale Alerts.

These read-only endpoints report which products shoppers have saved. Creating a wishlist, saving a product, and sharing a link are storefront actions and are not part of the API.

Related resources:

• Products for the product fields returned below
• Sites for wishlist sale alerts

Endpoints

• List Wishlisted Products - GET /api/v1/products/wishlisted/
• Get Product Wishlist - GET /api/v1/products/{product_id}/wishlist/

Only counts are exposed. A wishlist may belong to a customer’s account, but the API never returns a wishlist ID, its owner, or any other shopper identity. A merged guest wishlist is deleted, so a shopper’s saves count once.

List Wishlisted Products

List the products that have been saved to at least one wishlist, ranked by how many wishlists saved them and then by the most recently created product. Products with no saves are omitted.

Endpoint: GET /api/v1/products/wishlisted/

Scope Required: products:read

Query Parameters

Pagination follows the same cursor rules as the product list: after is the id of the last item from the previous page, before is the id of the first item to page back, and the response reports has_more in the direction of travel. An after ID that no longer has any saves yields an empty page.

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/wishlisted/?search=t-shirt&limit=20" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "pro_d0b6fmv28q6vn14peun0",
      "name": "Blue T-Shirt",
      "status": "active",
      "description": "A soft cotton tee.",
      "delivery": "physical",
      "created_at": "2026-09-01T12:00:00Z",
      "updated_at": "2026-09-20T09:30:00Z",
      "taken_down_at": null,
      "wishlist_count": 8
    }
  ],
  "has_more": false
}

Only products saved to at least one wishlist are returned, so wishlist_count is always 1 or greater in this list. Use Get Product Wishlist to check a product that may have no saves.

Error Responses

Invalid query parameter

Status: 400 Bad Request

A malformed after or before, both at once, a non-numeric or negative limit, or a limit over 100 returns INVALID_REQUEST_ERROR, with the offending parameter named in the error message:

{
  "error": "Invalid 'limit' parameter: cannot exceed 100",
  "code": "INVALID_REQUEST_ERROR"
}

Failed to list wishlisted products

Status: 500 Internal Server Error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Get Product Wishlist

Report how many wishlists saved one product.

Endpoint: GET /api/v1/products/{product_id}/wishlist/

Scope Required: products:read

Path Parameters

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/wishlist/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": {
    "product_id": "pro_d0b6fmv28q6vn14peun0",
    "wishlist_count": 3
  }
}

wishlist_count is 0 when no wishlist has saved the product.

Error Responses

Product not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Failed to get wishlist

Status: 500 Internal Server Error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Wishlisted Product Object

A wishlisted product is the standard Product object with one extra field:

Each wishlist counts once no matter how many of the product’s variants are in it, so a shopper who saves the same product from two variant pages still counts as one.