Advanced Patterns

Multiple Wishlists

Use the Lists API for multi-wishlist support:

window.SwymCallbacks = window.SwymCallbacks || [];
window.SwymCallbacks.push(function(swat) {

  // Fetch all wishlists
  swat.fetchLists({
    callbackFn: function(lists) {
      // lists = array of { lid, lname, listcontents, ... }
    },
    errorFn: function(err) {
      // handle error
    }
  });

  // Add to a specific list
  swat.addToList(
    'list-uuid-here',
    { epi: 123, empi: 456, du: 'https://yourstore.myshopify.com/products/example' },
    function(result) { /* success */ },
    function(err) { /* error */ }
  );

  // Remove from a specific list
  swat.deleteFromList(
    'list-uuid-here',
    { epi: 123, empi: 456, du: 'https://yourstore.myshopify.com/products/example' },
    function(result) { /* success */ },
    function(err) { /* error */ }
  );

});

Custom Properties (cprops)

Attach arbitrary metadata to wishlist items for advanced use cases like quantity, personalization, or gift registries:

window.SwymCallbacks = window.SwymCallbacks || [];
window.SwymCallbacks.push(function(swat) {

  swat.addToWishList({
    epi: 41255230701766,
    empi: 7096437407942,
    du: 'https://yourstore.myshopify.com/products/example',
    qty: 2,                              // Quantity (defaults to 1)
    note: 'Size runs small, order up',   // Custom note
    cprops: {                            // Arbitrary key-value pairs
      "engraving": "Happy Birthday",
      "gift_wrap": true,
      "priority": "high"
    },
    source: 'pdp'                        // Tracking source for analytics
  }, function(result) {
    // Success
  }, function(error) {
    // Error
  });

});

Use Cases

Feature	Fields Used
Quantity selector	`qty: 2`
Gift registry	`cprops: { "occasion": "wedding", "priority": "high" }`
Personalization	`cprops: { "engraving": "text", "color_choice": "blue" }`
Notes per item	`note: "My notes here"`
Source tracking	`source: "pdp"` or `"collections-grid"`

Constraints

cprops has a character limit — keep values lightweight (key-value pairs, not large blobs)
cprops values are not visible in the Swym admin dashboard
Reading cprops back: swat.fetch() returns items with cprops attached
Valid source values: pdp, collections-grid, quick-view, featured-grid, recommendations, search-results, plp. Invalid values trigger request blocking.

Reading Custom Properties

swat.fetch(function(products) {
  products.forEach(function(item) {
    if (item.cprops && item.cprops.engraving) {
      // Display personalization in the wishlist page card
    }
    if (item.qty && item.qty > 1) {
      // Show quantity badge
    }
  });
});

Back-in-Stock Subscription

window.SwymCallbacks = window.SwymCallbacks || [];
window.SwymCallbacks.push(function(swat) {

  swat.sendWatchlist(
    '[email protected]',            // medium value
    'email',                        // medium type
    { epi: 123, empi: 456, du: 'https://yourstore.myshopify.com/products/example' },
    function(result) { /* subscribed */ },
    function(err) { /* error */ }
  );

});

Event Listening

Subscribe to SDK events for real-time UI updates:

window.SwymCallbacks = window.SwymCallbacks || [];
window.SwymCallbacks.push(function(swat) {

  if (swat.evtLayer) {
    swat.evtLayer.addEventListener('sw:addedtowishlist', function(e) {
      // e.detail contains the product data
    });

    swat.evtLayer.addEventListener('sw:removedfromwishlist', function(e) {
      // e.detail contains the product data
    });

    swat.evtLayer.addEventListener('sw:addedtocart', function(e) {
      // e.detail contains the cart item data
    });
  }

});

Error Handling

addToWishList and removeFromWishList accept an optional error callback as the third argument:

window.SwymCallbacks = window.SwymCallbacks || [];
window.SwymCallbacks.push(function(swat) {

  swat.addToWishList(
    { epi: 123, empi: 456, du: 'https://yourstore.myshopify.com/products/example' },
    function(result) {
      // Success — update UI
    },
    function(error) {
      // Error — show message, revert button state, etc.
    }
  );

});

Common error causes: missing du, invalid epi/empi, network failure, or SDK not initialized (always use SwymCallbacks).

Troubleshooting

Problem	Cause	Fix
`window._swat` is undefined	SDK not loaded yet	Always use `SwymCallbacks` — never access `_swat` directly
`_SwymSDKOnlyMode` is not true	`show_ui` is checked	Uncheck "Show UI" on Storefront UI Elements
Button state doesn't match	`epi`/`empi` mismatch	Ensure variant ID = `epi`, product ID = `empi`
CORS errors	Wrong domain	SDK must run on the store's own domain
`addToWishList` callback not firing	Missing required fields	Ensure `epi`, `empi`, and `du` are all provided
Count badge not updating	No event listeners	Verify `swat.evtLayer` exists before adding listeners
Collection buttons missing after filter	DOM changed	Use MutationObserver pattern (see Collection Buttons)
Price shows NaN	Wrong units	`{{ variant.price }}` returns cents — divide by 100
Header count badge stretched into oval	Theme CSS `.header__icon span { height: 100% }`	Set explicit `height: 1.7rem !important` on badge, match `.cart-count-bubble`
Collection "Unknown product" error	`epi` set to product ID instead of variant ID	Use `swat.getProductDetails({ du })` to fetch proper variant ID

Full API Reference

Wishlist Plus JavaScript SDK — List API, sharing, comments
Shopper API — Shopper context and identity
Triggered UI Events — Full event catalog