Cart functions

The cart drop-in component provides API functions that allow developers to retrieve and display detailed cart information dynamically.

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.

export const addProductsToCart = async (
  items: {
    sku: string;
    parentSku?: string;
    quantity: number;
    optionsUIDs?: string[];
    enteredOptions?: { uid: string; value: string }[];
  }[]
): 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.

Returns

Returns a promise that resolves to a CartModel object or null. The CartModel object has the following shape:

export interface CartModel {
  id: string;
  totalQuantity: 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[];
}

interface TotalPriceModifier {
  amount: Price;
  label: string;
  coupon?: Coupon;
}

interface FixedProductTax {
  amount: Price;
  label: string;
}

export interface Item {
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  quantity: number;
  sku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  selectedOptions?: { [key: string]: any };
  customizableOptions?: { [key: string]: any };
  message?: string;
  recipient?: string;
  recipientEmail?: string;
  sender?: string;
  senderEmail?: string;
  lowInventory?: boolean;
  insufficientQuantity?: boolean;
  onlyXLeftInStock?: number | null;
  outOfStock?: boolean;
  notAvailableMessage?: string;
  stockLevel?: String;
  discountPercentage?: number;
  savingsAmount?: Price;
  productAttributes?: Attribute[];
  fixedProductTaxes?: FixedProductTax[];
}

interface ItemError {
  id: string;
  text: string;
}

interface ItemImage {
  src: string;
  alt: string;
}

export interface Price {
  value: number;
  currency: string;
}

interface ItemURL {
  urlKey: string;
  categories: string[];
}

interface ItemLinks {
  count: number;
  result: string;
}

interface AttributeOption {
  value: string;
  label: string;
}

interface Attribute {
  code: string;
  value?: string;
  selected_options?: AttributeOption[];
}

interface Coupon {
  code: string;
}

Events

The event bus emits the cart/updated and cart/data events with the CartModel as the data payload. It also publishes add-to-cart or remove-from-cart events to the Adobe Client Data Layer (ACDL).

Usage

To add a simple product to the cart:

addProductsToCart([
  {
    sku: 'VA19-GO-NA',
    quantity: 1,
  },
]);

To add a configurable product to the cart:

addProductsToCart([
  {
    sku: 'VSW01',
    quantity: 1,
    optionsUIDs: ['Y29uZmlndXJhYmxlLzE1Ny8zMQ==', 'Y29uZmlndXJhYmxlLzE5MC80NA=='],
  },
]);

applyCouponsToCart

The applyCouponsToCart function applies one or more predefined coupon codes to the specified cart. Any previously applied coupons are replaced. The function calls the applyCouponsToCart mutation.

export 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	Indicates whether the specified coupons replace (REPLACE) or are added (APPEND) to any previously applied coupons.

Returns

Returns a promise that resolves to a CartModel object or null. The CartModel object has the following shape:

export interface CartModel {
  id: string;
  totalQuantity: 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[];
}

interface TotalPriceModifier {
  amount: Price;
  label: string;
  coupon?: Coupon;
}

interface FixedProductTax {
  amount: Price;
  label: string;
}

export interface Item {
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  quantity: number;
  sku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  selectedOptions?: { [key: string]: any };
  customizableOptions?: { [key: string]: any };
  message?: string;
  recipient?: string;
  recipientEmail?: string;
  sender?: string;
  senderEmail?: string;
  lowInventory?: boolean;
  insufficientQuantity?: boolean;
  onlyXLeftInStock?: number | null;
  outOfStock?: boolean;
  notAvailableMessage?: string;
  stockLevel?: String;
  discountPercentage?: number;
  savingsAmount?: Price;
  productAttributes?: Attribute[];
  fixedProductTaxes?: FixedProductTax[];
}

interface ItemError {
  id: string;
  text: string;
}

interface ItemImage {
  src: string;
  alt: string;
}

export interface Price {
  value: number;
  currency: string;
}

interface ItemURL {
  urlKey: string;
  categories: string[];
}

interface ItemLinks {
  count: number;
  result: string;
}

interface AttributeOption {
  value: string;
  label: string;
}

interface Attribute {
  code: string;
  value?: string;
  selected_options?: AttributeOption[];
}

interface Coupon {
  code: string;
}

Events

The event bus emits the cart/updated and cart/data events with the CartModel as the data payload.

Usage

To apply a single coupon, replacing any existing coupons in the cart:

import { applyCouponsToCart } from '@/cart/api/applyCouponsToCart';

applyCouponsToCart(['COUPON1'], 'REPLACE');

To apply multiple coupons to the cart:

import { applyCouponsToCart } from '@/cart/api/applyCouponsToCart';

applyCouponsToCart(['COUPON1', 'COUPON2', 'COUPON3'], 'APPEND');

applyCouponsToCart

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

import { applyCouponsToCart } from '@/cart/api/applyCouponsToCart';

applyCouponsToCart(Array<string>);

Apply or replace a single coupon to the cart:

applyCouponsToCart(['COUPON1']);

Apply or replace multiple coupons to the cart:

applyCouponsToCart(['COUPON1', 'COUPON2', 'COUPON3']);

Here’s the shape of the data returned from the applyCouponsToCart function:

type CartModel = {
  id: string;
  totalQuantity: 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[];
};

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.

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

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

Returns

Returns a promise that resolves to a CartModel object or null. The CartModel object has the following shape:

export interface CartModel {
  id: string;
  totalQuantity: 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[];
}

interface TotalPriceModifier {
  amount: Price;
  label: string;
  coupon?: Coupon;
}

interface FixedProductTax {
  amount: Price;
  label: string;
}

export interface Item {
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  quantity: number;
  sku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  selectedOptions?: { [key: string]: any };
  customizableOptions?: { [key: string]: any };
  message?: string;
  recipient?: string;
  recipientEmail?: string;
  sender?: string;
  senderEmail?: string;
  lowInventory?: boolean;
  insufficientQuantity?: boolean;
  onlyXLeftInStock?: number | null;
  outOfStock?: boolean;
  notAvailableMessage?: string;
  stockLevel?: String;
  discountPercentage?: number;
  savingsAmount?: Price;
  productAttributes?: Attribute[];
  fixedProductTaxes?: FixedProductTax[];
}

interface ItemError {
  id: string;
  text: string;
}

interface ItemImage {
  src: string;
  alt: string;
}

export interface Price {
  value: number;
  currency: string;
}

interface ItemURL {
  urlKey: string;
  categories: string[];
}

interface ItemLinks {
  count: number;
  result: string;
}

interface AttributeOption {
  value: string;
  label: string;
}

interface Attribute {
  code: string;
  value?: string;
  selected_options?: AttributeOption[];
}

interface Coupon {
  code: string;
}

Events

This function emits the cart/updated and cart/data events. It also publishes add-to-cart or remove-from-cart events to the Adobe Client Data Layer (ACDL).

Usage

import { applyGiftCardToCart } from '@/cart/api/applyGiftCardToCart';

applyGiftCardToCart(giftCardCode: string);

createEmptyCart

The createEmptyCart function creates an empty shopping cart for a guest or logged in customer. It returns a cart ID. The function calls the createEmptyCart mutation.

export const createEmptyCart = async();

Returns

The data returned is a new empty cart ID as a string:

type EmptyCartId = string;

If guest carts have been disabled from the Admin, the function returns an error.

Usage

To create an empty cart:

import { createEmptyCart } from '@/cart/api/createEmptyCart';

createEmptyCart();

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.

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

Returns

Returns a promise that resolves to a CartModel object or null. The CartModel object has the following shape:

export interface CartModel {
  id: string;
  totalQuantity: 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[];
}

interface TotalPriceModifier {
  amount: Price;
  label: string;
  coupon?: Coupon;
}

interface FixedProductTax {
  amount: Price;
  label: string;
}

export interface Item {
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  quantity: number;
  sku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  selectedOptions?: { [key: string]: any };
  customizableOptions?: { [key: string]: any };
  message?: string;
  recipient?: string;
  recipientEmail?: string;
  sender?: string;
  senderEmail?: string;
  lowInventory?: boolean;
  insufficientQuantity?: boolean;
  onlyXLeftInStock?: number | null;
  outOfStock?: boolean;
  notAvailableMessage?: string;
  stockLevel?: String;
  discountPercentage?: number;
  savingsAmount?: Price;
  productAttributes?: Attribute[];
  fixedProductTaxes?: FixedProductTax[];
}

interface ItemError {
  id: string;
  text: string;
}

interface ItemImage {
  src: string;
  alt: string;
}

export interface Price {
  value: number;
  currency: string;
}

interface ItemURL {
  urlKey: string;
  categories: string[];
}

interface ItemLinks {
  count: number;
  result: string;
}

interface AttributeOption {
  value: string;
  label: string;
}

interface Attribute {
  code: string;
  value?: string;
  selected_options?: AttributeOption[];
}

interface Coupon {
  code: string;
}

Usage

To get detailed information about the user’s shopping cart:

import { getCartData } from '@/cart/api/getCartData';

getCartData();

getEstimatedTotals

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

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

Parameter	Type	Req?	Description
address	EstimateAddressShippingInput	Yes	Defines the shipping address for the estimate.

The EstimateAddressShippingInput object has the following parameters:

Parameter	Type	Req?	Description
countryCode	string	Yes	The two-letter code representing the user's country.
postcode	string	No	The user's ZIP or postal code.
region	object	No	An object containing the region name, region code, and region ID.
region.region	string	No	The state or province name.
region.id	number	No	The unique ID for a pre-defined region.
shipping_method	object	No	Defines the shipping carrier and method.
shipping_method.carrier_code	string	No	A string that identifies a commercial carrier or an offline delivery method.
shipping_method.method_code	string	No	A string that indicates which service a commercial carrier will use to ship items.

Returns

Returns a promise that resolves to a CartModel object or null. The CartModel object has the following shape:

export interface CartModel {
  id: string;
  totalQuantity: 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[];
}

interface TotalPriceModifier {
  amount: Price;
  label: string;
  coupon?: Coupon;
}

interface FixedProductTax {
  amount: Price;
  label: string;
}

export interface Item {
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  quantity: number;
  sku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  selectedOptions?: { [key: string]: any };
  customizableOptions?: { [key: string]: any };
  message?: string;
  recipient?: string;
  recipientEmail?: string;
  sender?: string;
  senderEmail?: string;
  lowInventory?: boolean;
  insufficientQuantity?: boolean;
  onlyXLeftInStock?: number | null;
  outOfStock?: boolean;
  notAvailableMessage?: string;
  stockLevel?: String;
  discountPercentage?: number;
  savingsAmount?: Price;
  productAttributes?: Attribute[];
  fixedProductTaxes?: FixedProductTax[];
}

interface ItemError {
  id: string;
  text: string;
}

interface ItemImage {
  src: string;
  alt: string;
}

export interface Price {
  value: number;
  currency: string;
}

interface ItemURL {
  urlKey: string;
  categories: string[];
}

interface ItemLinks {
  count: number;
  result: string;
}

interface AttributeOption {
  value: string;
  label: string;
}

interface Attribute {
  code: string;
  value?: string;
  selected_options?: AttributeOption[];
}

interface Coupon {
  code: string;
}

Usage

To get estimated totals for the cart based on an address:

import { getEstimatedTotals } from '@/cart/api/getEstimatedTotals';

getEstimatedTotals([
  {
    address: {
      countryCode: string,
      postcode?: string,
      region?: {
        region?: string,
        code?: string,
        id?: number,
      }
    }
  }
]);

Here’s the shape of the data returned from the getEstimatedTotals function:

type EstimatedTotals = {
  cartId: string;
  address: {
    countryCode: string;
    postcode?: string;
    region?: {
      region?: string;
      code?: string;
      id?: number;
    };
  };
  shippingMethod: {
    carrierCode: string;
    methodCode: string;
  };
};

getEstimateShipping

The getEstimateShipping function returns a list of shipping methods and the estimated shipping costs, based on the country ID. The function calls the estimateShippingMethods mutation.

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

Parameter	Type	Req?	Description
address	EstimateAddressInput	No	Defines the shipping address for the estimate.

The EstimateAddressInput object has the following parameters:

Parameter	Type	Req?	Description
countryCode	string	Yes	The two-letter code representing the user's country.
postcode	string	No	The user's ZIP or postal code.
region	object	No	An object containing the region name, region code, and region ID.
region.region	string	No	The state or province name.
region.code	string	No	The address region code.
region.id	number	No	The unique ID for a pre-defined region.

Returns

Returns a promise that contains shipping data or null. The EstimatedShipping object has the following shape:

type EstimatedShipping = {
  cartId: string;
  address: {
    countryCode: string;
    postcode?: string;
    region?: {
      region?: string;
      code?: string;
      id?: number;
    };
  };
  shippingMethod: {
    carrierCode: string;
    methodCode: string;
  };
};

Events

The event bus emits the shipping/estimate event, which contains data about the address and shipping method.

Usage

To get an estimate of the shipping costs:

import { getEstimateShipping } from '@/cart/api/getEstimateShipping';

getEstimateShipping({
  countryCode: 'US',
  region: {
    code: 'NY',
  },
});

getStoreConfig

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

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

Returns

Returns a promise that resolves to a StoreConfigModel object or null. The StoreConfigModel object has the following shape:

type StoreConfigModel = {
  displayMiniCart: boolean;
  miniCartMaxItemsDisplay: number;
  cartExpiresInDays: number;
  cartSummaryDisplayTotal: number;
  defaultCountry: string;
  categoryFixedProductTaxDisplaySetting: string;
  productFixedProductTaxDisplaySetting: string;
  salesFixedProductTaxDisplaySetting: string;
  shoppingCartDisplaySetting: {
    fullSummary: boolean;
    grandTotal: boolean;
    price: number | string;
    shipping: number | string;
    subtotal: number | string;
    taxGiftWrapping: string;
    zeroTax: boolean;
  };
};

Usage

To get cart-related configuration values:

import { getStoreConfig } from '@/cart/api/getStoreConfig';

getStoreConfig();

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. It also emits the cart/initialized and cart/data events.

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

Returns

Returns a promise that resolves to a CartModel object or null. The CartModel object has the following shape:

export interface CartModel {
  id: string;
  totalQuantity: 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[];
}

interface TotalPriceModifier {
  amount: Price;
  label: string;
  coupon?: Coupon;
}

interface FixedProductTax {
  amount: Price;
  label: string;
}

export interface Item {
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  quantity: number;
  sku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  selectedOptions?: { [key: string]: any };
  customizableOptions?: { [key: string]: any };
  message?: string;
  recipient?: string;
  recipientEmail?: string;
  sender?: string;
  senderEmail?: string;
  lowInventory?: boolean;
  insufficientQuantity?: boolean;
  onlyXLeftInStock?: number | null;
  outOfStock?: boolean;
  notAvailableMessage?: string;
  stockLevel?: String;
  discountPercentage?: number;
  savingsAmount?: Price;
  productAttributes?: Attribute[];
  fixedProductTaxes?: FixedProductTax[];
}

interface ItemError {
  id: string;
  text: string;
}

interface ItemImage {
  src: string;
  alt: string;
}

export interface Price {
  value: number;
  currency: string;
}

interface ItemURL {
  urlKey: string;
  categories: string[];
}

interface ItemLinks {
  count: number;
  result: string;
}

interface AttributeOption {
  value: string;
  label: string;
}

interface Attribute {
  code: string;
  value?: string;
  selected_options?: AttributeOption[];
}

interface Coupon {
  code: string;
}

Events

The event bus emits the cart/initialized event and the cart/data event, which contains data about the address and shipping method.

Usage

To initialize a cart:

import { initializeCart } from '@/cart/api/initializeCart';

initializeCart();

refreshCart

The refreshCart function refreshes the cart data.

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

Returns

Returns a promise that resolves to a CartModel object or null. The CartModel object has the following shape:

export interface CartModel {
  id: string;
  totalQuantity: 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[];
}

interface TotalPriceModifier {
  amount: Price;
  label: string;
  coupon?: Coupon;
}

interface FixedProductTax {
  amount: Price;
  label: string;
}

export interface Item {
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  quantity: number;
  sku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  selectedOptions?: { [key: string]: any };
  customizableOptions?: { [key: string]: any };
  message?: string;
  recipient?: string;
  recipientEmail?: string;
  sender?: string;
  senderEmail?: string;
  lowInventory?: boolean;
  insufficientQuantity?: boolean;
  onlyXLeftInStock?: number | null;
  outOfStock?: boolean;
  notAvailableMessage?: string;
  stockLevel?: String;
  discountPercentage?: number;
  savingsAmount?: Price;
  productAttributes?: Attribute[];
  fixedProductTaxes?: FixedProductTax[];
}

interface ItemError {
  id: string;
  text: string;
}

interface ItemImage {
  src: string;
  alt: string;
}

export interface Price {
  value: number;
  currency: string;
}

interface ItemURL {
  urlKey: string;
  categories: string[];
}

interface ItemLinks {
  count: number;
  result: string;
}

interface AttributeOption {
  value: string;
  label: string;
}

interface Attribute {
  code: string;
  value?: string;
  selected_options?: AttributeOption[];
}

interface Coupon {
  code: string;
}

Events

The event bus emits the cart/updated and cart/data events.

Usage

To refresh the cart data:

import { refreshCart } from '@/cart/api/refreshCart';

refreshCart();

removeGiftCardFromCart

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

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

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

Returns

Returns a promise that resolves to a CartModel object or null. The CartModel object has the following shape:

export interface CartModel {
  id: string;
  totalQuantity: 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[];
}

interface TotalPriceModifier {
  amount: Price;
  label: string;
  coupon?: Coupon;
}

interface FixedProductTax {
  amount: Price;
  label: string;
}

export interface Item {
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  quantity: number;
  sku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  selectedOptions?: { [key: string]: any };
  customizableOptions?: { [key: string]: any };
  message?: string;
  recipient?: string;
  recipientEmail?: string;
  sender?: string;
  senderEmail?: string;
  lowInventory?: boolean;
  insufficientQuantity?: boolean;
  onlyXLeftInStock?: number | null;
  outOfStock?: boolean;
  notAvailableMessage?: string;
  stockLevel?: String;
  discountPercentage?: number;
  savingsAmount?: Price;
  productAttributes?: Attribute[];
  fixedProductTaxes?: FixedProductTax[];
}

interface ItemError {
  id: string;
  text: string;
}

interface ItemImage {
  src: string;
  alt: string;
}

export interface Price {
  value: number;
  currency: string;
}

interface ItemURL {
  urlKey: string;
  categories: string[];
}

interface ItemLinks {
  count: number;
  result: string;
}

interface AttributeOption {
  value: string;
  label: string;
}

interface Attribute {
  code: string;
  value?: string;
  selected_options?: AttributeOption[];
}

interface Coupon {
  code: string;
}

Events

The event bus emits the cart/updated and cart/data events.

Usage

To remove a gift card from the cart:

import { removeGiftCardFromCart } from '@/cart/api/removeGiftCardFromCart';

removeGiftCardFromCart(giftCardCode: string);

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.

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

Returns

Returns a promise that resolves to a CartModel object or null. The CartModel object has the following shape:

export interface CartModel {
  id: string;
  totalQuantity: 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[];
}

interface TotalPriceModifier {
  amount: Price;
  label: string;
  coupon?: Coupon;
}

interface FixedProductTax {
  amount: Price;
  label: string;
}

export interface Item {
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  quantity: number;
  sku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  selectedOptions?: { [key: string]: any };
  customizableOptions?: { [key: string]: any };
  message?: string;
  recipient?: string;
  recipientEmail?: string;
  sender?: string;
  senderEmail?: string;
  lowInventory?: boolean;
  insufficientQuantity?: boolean;
  onlyXLeftInStock?: number | null;
  outOfStock?: boolean;
  notAvailableMessage?: string;
  stockLevel?: String;
  discountPercentage?: number;
  savingsAmount?: Price;
  productAttributes?: Attribute[];
  fixedProductTaxes?: FixedProductTax[];
}

interface ItemError {
  id: string;
  text: string;
}

interface ItemImage {
  src: string;
  alt: string;
}

export interface Price {
  value: number;
  currency: string;
}

interface ItemURL {
  urlKey: string;
  categories: string[];
}

interface ItemLinks {
  count: number;
  result: string;
}

interface AttributeOption {
  value: string;
  label: string;
}

interface Attribute {
  code: string;
  value?: string;
  selected_options?: AttributeOption[];
}

interface Coupon {
  code: string;
}

Usage

To reset the cart:

import { resetCart } from '@/cart/api/resetCart';

resetCart();

setGiftOptionsOnCart

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

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

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

The GiftFormDataType object has the following parameters:

Parameter	Type	Req?	Description
giftReceiptIncluded	boolean	No	Indicates if a gift receipt is included.
printedCardIncluded	boolean	No	Indicates if a printed card is included.
isGiftWrappingSelected	boolean	No	Indicates if gift wrapping is selected.
recipientName	string	No	The name of the gift recipient.
senderName	string	No	The name of the gift sender.
message	string	No	A message to include with the gift.
giftWrappingId	string	No	The ID of the selected gift wrapping option.
itemId	string	No	The ID of the item being gifted.
giftWrappingOptions	GiftWrappingConfigProps[]	No	Available gift wrapping options.

The GiftWrappingConfigProps object has the following parameters:

Parameter	Type	Req?	Description
uid	string	No	The unique ID of the gift wrapping option.
design	string	No	Describes the pattern or design of the gift wrapping.
selected	boolean	No	Indicates whether the option is selected.
image	WrappingImage	No	An image of the gift wrapping option.
price	Price	No	The price

Returns

Returns a promise that resolves to a CartModel object or null. The CartModel object has the following shape:

export interface CartModel {
  id: string;
  totalQuantity: 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[];
}

interface TotalPriceModifier {
  amount: Price;
  label: string;
  coupon?: Coupon;
}

interface FixedProductTax {
  amount: Price;
  label: string;
}

export interface Item {
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  quantity: number;
  sku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  selectedOptions?: { [key: string]: any };
  customizableOptions?: { [key: string]: any };
  message?: string;
  recipient?: string;
  recipientEmail?: string;
  sender?: string;
  senderEmail?: string;
  lowInventory?: boolean;
  insufficientQuantity?: boolean;
  onlyXLeftInStock?: number | null;
  outOfStock?: boolean;
  notAvailableMessage?: string;
  stockLevel?: String;
  discountPercentage?: number;
  savingsAmount?: Price;
  productAttributes?: Attribute[];
  fixedProductTaxes?: FixedProductTax[];
}

interface ItemError {
  id: string;
  text: string;
}

interface ItemImage {
  src: string;
  alt: string;
}

export interface Price {
  value: number;
  currency: string;
}

interface ItemURL {
  urlKey: string;
  categories: string[];
}

interface ItemLinks {
  count: number;
  result: string;
}

interface AttributeOption {
  value: string;
  label: string;
}

interface Attribute {
  code: string;
  value?: string;
  selected_options?: AttributeOption[];
}

interface Coupon {
  code: string;
}

Events

The event bus emits the cart/updated and cart/data events.

Usage

import { setGiftOptionsOnCart } from '@/cart/api/setGiftOptionsOnCart';

setGiftOptionsOnCart(
  giftMessage: {
    from: string;
    to: string;
    message: string;
  };
  giftWrappingId: string;
  giftReceiptIncluded: boolean;
  printedCardIncluded: boolean;
);

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.

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

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

The UpdateProductsFromCart object has the following parameters:

Parameter	Type	Req?	Description
uid	string	Yes	The unique ID of an item in the cart.
quantity	number	Yes	The new quantity of the item.
giftOptions	object	No	Contains gift wrapping and gift message options.
giftOptions.gift_wrapping_id	0	No	The ID of the selected gift wrapping option.
giftOptions.gift_message	object	No	Contains the gift message details.
giftOptions.gift_message.from	string	No	The name of the gift sender.
giftOptions.gift_message.to	string	No	The name of the gift recipient.
giftOptions.gift_message.message	string	No	The message to include with the gift.
optionsUIDs	string[]	No	The selected options for the product, such as color or size, using the unique ID for an object.

Returns

Returns a promise that resolves to a CartModel object or null. The CartModel object has the following shape:

export interface CartModel {
  id: string;
  totalQuantity: 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[];
}

interface TotalPriceModifier {
  amount: Price;
  label: string;
  coupon?: Coupon;
}

interface FixedProductTax {
  amount: Price;
  label: string;
}

export interface Item {
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  quantity: number;
  sku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  selectedOptions?: { [key: string]: any };
  customizableOptions?: { [key: string]: any };
  message?: string;
  recipient?: string;
  recipientEmail?: string;
  sender?: string;
  senderEmail?: string;
  lowInventory?: boolean;
  insufficientQuantity?: boolean;
  onlyXLeftInStock?: number | null;
  outOfStock?: boolean;
  notAvailableMessage?: string;
  stockLevel?: String;
  discountPercentage?: number;
  savingsAmount?: Price;
  productAttributes?: Attribute[];
  fixedProductTaxes?: FixedProductTax[];
}

interface ItemError {
  id: string;
  text: string;
}

interface ItemImage {
  src: string;
  alt: string;
}

export interface Price {
  value: number;
  currency: string;
}

interface ItemURL {
  urlKey: string;
  categories: string[];
}

interface ItemLinks {
  count: number;
  result: string;
}

interface AttributeOption {
  value: string;
  label: string;
}

interface Attribute {
  code: string;
  value?: string;
  selected_options?: AttributeOption[];
}

interface Coupon {
  code: string;
}

Events

This function emits the cart/updated and cart/data events. It also publishes add-to-cart or remove-from-cart events to the Adobe Client Data Layer (ACDL).

Usage

To set the quantity of an item in the cart to 3.

import { updateProductsFromCart } from '@/cart/api/updateProductsFromCart';

updateProductsFromCart([
  {
    uid: 'VA19-GO-NA',
    quantity: 3,
  },
]);

To remove the item from the cart.

import { updateProductsFromCart } from '@/cart/api/updateProductsFromCart';

updateProductsFromCart([
  {
    uid: 'VA19-GO-NA',
    quantity: 0,
  },
]);

To update the item from the cart by replacing the cart item. By passing optionsUIDs, this function adds the product associated with the new optionsUIDs and removes the previous item with the same UID.

import { updateProductsFromCart } from '@/cart/api/updateProductsFromCart';

updateProductsFromCart([
  {
    sku: 'VT02-PE-M',
    uid: 'NTE1NDY=',
    quantity: 2,
    optionsUIDs: [
                'Y29uZmlndXJhYmxlLzE4MC8zMg==',
                'Y29uZmlndXJhYmxlLzE5MS80Mw==',
              ]
  },
]);