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: 3.1.0

Function	Description
addProductsToCart	Adds products to a cart.
applyCouponsToCart	Applies or replaces one or more coupons to the cart.
applyGiftCardToCart	Apply a gift card to the current shopping cart.
createGuestCart	Creates a new empty cart for a guest user.
getCartData	Is mainly used internally by the initializeCart() and refreshCart() functions.
getCountries	API function for the drop-in..
getEstimatedTotals	Returns estimated totals for cart based on an address.
getEstimateShipping	Returns the first available shipping method and its estimated cost, based on the provided address.
getRegions	API function for the drop-in..
getStoreConfig	Returns information about a store’s configuration.
initializeCart	Initializes a guest or customer cart.
publishShoppingCartViewEvent	Publishes a shopping cart view event to the ACDL.
refreshCart	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	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 product identifier (SKU) to add to the cart. 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).
parentSku	string	No	For configurable products, this is the SKU of the parent (base) product. For example, if adding a specific variant like `MS09-M-Blue` (child SKU), the `parentSku` would be `MS09` (the base configurable product). This helps Commerce track the relationship between the variant and its parent product.
quantity	number	Yes	The number of items to add to the cart. For example, `1` to add a single item, or `3` to add three units of the product. 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 define which product variant the customer wants. For example, if a customer selects **Medium** and **Blue** for a configurable shirt, you would include the UIDs for those specific options. Use the product query to retrieve available option UIDs for a product.
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). For example, if a product offers monogram personalization, you would provide the field’s UID and the customer’s text like `{ uid: ‘Y3VzdG9tLW9wdGlvbi8x’, value: ‘ABC’ }`.
customFields	Record<string, any>	No	An optional object for passing additional custom data or attributes to associate with the cart item. This can include any key-value pairs needed for your implementation, such as gift messages, special handling instructions, or custom metadata. The structure and usage of this field depends on your Commerce backend configuration and any custom extensions you have installed.

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. The function calls the applyCouponsToCart mutation.

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`](#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. The function calls the applyGiftCardToCart mutation.

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>

Events

Does not emit any drop-in events.

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>

Events

Does not emit any drop-in events.

Returns

Returns CartModel or null.

getCountries

const getCountries = async (): Promise<[CountryData]>

Events

Does not emit any drop-in events.

Returns

Returns [CountryData].

getEstimatedTotals

A function that returns estimated totals for cart based on an address. It takes an address parameter. The function calls the estimateTotals mutation.

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`](#estimateaddressshippinginput).

Events

Does not emit any drop-in events.

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`](#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.

getRegions

const getRegions = async (
  countryId: string
): Promise<Array<{ code: string; name: string }>>

Parameter	Type	Req?	Description
countryId	string	Yes	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns Array<{ code: string; name: string }>.

getStoreConfig

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

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

Events

Does not emit any drop-in events.

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. The function calls the mergeCarts mutation.

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

Does not emit any drop-in 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>

Events

Does not emit any drop-in events.

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