JavaScript SDK - Fetch Wishlist Picks

swat.fetchWishlistPicks

Fetches the shopper's full Wishlist Picks dataset: one merchant-ranked list plus three plain sort views, in a single call.

Wishlist Picks returns a shopper's saved items pre-sorted four ways, so you can build whatever surface fits your store without writing your own ranking logic. The headline view, prioritized-items, tags each item with why it's showing: a price drop, low stock, back in stock, or saved-for-later, and tops itself up with popular items so it's never empty. The other three views are plain sorts of the shopper's actual wishlist: newest first, cheapest first, priciest first.

It's one shared fetch server-side, not four separate calls, so a caller switching between chips (e.g. "Don't Miss Out" vs "Recently Added") needs no extra round trip.

📘

This call returns four arrays, not one

prioritized-items is the ranked, reason-tagged list. recently-added, price-low-to-high, and price-high-to-low are simple sorts of the shopper's actual wishlist, with no ranking or fallback applied. Build your UI around all four keys, not just prioritized-items.

🚧

Not self-serve

Wishlist Picks is off for every store by default until Swym turns it on. There is no setting in your dashboard for this yet, contact Swym Support to have it enabled for your store before building against this API.

Definition

swat.fetchWishlistPicks(options, onSuccess, onError)

regid/sessionid are attached automatically from the shopper's session, no need to pass them yourself.

Example

Here's an example of how you can use this API to fetch a shopper's Wishlist Picks:

// define the options
let options = {
  itemCount: 4
};

// Define success callback
let onSuccess = function(data) {
  renderPrioritizedItems(data['prioritized-items']);
  renderChip('recently-added', data['recently-added']);
  renderChip('price-low-to-high', data['price-low-to-high']);
  renderChip('price-high-to-low', data['price-high-to-low']);
}

// Define error callback
let onError = function(status, xhr) {
  console.log('fetchWishlistPicks failed', status);
}

// Call `fetchWishlistPicks` with the above callbacks and options
swat.fetchWishlistPicks(options, onSuccess, onError);

API Parameters

Success Response

Each array is capped at itemCount independently. Every item (in any of the four arrays) has this shape, ItemWithReason (only in prioritized-items) adds reason, the three sort views add saved-at instead:

Example Response

A shopper with two saved items, requested with itemCount: 2:

{
  "prioritized-items": [
    {
      "epi": 41283910218, "empi": 41283910000,
      "title": "Ridgeline Trail Jacket",
      "iu": "https://cdn.example.com/files/ridgeline-jacket.jpg",
      "pr": 89.00,
      "uri": "https://merchant-store.com/products/ridgeline-trail-jacket?variant=41283910218",
      "reason": "price-drop"
    },
    {
      "epi": 41283910900, "empi": 41283910700,
      "title": "Ceramic Pour-Over Set",
      "iu": "https://cdn.example.com/files/pour-over-set.jpg",
      "pr": 38.00,
      "uri": "https://merchant-store.com/products/ceramic-pour-over-set?variant=41283910900",
      "reason": "popular"
    }
  ],
  "recently-added": [
    {
      "epi": 41283910900, "empi": 41283910700,
      "title": "Ceramic Pour-Over Set",
      "iu": "https://cdn.example.com/files/pour-over-set.jpg",
      "pr": 38.00,
      "uri": "https://merchant-store.com/products/ceramic-pour-over-set?variant=41283910900",
      "saved-at": 1789922984142
    },
    {
      "epi": 41283910218, "empi": 41283910000,
      "title": "Ridgeline Trail Jacket",
      "iu": "https://cdn.example.com/files/ridgeline-jacket.jpg",
      "pr": 89.00,
      "uri": "https://merchant-store.com/products/ridgeline-trail-jacket?variant=41283910218",
      "saved-at": 1789731110250
    }
  ],
  "price-low-to-high": [
    { "epi": 41283910900, "empi": 41283910700, "title": "Ceramic Pour-Over Set", "iu": "https://cdn.example.com/files/pour-over-set.jpg", "pr": 38.00, "uri": "https://merchant-store.com/products/ceramic-pour-over-set?variant=41283910900", "saved-at": 1789922984142 },
    { "epi": 41283910218, "empi": 41283910000, "title": "Ridgeline Trail Jacket", "iu": "https://cdn.example.com/files/ridgeline-jacket.jpg", "pr": 89.00, "uri": "https://merchant-store.com/products/ridgeline-trail-jacket?variant=41283910218", "saved-at": 1789731110250 }
  ],
  "price-high-to-low": [
    { "epi": 41283910218, "empi": 41283910000, "title": "Ridgeline Trail Jacket", "iu": "https://cdn.example.com/files/ridgeline-jacket.jpg", "pr": 89.00, "uri": "https://merchant-store.com/products/ridgeline-trail-jacket?variant=41283910218", "saved-at": 1789731110250 },
    { "epi": 41283910900, "empi": 41283910700, "title": "Ceramic Pour-Over Set", "iu": "https://cdn.example.com/files/pour-over-set.jpg", "pr": 38.00, "uri": "https://merchant-store.com/products/ceramic-pour-over-set?variant=41283910900", "saved-at": 1789922984142 }
  ]
}

A store with nothing wishlisted yet, or one that hasn't been enabled (see the Not self-serve callout above), returns the same four keys, all empty:

{ "prioritized-items": [], "recently-added": [], "price-low-to-high": [], "price-high-to-low": [] }

Reason types

Only present on items in the prioritized-items array, checked in the merchant's configured priority order (or options.reasonOrder if you override it):

• low-stock: Current stock is at or below the merchant's low-stock threshold.
• price-drop: Price has dropped since the shopper saved it.
• back-in-stock: Was out of stock (or at/below threshold) when saved, currently back above threshold.
• sfl: Saved via the merchant's Save for Later flow rather than the standard wishlist.
• popular: Fallback only, used to fill remaining slots when nothing else qualifies. Not a real "reason" the shopper's item has, just a way to avoid showing an empty widget.

📘

Timing

low-stock reflects inventory data that can be up to 5 minutes stale. back-in-stock reflects a threshold lookup that can be up to 60 minutes stale. If a merchant changes a threshold or a product's stock just changed, allow for that delay before treating a missing/wrong badge as a bug.

📘

Cold start on back-in-stock

This reason depends on the stock level captured at the moment an item was saved. Items saved before this feature was available on your storefront won't trigger back-in-stock, regardless of restocking, not a bug, it resolves on its own as shoppers save new items.

Errors

onError(status, xhr) fires on any non-2xx response or network failure. There's no special error code for "nothing to show", an empty wishlist still resolves successfully with empty (or popular-filled, for prioritized-items) arrays. A store that hasn't been enabled for Wishlist Picks also resolves successfully, with all four arrays empty and no error, that's the disabled state, not a failure, see the Not self-serve callout above.