How do I script the wishlist with the JavaScript SDK?

The Wishlist Hero JavaScript SDK exposes the wishlist to your theme code through a single global object, window.WishListHero_SDK . Use it to build custom buttons, render your own wishlist UI, or add and remove items from anywhere on the page.

Available on Silver plans and above. Calls from stores without the feature return { ok: false, status: 403, error } .

Load and readiness

The SDK loads with the app’s storefront bundle. Wait for the ready event before calling anything:

document.addEventListener("wishlist-hero-wishlist-sdk-ready", () => {
  const sdk = window.WishListHero_SDK;
  console.log("SDK ready, items:", sdk.GetWishListItemsCount());
});

Two more globals matter in custom work:

window.WishListHero_setting : your store’s full client settings, published from the app
window.WishListHero_block_settings : overrides from the theme editor blocks

Methods

Method	Returns	Does
`OpenWishList()`	void	Opens the wishlist (popup or page, per your display mode)
`GetWishListHash(createIfNotFound)`	string or Promise	The wishlist hash. With `true`, creates a wishlist when none exists and resolves on creation
`GetWishListItemsCount()`	number	Items in the list, from local storage
`GetWishListItems()`	array	Local items snapshot
`GetWishListItemsFromServer()`	Promise	Fresh items from the server
`GetCustomerId()`	string	The logged in customer ID, when present
`AddWishListItem(productInfo)`	Promise	Adds a product
`DeleteWishListItem(productInfo)`	Promise	Removes one variant
`DeleteAllWishListItems(productInfo)`	Promise	Clears the list
`InitializeAddToWishListButton(buttonInfo)`	void	Turns any element into a wishlist button

Adding and removing items

AddWishListItem takes a product descriptor:

window.WishListHero_SDK.AddWishListItem({
  ProductId: "1234567890123",
  ProductVariantId: "1234567890456",
  ProductTitle: "Classic Leather Jacket",
  ProductPrice: 189.99,
  ProductLink: "/products/classic-leather-jacket",
  ProductImage: "https://cdn.shopify.com/…jpg",
});

DeleteWishListItem needs the hash and the variant:

window.WishListHero_SDK.DeleteWishListItem({
  WishlistHash: "your_wishlist_hash",
  ProductVariantId: "1234567890456",
});

Adds and deletes made through the SDK update the same cloud wishlist as button clicks, fire the same document events, and appear in the same reports.

Building custom buttons

InitializeAddToWishListButton wires any element into a working wishlist button:

window.WishListHero_SDK.InitializeAddToWishListButton({
  ButtonClassElement: ".my-buy-box",
  ProductId: "1234567890123",
  ProductVariantId: "1234567890456",
  ProductLink: "/products/classic-leather-jacket",
  ProductTitle: "Classic Leather Jacket",
  ProductPrice: 189.99,
  ProductImage: "https://cdn.shopify.com/…jpg",
});

The SDK tags the target with data-wlh-* attributes and the wishlisthero-quick-view class, then dispatches wishlist-hero-add-to-custom-element , and the storefront app takes over rendering and state.

For statically known products you can skip the SDK call: give the element class wishlist-hero-custom-button plus the data-wlh-* attributes, and the app binds it automatically once wishlist-hero-links-binded fires.

The hide toggles contract

Custom UI work pairs with two settings:

Disable automatic product button placement in the App Configuration embed stops the app from injecting its own product buttons, leaving yours as the only ones
Show add to cart button in the wishlist display settings controls whether the app renders cart actions inside its own wishlist views

Keep them in mind when you replace either surface; the full pattern is in Build a custom wishlist UI.

Errors

Invalid or missing parameters are rejected rather than thrown, with a result object:

{ ok: false, status: 400 }

Common statuses: 400 bad parameters, 403 feature not on your plan or app disabled. Always branch on ok instead of assuming the network call succeeded.