REST API - Fetch Wishlist Picks

Endpoint

Use this from any backend, mobile app, or custom client that isn't running the JS SDK. regid and sessionid identify the shopper and must be supplied yourself, get them from your own session handling, or from a prior call to generate-regid.

🚧

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 endpoint.

Query Params

Form Data

Example Curl

curl --location --request POST '{{Swym API Endpoint}}/api/v2/provider/fetchWishlistPicks?pid={{URL Encoded PID}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'regid={{regid}}' \
--data-urlencode 'sessionid={{sessionid}}' \
--data-urlencode 'item-count={{item-count}}'

🚧

Curl Placeholders

Assuming these values are provided above, the curl command should work correctly. However, if there are any issues with the API endpoint or the data being passed in the request, there could still be errors that need to be resolved before you can test these APIs.

Success Response

Identical whether you called the REST endpoint directly or the JS SDK method. Each array is capped at item-count 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 item-count: 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 reason-order 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.

There's no special error code for "nothing to show", an empty wishlist still resolves successfully (HTTP 200) 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.

Error Status Codes:

If the request is unsuccessful, the API will return a JSON response with an error message and an HTTP status code indicating the type of error that occurred.