Cart Functions

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

Version: 1.5.1

Function	Description
addProductsToCart	The addProductsToCart function adds products to a cart.
applyCouponsToCart	A function that applies or replaces one or more coupons to the cart..
applyGiftCardToCart	The applyGiftCardToCart function is used to apply a gift card to the current shopping cart.
createGuestCart	The createGuestCart function creates a new empty cart for a guest user.
getCartData	The getCartData function is mainly used internally by the initializeCart() and refreshCart() functions.
getEstimatedTotals	A function that returns estimated totals for cart based on an address.
getEstimateShipping	The getEstimateShipping function returns the first available shipping method and its estimated cost, based on the provided address.
getStoreConfig	The getStoreConfig function returns information about a store’s configuration.
initializeCart	The initializeCart function initializes a guest or customer cart.
publishShoppingCartViewEvent	Publishes a shopping cart view event to the ACDL.
refreshCart	The refreshCart function refreshes the cart data..
removeGiftCardFromCart	This function removes a single gift card from the cart.
resetCart	This function resets the cart drop-in.
setGiftOptionsOnCart	setGiftOptionsOnCart is a function that sets gift options on the cart.
updateProductsFromCart	The updateProductsFromCart function updates cart items by either changing the quantity or removing and adding an item in one step.

addProductsToCart

The addProductsToCart function adds products to a cart. You must supply a sku and quantityfor each product. The other parameters are specified for complex product types. The function calls the addProductsToCart mutation.

const addProductsToCart = async (
  items: {
    sku: string;
    parentSku?: string;
    quantity: number;
    optionsUIDs?: string[];
    enteredOptions?: { uid: string; value: string }[];
    customFields?: Record<string, any>;
  }[]
): Promise<CartModel | null>

Parameter	Type	Req?	Description
sku	string	Yes	The SKU of the product.
parentSku	string	No	For a child product, the SKU of its parent product.
quantity	number	Yes	The amount or number of an item to add.
optionsUIDs	string[]	No	The selected options for the base product, such as color or size, using the unique ID for an object.
enteredOptions	{ uid: string; value: string }[]	No	An array of entered options for the base product, such as personalization text.
customFields	Record<string, any>	No	Custom attributes or additional data to associate with the product in the cart.

Events

Emits the cart/updated and cart/data events with the CartModel as the data payload. Additionally, emits cart/product/added for new items and cart/product/updated for items with increased quantities. Also publishes add-to-cart or remove-from-cart events to the Adobe Client Data Layer (ACDL).

Returns

Returns CartModel or null.

---

applyCouponsToCart

A function that applies or replaces one or more coupons to the cart.

const applyCouponsToCart = async (
  couponCodes: string[],
  type: ApplyCouponsStrategy
): Promise<CartModel | null>

Parameter	Type	Req?	Description
couponCodes	string[]	Yes	An array of coupon codes to apply to the cart.
type	ApplyCouponsStrategy	Yes	The strategy for applying coupons. See ApplyCouponsStrategy.

Events

Emits the cart/updated and cart/data events with the updated cart information after applying the coupons.

Returns

Returns CartModel or null.

---

applyGiftCardToCart

The applyGiftCardToCart function is used to apply a gift card to the current shopping cart. It takes the gift card code as an argument and updates the cart with the applied gift card.

const applyGiftCardToCart = async (
  giftCardCode: string
): Promise<CartModel | null>

Parameter	Type	Req?	Description
giftCardCode	string	Yes	The code assigned to a gift card.

Events

Emits the cart/updated and cart/data events. Also publishes add-to-cart or remove-from-cart events to the Adobe Client Data Layer (ACDL).

Returns

Returns CartModel or null.

---

createGuestCart

The createGuestCart function creates a new empty cart for a guest user. This is typically used internally by the cart initialization process.

const createGuestCart = async (): Promise<any>

Returns

Returns the cart ID for the newly created guest cart: cartId: string | null

---

getCartData

The getCartData function is mainly used internally by the initializeCart() and refreshCart() functions. If you need detailed information about the current user’s shopping cart, a more optimal approach is to listen for cart/data or cart/updated events so that you do not need to make another network call.

const getCartData = async (): Promise<CartModel | null>

Returns

Returns CartModel or null.

---

getEstimatedTotals

A function that returns estimated totals for cart based on an address. It takes an address parameter.

const getEstimatedTotals = async (
  address: EstimateAddressShippingInput
): Promise<CartModel | null>

Parameter	Type	Req?	Description
address	EstimateAddressShippingInput	Yes	The shipping address used to calculate estimated cart totals, taxes, and shipping costs. See EstimateAddressShippingInput.

Returns

Returns CartModel or null.

---

getEstimateShipping

The getEstimateShipping function returns the first available shipping method and its estimated cost, based on the provided address. The function calls the estimateShippingMethods mutation. Note: This function returns raw GraphQL data. For a transformed ShippingMethod object, listen to the shipping/estimate event instead.

const getEstimateShipping = async (
  address: EstimateAddressInput
): Promise<any | null>

Parameter	Type	Req?	Description
address	EstimateAddressInput	Yes	The address criteria used to determine available shipping methods. See EstimateAddressInput.

Events

Emits the shipping/estimate event, which contains the transformed ShippingMethod data along with address information.

Returns

Returns a RawShippingMethodGraphQL object with snake_case properties from the GraphQL response, or null if no valid shipping method is available: GraphQL response structure

---

getStoreConfig

The getStoreConfig function returns information about a store’s configuration. The function calls the storeConfig query.

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

Returns

Returns StoreConfigModel or null.

---

initializeCart

The initializeCart function initializes a guest or customer cart. This function is automatically called during the initialize phase of a dropin’s lifecycle. You do not need to call this manually.

const initializeCart = async (): Promise<CartModel | null>

Events

Emits the cart/initialized, cart/data, and cart/merged events. The event payload contains data about the address and shipping method.

Returns

Returns CartModel or null.

---

publishShoppingCartViewEvent

Publishes a shopping cart view event to the ACDL. This function sets the shopping cart context and triggers a SHOPPING_CART_VIEW event on the Adobe Client Data Layer, typically used when a cart page loads.

const publishShoppingCartViewEvent = async (): any

Events

Publishes the SHOPPING_CART_VIEW event to the Adobe Client Data Layer (ACDL) with the current cart context.

Returns

Returns void.

---

refreshCart

The refreshCart function refreshes the cart data.

const refreshCart = async (): Promise<CartModel | null>

Events

Emits the cart/data event with the updated cart information.

Returns

Returns CartModel or null.

---

removeGiftCardFromCart

This function removes a single gift card from the cart. It function calls the removeGiftCardFromCart mutation.

const removeGiftCardFromCart = async (
  giftCardCode: string
): Promise<CartModel | null>

Parameter	Type	Req?	Description
giftCardCode	string	Yes	Defines the gift card code to remove.

Events

Emits the cart/updated and cart/data events.

Returns

Returns CartModel or null.

---

resetCart

This function resets the cart drop-in. As a result, the cart ID is set to null and the authenticated status is set to false.

const resetCart = async (): Promise<CartModel | null>

Returns

Returns CartModel or null.

---

setGiftOptionsOnCart

setGiftOptionsOnCart is a function that sets gift options on the cart. It takes a giftOptions parameter.

const setGiftOptionsOnCart = async (
  giftForm: GiftFormDataType
): Promise<CartModel | null>

Parameter	Type	Req?	Description
giftForm	GiftFormDataType	Yes	Defines the gift options to set.

Events

Emits the cart/updated and cart/data events.

Returns

Returns CartModel or null.

---

updateProductsFromCart

The updateProductsFromCart function updates cart items by either changing the quantity or removing and adding an item in one step. When passing a specified quantity, the function replaces the current quantity. Setting the quantity to 0 removes an item from the cart. The function calls the updateCartItems mutation.

When an optionsUIDs array is sent along with the cart item’s UID and quantity, the function adds the item with the specified options. It removes any pre-existing item with the same UID that lacks the newly provided optionsUIDs. In this process, the function invokes first the addProductsToCart, and later the updateCartItems mutations.

const updateProductsFromCart = async (
  items: UpdateProductsFromCart
): Promise<CartModel | null>

Parameter	Type	Req?	Description
items	UpdateProductsFromCart	Yes	An input object that defines products to be updated.

Events

Emits the cart/updated and cart/data events. Additionally, emits cart/product/updated event with the affected items when their quantities are changed. Also publishes add-to-cart or remove-from-cart events to the Adobe Client Data Layer (ACDL).

Returns

Returns CartModel or null.

---

Data Models

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

CartModel

The CartModel object is returned by the following functions: addProductsToCart, applyCouponsToCart, applyGiftCardToCart, getCartData, getEstimatedTotals, initializeCart, refreshCart, removeGiftCardFromCart, resetCart, setGiftOptionsOnCart, updateProductsFromCart.

interface CartModel {
  totalGiftOptions: {
    giftWrappingForItems: Price;
    giftWrappingForItemsInclTax: Price;
    giftWrappingForOrder: Price;
    giftWrappingForOrderInclTax: Price;
    printedCard: Price;
    printedCardInclTax: Price;
  };
  cartGiftWrapping: {
    uid: string;
    design: string;
    selected: boolean;
    image: WrappingImage;
    price: Price;
  }[];
  giftReceiptIncluded: boolean;
  printedCardIncluded: boolean;
  giftMessage: {
    recipientName: string;
    senderName: string;
    message: string;
  };
  appliedGiftCards: AppliedGiftCardProps[];
  id: string;
  totalQuantity: number;
  totalUniqueItems: number;
  errors?: ItemError[];
  items: Item[];
  miniCartMaxItems: Item[];
  total: {
    includingTax: Price;
    excludingTax: Price;
  };
  discount?: Price;
  subtotal: {
    excludingTax: Price;
    includingTax: Price;
    includingDiscountOnly: Price;
  };
  appliedTaxes: TotalPriceModifier[];
  totalTax?: Price;
  appliedDiscounts: TotalPriceModifier[];
  shipping?: Price;
  isVirtual?: boolean;
  addresses: {
    shipping?: {
      countryCode: string;
      zipCode?: string;
      regionCode?: string;
    }[];
  };
  isGuestCart?: boolean;
  hasOutOfStockItems?: boolean;
  hasFullyOutOfStockItems?: boolean;
  appliedCoupons?: Coupon[];
}

StoreConfigModel

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

interface StoreConfigModel {
  displayMiniCart: boolean;
  miniCartMaxItemsDisplay: number;
  cartExpiresInDays: number;
  cartSummaryDisplayTotal: number;
  cartSummaryMaxItems: number;
  defaultCountry: string;
  categoryFixedProductTaxDisplaySetting: string;
  productFixedProductTaxDisplaySetting: string;
  salesFixedProductTaxDisplaySetting: string;
  shoppingCartDisplaySetting: {
    fullSummary: boolean;
    grandTotal: boolean;
    price: number | string;
    shipping: number | string;
    subtotal: number | string;
    taxGiftWrapping: number | string;
    zeroTax: boolean;
  };
  useConfigurableParentThumbnail: boolean;
  allowGiftWrappingOnOrder: boolean | null;
  allowGiftWrappingOnOrderItems: boolean | null;
  allowGiftMessageOnOrder: boolean | null;
  allowGiftMessageOnOrderItems: boolean | null;
  allowGiftReceipt: boolean;
  allowPrintedCard: boolean;
  printedCardPrice: Price;
  cartGiftWrapping: string;
  cartPrintedCard: string;
}

RawShippingMethodGraphQL

The raw GraphQL response structure with snake_case properties returned by the estimateShippingMethods mutation.

Returned by: getEstimateShipping.

interface RawShippingMethodGraphQL {
  amount: {
    currency: string;
    value: number;
  };
  carrier_code: string;
  method_code: string;
  error_message?: string;
  price_excl_tax: {
    currency: string;
    value: number;
  };
  price_incl_tax: {
    currency: string;
    value: number;
  };
}

ApplyCouponsStrategy

Strategy for how coupons should be applied to the cart:

• APPEND: Adds the specified coupons to any existing coupons already applied to the cart
• REPLACE: Removes all existing coupons and applies only the specified coupons

Used by: applyCouponsToCart.

enum ApplyCouponsStrategy {
    APPEND = "APPEND",
    REPLACE = "REPLACE"
}

EstimateAddressInput

Defines the address criteria for estimating shipping methods.

Used by: getEstimateShipping.

interface EstimateAddressInput {
    countryCode: string;
    postcode?: string;
    region?: {
        region?: string;
        code?: string;
        id?: number;
    };
}

EstimateAddressShippingInput

Defines the shipping address for calculating cart totals.

Used by: getEstimatedTotals.

interface EstimateAddressShippingInput {
    countryCode: string;
    postcode?: string;
    region?: {
        region?: string;
        id?: number;
    };
    shipping_method?: {
        carrier_code?: string;
        method_code?: string;
    };
}