Search Documentation

Search for a documentation page...

Wishlist API

REST API endpoint for reading aggregated wishlist analytics.

Aggregated view of what shoppers have saved. Read-only — wishlist entries are created by shoppers on the storefront. Useful as a demand signal: what to restock, what to discount, what to feature.

Scope: customers:read (the top-shoppers breakdown includes customer PII).

Get Wishlist Analytics

GET /api/v1/wishlist

Query Parameters

ParameterTypeDefaultDescription
startDatestring—Only count saves at or after this instant (ISO 8601)
endDatestring—Only count saves at or before this instant (ISO 8601)
limitnumber10How many top products and top shoppers to return (1-100)
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/wishlist

Response

{
  "summary": {
    "totalFavorites": 142,
    "uniqueProducts": 38,
    "uniqueUsers": 67
  },
  "topProducts": [
    {
      "productId": "0191abc0-0000-7000-8000-000000000100",
      "name": "Classic Tee",
      "slug": "classic-tee",
      "image": "https://cdn.example.com/classic-tee.jpg",
      "favorites": 24,
      "lastFavoritedAt": "2025-08-10T14:30:00.000Z"
    }
  ],
  "topShoppers": [
    {
      "userId": "0191abc0-9999-7def-8000-000000000001",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "favorites": 12,
      "lastFavoritedAt": "2025-08-10T15:00:00.000Z"
    }
  ]
}

Response Fields

FieldTypeDescription
summary.totalFavoritesnumberTotal saves across all products
summary.uniqueProductsnumberDistinct products saved
summary.uniqueUsersnumberDistinct shoppers who saved something
topProducts[].slugstringProduct slug accepted by the catalog endpoints
topShoppers[].emailstringShopper email (requires customers:read scope)
PreviousSocialsAPI ReferenceNextAnalyticsAPI Reference