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.1.0

Function	Description
addProductsToWishlist	Add products to a user’s wishlist.
getStoreConfig	Retrieves the store configuration, which includes various settings and preferences for the store..
getWishlistById	Retrieves a wishlist by its ID.
getWishlists	Retrieves all wishlists associated with a user.
initializeWishlist	API function 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.
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 (e.g., `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. These are the UIDs of the selected product options (such as color or size) that are selected. These represent the selected product 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 (e.g., 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 retrieves a wishlist by its ID. This is useful for accessing a specific user’s wishlist. The function calls the wishlist_v2 query.

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

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

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.

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[];
}