Cart Data & Events

The Cart drop-in emits events when items are added, removed, or updated, and listens to checkout events to maintain synchronization across your storefront.

Version: 1.5.1

Tip

For information about event architecture, subscription patterns, and best practices, see the Events guide.

Events reference

Drop-ins communicate via the event bus.

Event	Direction	Description
cart/initialized	Emits	Emitted when the component completes initialization.
cart/product/added	Emits	Emitted when an item is added.
cart/product/removed	Emits	Emitted when an item is removed.
cart/product/updated	Emits	Emitted when the component state is updated.
checkout/initialized	Listens	Fired by Checkout (checkout) when the component completes initialization.
checkout/updated	Listens	Fired by Checkout (checkout) when the component state is updated.
companyContext/changed	Listens	Fired by Company Context (companyContext) when a change occurs.
cart/data	Emits and listens	Triggered when data is available or changes.
cart/merged	Emits and listens	Triggered when data is merged.
cart/reset	Emits and listens	Triggered when the component state is reset.
cart/updated	Emits and listens	Triggered when the component state is updated.
shipping/estimate	Emits and listens	Triggered when an estimate is calculated.

Event details

cart/data (emits and listens)

Emitted when cart data is available or changes. This event is triggered during cart initialization and updates to provide the current cart state.

Event payload

CartModel | null

See CartModel for full type definition.

Usage

import { events } from '@dropins/tools/event-bus.js';

const cartDataListener = events.on('cart/data', (data) => {
  console.log('cart/data event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
cartDataListener.off();

cart/initialized (emits)

Emitted when the component completes initialization.

Event payload

CartModel | null

See CartModel for full type definition.

Usage

import { events } from '@dropins/tools/event-bus.js';

const cartInitializedListener = events.on('cart/initialized', (data) => {
  console.log('cart/initialized event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
cartInitializedListener.off();

cart/merged (emits and listens)

Emitted when a guest cart is merged with a customer cart after login. This typically happens when an unauthenticated user adds items to their cart, then signs in, and their guest cart items are combined with any existing items in their customer cart.

Event payload

{
  oldCartItems: Item[] | null;
  newCart: CartModel | null;
}

See Item, CartModel for full type definitions.

Usage

import { events } from '@dropins/tools/event-bus.js';

const cartMergedListener = events.on('cart/merged', (data) => {
  console.log('cart/merged event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
cartMergedListener.off();

cart/product/added (emits)

Emitted when new products are added to the cart. This event fires for genuinely new items, not quantity updates of existing items.

Event payload

Item[] | null

See Item for full type definition.

Usage

import { events } from '@dropins/tools/event-bus.js';

const cartProductAddedListener = events.on('cart/product/added', (data) => {
  console.log('cart/product/added event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
cartProductAddedListener.off();

cart/product/removed (emits)

Emitted when an item is removed.

Event payload

Usage

import { events } from '@dropins/tools/event-bus.js';

const cartProductRemovedListener = events.on('cart/product/removed', (data) => {
  console.log('cart/product/removed event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
cartProductRemovedListener.off();

cart/product/updated (emits)

Emitted when the quantity of existing cart items is increased. This event fires when adding more of a product that’s already in the cart, as opposed to adding a brand new product.

Event payload

Item[] | null

See Item for full type definition.

Usage

import { events } from '@dropins/tools/event-bus.js';

const cartProductUpdatedListener = events.on('cart/product/updated', (data) => {
  console.log('cart/product/updated event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
cartProductUpdatedListener.off();

cart/reset (emits and listens)

Triggered when the component state is reset.

Event payload

void

Usage

import { events } from '@dropins/tools/event-bus.js';

const cartResetListener = events.on('cart/reset', (data) => {
  console.log('cart/reset event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
cartResetListener.off();

cart/updated (emits and listens)

Triggered when the component state is updated.

Event payload

CartModel | null

See CartModel for full type definition.

Usage

import { events } from '@dropins/tools/event-bus.js';

const cartUpdatedListener = events.on('cart/updated', (data) => {
  console.log('cart/updated event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
cartUpdatedListener.off();

checkout/initialized (listens)

Fired by Checkout (checkout) when the component completes initialization.

Event payload

Cart | NegotiableQuote | null

See Cart, NegotiableQuote for full type definitions.

Usage

import { events } from '@dropins/tools/event-bus.js';

const checkoutInitializedListener = events.on('checkout/initialized', (data) => {
  console.log('checkout/initialized event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
checkoutInitializedListener.off();

checkout/updated (listens)

Fired by Checkout (checkout) when the component state is updated.

Event payload

Cart | NegotiableQuote | null

See Cart, NegotiableQuote for full type definitions.

Usage

import { events } from '@dropins/tools/event-bus.js';

const checkoutUpdatedListener = events.on('checkout/updated', (data) => {
  console.log('checkout/updated event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
checkoutUpdatedListener.off();

companyContext/changed (listens)

Fired by Company Context (companyContext) when a change occurs.

Event payload

Usage

import { events } from '@dropins/tools/event-bus.js';

const companyContextChangedListener = events.on('companyContext/changed', (data) => {
  console.log('companyContext/changed event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
companyContextChangedListener.off();

shipping/estimate (emits and listens)

Emitted when shipping cost estimates are calculated for a given address. This event provides both the address used for estimation and the resulting shipping method with its cost.

Event payload

{
  address: PartialAddress;
  shippingMethod: ShippingMethod | null;
}

See PartialAddress, ShippingMethod for full type definitions.

Usage

import { events } from '@dropins/tools/event-bus.js';

const shippingEstimateListener = events.on('shipping/estimate', (data) => {
  console.log('shipping/estimate event received:', data);
  // Add your custom logic here
});

// Later, when you want to stop listening
shippingEstimateListener.off();

Data Models

The following data models are used in event payloads for this drop-in.

CartModel

The CartModel represents the complete state of a shopping cart, including items, pricing, discounts, shipping estimates, and gift options.

Used in: cart/data, cart/initialized, cart/merged, cart/updated.

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

Item

The Item interface represents a single product in the cart, including product details, pricing, quantity, customization options, and inventory status.

Used in: cart/merged, cart/product/added, cart/product/updated.

interface Item {
  giftWrappingAvailable: boolean;
  giftWrappingPrice: {
    currency: string;
    value: number;
  };
  productGiftWrapping: {
    uid: string;
    design: string;
    selected: boolean;
    image: WrappingImage;
    price: Price;
  }[];
  giftMessage: {
    recipientName: string;
    senderName: string;
    message: string;
  };
  priceTiers: PriceTier[];
  giftMessageAvailable: boolean | null;
  taxedPrice: Price;
  rowTotal: Price;
  rowTotalIncludingTax: Price;
  itemType: string;
  uid: string;
  url: ItemURL;
  canonicalUrl: string;
  categories: string[];
  quantity: number;
  sku: string;
  topLevelSku: string;
  name: string;
  image: ItemImage;
  links?: ItemLinks;
  price: Price;
  total: Price;
  discountedTotal?: Price;
  discount?: Price;
  regularPrice: Price;
  discounted: boolean;
  bundleOptions?: { [key: string]: any };
  bundleOptionsUIDs?: string[];
  selectedOptions?: { [key: string]: any };
  selectedOptionsUIDs?: { [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[];
}

PartialAddress

The PartialAddress interface represents a minimal address used for shipping estimates, containing country, postal code, and region information.

Used in: shipping/estimate.

interface PartialAddress {
  countryCode: string;
  postCode?: string;
  region?: string;
  regionCode?: string;
  regionId?: number;
}

ShippingMethod

The ShippingMethod interface represents a shipping option with carrier and method codes, along with pricing information.

Used in: shipping/estimate.

interface ShippingMethod {
  carrierCode: string;
  methodCode: string;
  amountExclTax?: Price;
  amountInclTax?: Price;
}