Dev: JavaScript API

Initialization

`ready()`

Waits for the helper to finish initializing. Should be called before any other method.

await window.refactor_apps.wishlist.ready();

Returns Promise<void> . May throw on unexpected runtime, storage, or network failures.

List methods

`getAllLists(options?)`

Returns all wishlist lists for the current user.

// From cache const lists = await window.refactor_apps.wishlist.getAllLists();  // Force refresh from server (authenticated users only) const freshLists = await window.refactor_apps.wishlist.getAllLists({ forceSync: true });

Parameters:

options.forceSync (Boolean, optional) — bypasses the cache and fetches fresh data from the server.

Returns: Promise<Array<Object>> — array of normalized list objects.

Possible errors: NETWORK_FAILED , HTTP_REQUEST_FAILED , REQUEST_FAILED , SUBSCRIPTION_INACTIVE , STORAGE_WRITE_FAILED .

`getWishlistCount(listId?)`

Returns the number of unique wishlist items that exist in the store catalog. Without listId , counts across all lists. With listId , counts unique variants in that list. Deleted or unpublished catalog items are excluded.

// Across all lists
const count = await window.refactor_apps.wishlist.getWishlistCount();

// For a specific list
const listCount = await window.refactor_apps.wishlist.getWishlistCount('your-list-id');

Parameters:

listId (String, optional) — ID of the list. When omitted, counts across all lists.

Returns: Promise<Number> — count of catalog-available wishlist items.

Possible errors: LIST_ID_REQUIRED , LIST_NOT_FOUND .

`createList(listName, listDescription?)`

Creates a new wishlist.

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

Parameters:

listName (String) — name of the new list. Required.
listDescription (String, optional) — description for the list.

Returns: Promise<Array<Object>> — updated array of all lists.

Possible errors: LIST_NAME_REQUIRED , LIST_DESCRIPTION_INVALID , NETWORK_FAILED , HTTP_REQUEST_FAILED , REQUEST_FAILED , SUBSCRIPTION_INACTIVE , STORAGE_WRITE_FAILED .

`clearList(listId)`

Removes all products from a list while keeping the list itself.

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

Parameters:

listId (String) — ID of the list to clear.

Returns: Promise<Object> — updated list object with an empty products array.

Possible errors: LIST_ID_REQUIRED , LIST_NOT_FOUND , NETWORK_FAILED , HTTP_REQUEST_FAILED , REQUEST_FAILED , SUBSCRIPTION_INACTIVE , STORAGE_WRITE_FAILED .

Product methods

`addProduct(listId, product)`

Adds a product variant to a list.

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

Parameters:

listId (String) — ID of the list.
product (Object) — object with id and variantId fields (numeric values or GIDs).

Returns: Promise<Object> — updated list object.

Possible errors: LIST_ID_REQUIRED , LIST_NOT_FOUND , INVALID_PRODUCT_INPUT , ALREADY_IN_LIST , NETWORK_FAILED , HTTP_REQUEST_FAILED , REQUEST_FAILED , SUBSCRIPTION_INACTIVE , STORAGE_WRITE_FAILED .

`removeProduct(listId, product)`

Removes a product variant from a list.

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

Parameters:

listId (String) — ID of the list.
product (Object) — object with id and variantId fields.

Returns: Promise<Object> — updated list object.

Possible errors: LIST_ID_REQUIRED , LIST_NOT_FOUND , INVALID_PRODUCT_INPUT , NOT_FOUND_IN_LIST , NETWORK_FAILED , HTTP_REQUEST_FAILED , REQUEST_FAILED , SUBSCRIPTION_INACTIVE , STORAGE_WRITE_FAILED .

`hasVariantInList(listId, variantId)`

Checks whether a specific variant exists in the specified list.

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

Parameters:

listId (String) — ID of the list.
variantId (String | Number) — variant ID as a numeric value or GID.

Returns: Promise<Boolean> .

Possible errors: LIST_ID_REQUIRED , VARIANT_ID_REQUIRED , LIST_NOT_FOUND .

`getUniqueWishlistItems()`

Returns a deduplicated array of all items across all lists. Useful for counting unique wishlist items across all lists.

const items = await window.refactor_apps.wishlist.getUniqueWishlistItems(); // [{ productId: number, variantId: number, listId: string }]

Parameters: none.

Returns: Promise<Array<Object>> .

Possible errors: same as getAllLists() , since this method depends on list loading internally.

Flow Triggers

The helper automatically dispatches events to Shopify Flow whenever the wishlist changes.

Event	User type	`flowHandle`
Variant added	Authenticated	`variant-added-to-wishlist`
Variant added	Guest	`variant-added-to-wishlist-guest`
Variant removed	Authenticated	`variant-removed-from-wishlist`
Variant removed	Guest	`variant-removed-from-wishlist-guest`

The payload format is the same for all events:

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

Do you need help?

If you have any questions or run into issues, please contact us — we’re happy to help.