> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wishlists

> Read a store's customer wishlists from an installed app: list saved-product lists and re-fetch the wishlist a wishlist webhook pointed at. Requires READ_WISHLIST.

## 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

```http theme={null}
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

```bash theme={null}
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.

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "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

> [card] [Webhooks](https://docs.salesive.com/apps-api/webhooks.md)
>
> The wishlist topics and the per-topic payload additions.

> [card] [Carts](https://docs.salesive.com/apps-api/carts.md)
>
> Read the cart a shopper is building right now.

> [card] [Products](https://docs.salesive.com/apps-api/endpoint/products/list-products.md)
>
> Resolve a saved product id to its current catalog values.

> [card] [Money and units](https://docs.salesive.com/apps-api/introduction.md#money-and-units)
>
> How product prices and every other amount is expressed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.