Wishlists - Salesive Docs

What an app can read

The wishlist API is a read-only view of the products customers have saved in a store. Use it to show a merchant what shoppers are saving, to power a back-in-stock or price-drop alert, or to re-fetch the wishlist a wishlist webhook pointed at. Wishlist writes are shopper actions on the storefront, so there are no create, update or delete routes here. An app reads a wishlist; it never edits one.

Authentication and scope

Authorization: Bearer app_<your-app-access-token>

The store comes from the installation bound to your token, never from a header or query parameter. Both routes require the READ_WISHLIST scope. A call without it is refused with 403 naming the missing scope. READ_WISHLIST is its own scope, separate from READ_CUSTOMERS. It grants the saved products and the populated shopper identity (name, email, avatar) shown below.

Endpoints

All paths are under https://api.salesive.com/api/v1.

Method	Path	What it does
`GET`	`/wishlist`	List the store’s customer wishlists, most recently updated first
`GET`	`/wishlist/:id`	Read one wishlist by its id

List wishlists

curl "https://api.salesive.com/api/v1/wishlist?limit=20" \
  -H "Authorization: Bearer app_<your-app-access-token>"

Query	Default	Notes
`page`	`1`	Whole number, 1 or more.
`limit`	`20`	Whole number from 1 to 100. Values outside the range are clamped.

There is one wishlist per customer per store, so the list has at most one row per shopper. Rows are ordered by updatedAt, newest first.

{
  "status": 200,
  "success": true,
  "message": "Wishlists retrieved successfully",
  "data": {
    "wishlists": [
      {
        "_id": "66d3b2c4d5e6f7a8b9c0d1e2",
        "user": {
          "_id": "66b1f0a3c2d4e5f6a7b8c9d0",
          "name": "Amara Okonkwo",
          "email": "amara@example.com",
          "avatar": "https://cdn.salesive.com/avatars/amara.png"
        },
        "shop": "6680aabbccddeeff00112200",
        "items": [
          {
            "product": {
              "_id": "66d3b2c4d5e6f7a8b9c0d1e3",
              "name": "Jollof rice",
              "price": 3500,
              "images": ["https://cdn.salesive.com/products/jollof.png"]
            },
            "variant": "66d3b2c4d5e6f7a8b9c0d1e4",
            "addedAt": "2026-11-07T18:10:00.000Z"
          }
        ],
        "createdAt": "2026-11-07T18:10:00.000Z",
        "updatedAt": "2026-11-08T09:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}

Wishlist fields

Field	Type	Description
`_id`	string	The wishlist id. This is the `resourceId` a wishlist webhook carries.
`user`	object or `null`	The shopper, populated as `{ _id, name, email, avatar }`, or `null` if the shopper record no longer exists.
`shop`	string	The store id.
`items`	array	The saved products.
`createdAt`	string	When the wishlist was created.
`updatedAt`	string	When a product was last added or removed.

Item fields

Field	Type	Description
`product`	object	The saved product as `{ _id, name, price, images }`.
`variant`	string	The saved variant id, when the shopper saved a specific variant.
`addedAt`	string	When the product was added to the wishlist.

Items have no id of their own. Address a saved product by its product._id (and variant when present). A populated product is null if the product has since been deleted.

Get one wishlist

curl "https://api.salesive.com/api/v1/wishlist/66d3b2c4d5e6f7a8b9c0d1e2" \
  -H "Authorization: Bearer app_<your-app-access-token>"

data is the same wishlist object shown above, not a list:

{
  "status": 200,
  "success": true,
  "message": "Wishlist retrieved successfully",
  "data": {
    "_id": "66d3b2c4d5e6f7a8b9c0d1e2",
    "user": {
      "_id": "66b1f0a3c2d4e5f6a7b8c9d0",
      "name": "Amara Okonkwo",
      "email": "amara@example.com",
      "avatar": "https://cdn.salesive.com/avatars/amara.png"
    },
    "shop": "6680aabbccddeeff00112200",
    "items": [
      {
        "product": {
          "_id": "66d3b2c4d5e6f7a8b9c0d1e3",
          "name": "Jollof rice",
          "price": 3500,
          "images": ["https://cdn.salesive.com/products/jollof.png"]
        },
        "variant": "66d3b2c4d5e6f7a8b9c0d1e4",
        "addedAt": "2026-11-07T18:10:00.000Z"
      }
    ],
    "createdAt": "2026-11-07T18:10:00.000Z",
    "updatedAt": "2026-11-08T09:30:00.000Z"
  }
}

The lookup is scoped to your store, so a wishlist id from another store returns 404.

When to call it

After a wishlist webhook. wishlists/item_added and wishlists/item_removed carry the wishlist id as resourceId, not the product id. Call GET /wishlist/:id to read the current saved products. The event is notify-only and carries no items, and the same id is used for both add and remove, so one re-fetch works for either.
To watch saved products. List the store’s wishlists and compare each one with the current catalog to spot a product that is about to go out of stock or has dropped in price.
To show a merchant demand. Count how often a product appears across the store’s wishlists.

Errors

Status	Meaning
`400`	The id is not a valid record id, so it cannot be looked up.
`401`	The token is missing, expired or revoked, or the app is no longer installed on the store.
`403`	The app does not hold `READ_WISHLIST`. The message names the missing scope.
`404`	No wishlist with that id exists in this store.

Next steps

Webhooks

The wishlist topics and the per-topic payload additions.

Carts

Read the cart a shopper is building right now.

Products

Resolve a saved product id to its current catalog values.

Money and units

How product prices and every other amount is expressed.

​What an app can read

​Authentication and scope

​Endpoints

​List wishlists

​Wishlist fields

​Item fields

​Get one wishlist

​When to call it

​Errors

​Next steps