Wishlist Functions

The Wishlist drop-in provides API functions that enable you to programmatically control behavior, fetch data, and integrate with Adobe Commerce backend services.

Version: 3.3.0

Function	Description
addProductsToWishlist	Add products to a user’s wishlist.
clearPersistedLocalStorage	Removes the persisted wishlist data from local storage.
getAllItemsCacheVersion	Returns the current version of the all-items cache.
getDefaultWishlist	Fetches the authenticated customer’s default (first) wishlist.
getGuestWishlist	Returns the current guest wishlist from persisted storage.
getPersistedWishlistData	Returns wishlist data from browser storage.
getPersistedAllWishlistItems	Returns all persisted wishlist items from browser storage.
getStoreConfig	Retrieves the store configuration, which includes various settings and preferences for the store.
getWishlistById	Retrieves a wishlist by its ID.
getWishlistItemFromStorage	Looks up a specific wishlist item in browser storage by SKU and option UIDs.
getWishlists	Retrieves all wishlists associated with a user.
initializeWishlist	Initializes wishlist state for the drop-in.
mergeWishlists	Merge a wishlist from local storage with one belonging to a registered user.
removeProductsFromWishlist	Remove products from a user’s wishlist.
resetWishlist	Resets the wishlist by clearing the current wishlist ID and marking the user as unauthenticated.
setPersistedWishlistData	Persists wishlist data to browser storage.
setPersistedAllWishlistItems	Persists a full list of all wishlist items to browser storage.
addToPersistedAllWishlistItems	Appends items to the persisted all-items list.
removeFromPersistedAllWishlistItems	Removes items from the persisted all-items list.
findInPersistedAllWishlistItems	Looks up an item in the persisted all-items list by SKU and option UIDs.
updateProductsInWishlist	Update the quantity of products in a user’s wishlist.

addProductsToWishlist

The addProductsToWishlist function allows you to add products to a user’s wishlist. This function is typically used when a user wants to save a product for later purchase. The function calls the addProductsToWishlist mutation.

const addProductsToWishlist = async (
  items: [ { sku: string; quantity: number; optionsUIDs?: string[]; // should be the options available for the product enteredOptions?: { uid: string; value: string }[]; // refer to both selected and entered options } ]
): Promise<Wishlist | null>

Parameter	Type	Req?	Description
sku	string	Yes	The product identifier (SKU) for the product. For configurable products (like a shirt available in multiple colors and sizes), use the child product SKU that represents the specific variant selected by the customer (for example, `MS09-M-Blue` for a medium blue shirt).
quantity	number	Yes	The number of items. This value must be a positive number.
optionsUIDs	string[]	No	An array of option UIDs for configurable products—the selected options (such as color or size) that identify the variant. Use the product query to retrieve available option UIDs for a product.

Events

Emits the wishlist/data event with the updated wishlist information after adding the products. This event may be emitted multiple times depending on the operation flow (for example, creating a new wishlist, merging wishlists, or updating an existing wishlist).

Returns

Returns Wishlist or null.

getStoreConfig

The getStoreConfig function retrieves the store configuration, which includes various settings and preferences for the store.

const getStoreConfig = async (): Promise<StoreConfigModel | null>

Events

Does not emit any drop-in events.

Returns

Returns StoreConfigModel or null.

getWishlistById

The getWishlistById function returns a customer’s wishlist by ID, using the customer query, with the contents defined by the wishlist_v2 object.

const getWishlistById = async (
  wishlistId: string
): Promise<void | Wishlist | null>

Parameter	Type	Req?	Description
wishlistId	string	Yes	The unique identifier of the wishlist to retrieve.

Events

Emits the wishlist/data event with the retrieved wishlist information.

Returns

Returns void | Wishlist | null. See Wishlist.

getWishlists

The getWishlists function retrieves all wishlists associated with a user. This is useful for displaying all wishlists a user has created.

const getWishlists = async (): Promise<void | Wishlist[] | null>

Events

Does not emit any drop-in events.

Returns

Returns void | Wishlist[] | null. See Wishlist.

initializeWishlist

The initializeWishlist function loads wishlist state when the drop-in starts. Call it during setup so containers receive data before rendering.

const initializeWishlist = async (): Promise<Wishlist | null>

Events

Emits the following events: wishlist/data, wishlist/initialized.

Returns

Returns Wishlist or null.

mergeWishlists

The mergeWishlists function allows you to merge a wishlist from local storage with one belonging to a registered user. This is useful when a user wants to synchronize both local and remote wishlists into one wishlist after logging in.

Signature

function mergeWishlists(wishlist: Wishlist): Promise<Wishlist | null>

---

removeProductsFromWishlist

The removeProductsFromWishlist function allows you to remove products from a user’s wishlist. The function calls the removeProductsFromWishlist mutation.

const removeProductsFromWishlist = async (
  items: Array<Item>
): Promise<Wishlist | null>

Parameter	Type	Req?	Description
items	Array<Item>	Yes	An array of wishlist item identifiers to remove from the wishlist.

Events

Emits the wishlist/data event with the updated wishlist information after removing the products. This event may be emitted multiple times depending on whether the wishlist becomes empty after removal.

Returns

Returns Wishlist or null.

resetWishlist

The resetWishlist function resets the wishlist by clearing the current wishlist ID and marking the user as unauthenticated. It returns a promise that resolves to null.

const resetWishlist = async (): Promise<Wishlist | null>

Events

Does not emit any drop-in events.

Returns

Returns Wishlist or null.

updateProductsInWishlist

The updateProductsInWishlist function allows you to update the quantity of products in a user’s wishlist. The function calls the updateProductsInWishlist mutation.

const updateProductsInWishlist = async (
  items: { wishlistItemId: string; quantity: number; description: string; selectedOptions?: string[]; enteredOptions?: { uid: string; value: string }[]; }[]
): Promise<Wishlist | null>

Parameter	Type	Req?	Description
wishlistItemId	string	Yes	The unique identifier of the wishlist item to update. This ID is returned in the wishlist data structure when you retrieve a wishlist (not the product SKU). Each item in a wishlist has its own unique ID, even if multiple items reference the same product.
quantity	number	Yes	The new quantity for the item. This replaces the current quantity (it does not increment). For example, setting this to `2` will change the quantity to 2, regardless of the previous value. This value must be a positive number.
description	string	Yes	A text description.
selectedOptions	string[]	No	An array of option UIDs to update the selected product options for configurable products. For example, if a customer wants to change the size from **Medium** to **Large**, you would provide the UID for the Large option. These are the same type of option UIDs used when selecting product options.
enteredOptions	{ uid: string; value: string }[]	No	An array of custom options that allow text input for customizable products. Each object contains a `uid` (the unique identifier for the custom option field from the product data) and a `value` (the text the customer entered). These are typically used for personalization like engravings or custom messages.

Events

Does not emit any drop-in events.

Returns

Returns Wishlist or null.

clearPersistedLocalStorage

The clearPersistedLocalStorage function removes the persisted wishlist data from local storage. Used during sign-out or wishlist reset flows to clean up guest session data.

const clearPersistedLocalStorage = (): void

Events

Does not emit any drop-in events.

Returns

Returns void.

getDefaultWishlist

The getDefaultWishlist function fetches all wishlists for the authenticated customer and returns the first one as the default. Sets the retrieved wishlist ID in the drop-in state.

const getDefaultWishlist = async (): Promise<Wishlist | null>

Events

Does not emit any drop-in events.

Returns

Returns Wishlist or null if the customer has no wishlists.

getGuestWishlist

The getGuestWishlist function retrieves the current guest wishlist from persisted browser storage. Used internally by initializeWishlist when the user is not authenticated.

const getGuestWishlist = async (): Promise<Wishlist | {}>

Events

Does not emit any drop-in events.

Returns

Returns Wishlist or an empty object {} when no guest wishlist exists.

getPersistedWishlistData

The getPersistedWishlistData function returns wishlist data from browser storage. Reads from sessionStorage for authenticated users and localStorage for guests. Returns an empty wishlist object when no data is stored.

const getPersistedWishlistData = (guest?: boolean): Wishlist | {}

Parameter	Type	Req?	Description
guest	boolean	No	When true, forces reading from localStorage regardless of authentication state. Defaults to false.

Events

Does not emit any drop-in events.

Returns

Returns Wishlist or {} when no data is found.

getWishlistItemFromStorage

The getWishlistItemFromStorage function looks up a specific wishlist item in browser storage by its product SKU and option UIDs. Useful for checking whether a product (with specific configuration) is already in the wishlist.

const getWishlistItemFromStorage = (
  productSku: string,
  optionUIDs?: string[]
): WishlistItem | undefined

Parameter	Type	Req?	Description
productSku	string	Yes	The SKU of the product to look up.
optionUIDs	string[]	No	An array of selected option UIDs for configurable products. Defaults to an empty array.

Events

Does not emit any drop-in events.

Returns

Returns the matching wishlist item or undefined when not found.

setPersistedWishlistData

The setPersistedWishlistData function persists wishlist data to browser storage. Writes to sessionStorage for authenticated users and localStorage for guests. Passing null removes the stored wishlist.

const setPersistedWishlistData = (data: Wishlist | null): void

Parameter	Type	Req?	Description
data	Wishlist | null	Yes	The wishlist data to persist. Pass null to remove the stored data.

Events

Does not emit any drop-in events.

Returns

Returns void.

getAllItemsCacheVersion

The getAllItemsCacheVersion function returns the current version number of the all-items cache. The version increments whenever the persisted all-items list is modified, allowing consumers to detect stale data.

const getAllItemsCacheVersion = (): number

Events

Does not emit any drop-in events.

Returns

Returns number.

setPersistedAllWishlistItems

The setPersistedAllWishlistItems function persists a complete list of all wishlist items to browser storage, replacing any previously stored items.

const setPersistedAllWishlistItems = (items: Item[]): void

Parameter	Type	Req?	Description
items	Item[]	Yes	The full array of wishlist items to persist.

Events

Does not emit any drop-in events.

Returns

Returns void.

getPersistedAllWishlistItems

The getPersistedAllWishlistItems function returns all persisted wishlist items from browser storage.

const getPersistedAllWishlistItems = (): Item[]

Events

Does not emit any drop-in events.

Returns

Returns Item[].

clearPersistedAllWishlistItems

The clearPersistedAllWishlistItems function removes all persisted wishlist items from browser storage.

const clearPersistedAllWishlistItems = (): void

Events

Does not emit any drop-in events.

Returns

Returns void.

addToPersistedAllWishlistItems

The addToPersistedAllWishlistItems function appends items to the persisted all-items list in browser storage.

const addToPersistedAllWishlistItems = (items: Item[]): void

Parameter	Type	Req?	Description
items	Item[]	Yes	The wishlist items to append.

Events

Does not emit any drop-in events.

Returns

Returns void.

removeFromPersistedAllWishlistItems

The removeFromPersistedAllWishlistItems function removes items from the persisted all-items list in browser storage.

const removeFromPersistedAllWishlistItems = (items: Item[]): void

Parameter	Type	Req?	Description
items	Item[]	Yes	The wishlist items to remove.

Events

Does not emit any drop-in events.

Returns

Returns void.

findInPersistedAllWishlistItems

The findInPersistedAllWishlistItems function looks up an item in the persisted all-items list by its product SKU and option UIDs. Useful for checking whether a product (with a specific configuration) is already in the wishlist across all pages.

const findInPersistedAllWishlistItems = (
  sku: string,
  optionUIDs?: string[]
): Item | undefined

Parameter	Type	Req?	Description
sku	string	Yes	The SKU of the product to look up.
optionUIDs	string[]	No	An array of selected option UIDs for configurable products. Defaults to an empty array.

Events

Does not emit any drop-in events.

Returns

Returns the matching wishlist item or undefined when not found.

Data Models

The following data models are used by functions in this drop-in.

StoreConfigModel

The StoreConfigModel object is returned by the following functions: getStoreConfig.

interface StoreConfigModel {
  wishlistIsEnabled: boolean;
  wishlistMaxNumber: number;
  wishlistMultipleListIsEnabled: boolean;
}

Wishlist

The Wishlist object is returned by the following functions: addProductsToWishlist, getWishlistById, getWishlists, initializeWishlist, mergeWishlists, removeProductsFromWishlist, resetWishlist, updateProductsInWishlist.

interface Wishlist {
  id: string;
  updated_at: string;
  sharing_code: string;
  items_count: number;
  items: Item[];
}