Instruction

Introduction

The  WishlistHelper  is exposed on  window.refactor_apps.wishlist  after initialization. It stores and syncs users' wishlist data in localStorage and the cloud. You can call its methods anywhere in your storefront scripts.

How to use "R+ Wishlist"?

First of all, you need to activate the App Embed Extension. Follow these steps:

1. In your Shopify admin, go to Online Store / Themes.
2. Find the theme you want to edit, and then click "Customize."
3. On the sidebar, click the App embeds icon.
4. Select the app embed "R+ Wishlist - Helper".
5. Besides the app embed, click the toggle button to activate it.
6. Click Save.

After that, in the theme in which you activated App Embed, you will be able to access the helper functions.

All helper functions are stored in the global  window.refactor_apps.wishlist  object.

You can check that everything is fine by running this command:

const lists = await window.refactor_apps.wishlist.getAllLists();
console.log(lists);

Public Methods

window.refactor_apps.wishlist.ready()

Accepts:

// No parameters

Returns:

@returns {Promise<void>} - Resolves when helper initialization is complete

Errors:

@throws {Error} - Initialization may reject on unexpected runtime/storage/network failures

Example:

await window.refactor_apps.wishlist.ready();

window.refactor_apps.wishlist.getAllLists()

Accepts:

@param options {Object} [Optional] - Optional query options
@param options.forceSync {Boolean} [Optional] - Forces server refresh for authenticated customer

Returns:

@returns {Promise<Array<Object>>} - All normalized wishlist lists

Errors:

@throws {Error} - NETWORK_FAILED (request could not be completed)
@throws {Error} - HTTP_REQUEST_FAILED (non-JSON or unsuccessful HTTP response)
@throws {Error} - REQUEST_FAILED (server returned application-level error)
@throws {Error} - SUBSCRIPTION_INACTIVE (subscription is not active)
@throws {Error} - STORAGE_WRITE_FAILED (local persistence failed)

Example:

const lists = await window.refactor_apps.wishlist.getAllLists();
const freshLists = await window.refactor_apps.wishlist.getAllLists({
  forceSync: true,
});
console.log(freshLists);

window.refactor_apps.wishlist.hasVariantInList()

Accepts:

@param listId {String} - ID of the list
@param variantId {String|Number} - Variant ID (numeric value or GID)

Returns:

@returns {Promise<Boolean>} - true if variant is in the list, false otherwise

Errors:

@throws {Error} - LIST_ID_REQUIRED (list id is empty or missing)
@throws {Error} - VARIANT_ID_REQUIRED (variant id is empty, invalid, or not parseable)
@throws {Error} - LIST_NOT_FOUND (no list exists with this id)

Example:

const exists = await window.refactor_apps.wishlist.hasVariantInList(
  'your-list-id',
  123456789,
);
console.log(`Product is in list? ${exists}`);

window.refactor_apps.wishlist.getUniqueWishlistItems()

Accepts:

// No parameters

Returns:

@returns {Promise<Array<Object>>} - Deduplicated items across all lists
// [{ productId: number, variantId: number, listId: string }]

Errors:

@throws {Error} - Same error set as getAllLists() because this method depends on list loading

Example:

const items = await window.refactor_apps.wishlist.getUniqueWishlistItems();
console.log(items);

window.refactor_apps.wishlist.createList()

Accepts:

@param listName {String} - Name of the new list
@param listDescription {String} [Optional] - Description for the list

Returns:

@returns {Promise<Array<Object>>} - Updated array of all lists

Errors:

@throws {Error} - LIST_NAME_REQUIRED (list name is empty or missing)
@throws {Error} - LIST_DESCRIPTION_INVALID (description is not a string)
@throws {Error} - NETWORK_FAILED (request could not be completed)
@throws {Error} - HTTP_REQUEST_FAILED (non-JSON or unsuccessful HTTP response)
@throws {Error} - REQUEST_FAILED (server returned application-level error)
@throws {Error} - SUBSCRIPTION_INACTIVE (subscription is not active)
@throws {Error} - STORAGE_WRITE_FAILED (local persistence failed)

Example:

const allLists = await window.refactor_apps.wishlist.createList(
  'Favorites',
  'My favorite items',
);
console.log(allLists);

window.refactor_apps.wishlist.clearList()

Accepts:

@param listId {String} - ID of the list to clear

Returns:

@returns {Promise<Object>} - Updated list object with empty products

Errors:

@throws {Error} - LIST_ID_REQUIRED (list id is empty or missing)
@throws {Error} - LIST_NOT_FOUND (no list exists with this id)
@throws {Error} - NETWORK_FAILED (request could not be completed)
@throws {Error} - HTTP_REQUEST_FAILED (non-JSON or unsuccessful HTTP response)
@throws {Error} - REQUEST_FAILED (server returned application-level error)
@throws {Error} - SUBSCRIPTION_INACTIVE (subscription is not active)
@throws {Error} - STORAGE_WRITE_FAILED (local persistence failed)

Example:

const cleared = await window.refactor_apps.wishlist.clearList('your-list-id');
console.log(cleared);

window.refactor_apps.wishlist.addProduct()

Accepts:

@param listId {String} - ID of the list
@param product {Object} - { id: number|string, variantId: number|string }

Returns:

@returns {Promise<Object>} - Updated list object

Errors:

@throws {Error} - LIST_ID_REQUIRED (list id is empty or missing)
@throws {Error} - LIST_NOT_FOUND (no list exists with this id)
@throws {Error} - INVALID_PRODUCT_INPUT (id and variantId are required and must be numeric/GID-compatible)
@throws {Error} - ALREADY_IN_LIST (product+variant pair already exists in this list)
@throws {Error} - NETWORK_FAILED (request could not be completed)
@throws {Error} - HTTP_REQUEST_FAILED (non-JSON or unsuccessful HTTP response)
@throws {Error} - REQUEST_FAILED (server returned application-level error)
@throws {Error} - SUBSCRIPTION_INACTIVE (subscription is not active)
@throws {Error} - STORAGE_WRITE_FAILED (local persistence failed)

Example:

const product = { id: 15359342215537, variantId: 62808509088113 };
const updated = await window.refactor_apps.wishlist.addProduct(
  'your-list-id',
  product,
);
console.log(updated);

window.refactor_apps.wishlist.removeProduct()

Accepts:

@param listId {String} - ID of the list
@param product {Object} - { id: number|string, variantId: number|string }

Returns:

@returns {Promise<Object>} - Updated list object

Errors:

@throws {Error} - LIST_ID_REQUIRED (list id is empty or missing)
@throws {Error} - LIST_NOT_FOUND (no list exists with this id)
@throws {Error} - INVALID_PRODUCT_INPUT (id and variantId are required and must be numeric/GID-compatible)
@throws {Error} - NOT_FOUND_IN_LIST (product+variant pair is not present in this list)
@throws {Error} - NETWORK_FAILED (request could not be completed)
@throws {Error} - HTTP_REQUEST_FAILED (non-JSON or unsuccessful HTTP response)
@throws {Error} - REQUEST_FAILED (server returned application-level error)
@throws {Error} - SUBSCRIPTION_INACTIVE (subscription is not active)
@throws {Error} - STORAGE_WRITE_FAILED (local persistence failed)

Example:

const product = { id: 15359342215537, variantId: 62808509088113 };
const updated = await window.refactor_apps.wishlist.removeProduct(
  'your-list-id',
  product,
);
console.log(updated);

Flow Triggers

Variant added to wishlist

Sent when a variant is added to a wishlist list.

• Authorized (logged-in) user - Event is sent with flowHandle: "variant-added-to-wishlist" .
• Guest (not logged-in) user - Event is sent with flowHandle: "variant-added-to-wishlist-guest" .

Sync event payload format:

{
  "productId": "15359342215537",
  "variantId": "62808509088113",
  "flowHandle": "variant-added-to-wishlist"
}

Variant removed from wishlist

Sent when a variant is removed from a wishlist list.

• Authorized (logged-in) user - Event is sent with flowHandle: "variant-removed-from-wishlist" .
• Guest (not logged-in) user - Event is sent with flowHandle: "variant-removed-from-wishlist-guest" .

Sync event payload format:

{
  "productId": "15359342215537",
  "variantId": "62808509088113",
  "flowHandle": "variant-removed-from-wishlist"
}