For most stores, the theme setup wizard handles everything. This guide is for developers building custom themes, headless storefronts, or advanced integrations who need direct access to the Wishlist SDK and APIs.
App Embed vs App Block
Wishlist uses two integration methods:
App Embed - A global script that loads on every page. Enables functionality site-wide, loads the SDK, handles auth, and manages storage. Enable in: Theme Editor > App embeds > Wishlist
App Block - Placed on specific pages to render buttons, collection icons, and the wishlist page. Add in: Theme Editor > Add block > Apps > Wishlist
Both must be enabled for full functionality.
Manual Theme Installation
For headless or custom themes, install manually:
1. Add the SDK script (in theme.liquid before </head>):
#{{ 'wishlist-hero.js' | asset_url | script_tag }}2. Initialize the SDK:
window.WishlistHero.init({
shopDomain: '#{{ shop.permanent_domain }}',
customerId: '#{{ customer.id }}',
customerEmail: '#{{ customer.email }}'
});3. Add button containers:
<div data-wishlist-button data-product-id="#{{ product.id }}" data-variant-id="#{{ product.selected_or_first_available_variant.id }}"></div>JavaScript API
Control wishlist programmatically:
// Add product
WishlistHero.add({ productId: 123456789, variantId: 987654321 });// Remove product
WishlistHero.remove({ productId: 123456789, variantId: 987654321 });// Check if saved
const isSaved = WishlistHero.isSaved({ productId: 123456789, variantId: 987654321 });// Get all items
const items = WishlistHero.getItems();// Get count
const count = WishlistHero.getCount();Custom Event Handling
Listen for wishlist events:
document.addEventListener('wishlist:added', (event) => {
console.log('Added:', event.detail.product);
});document.addEventListener('wishlist:removed', (event) => {
console.log('Removed:', event.detail.product);
});document.addEventListener('wishlist:updated', (event) => {
console.log('Count:', event.detail.count);
});Available events:
wishlist:added- Item addedwishlist:removed- Item removedwishlist:updated- List changedwishlist:loaded- SDK initialized