Cart Data & Events

The Cart drop-in uses the event bus to emit and listen to events for communication between drop-ins and external integrations.

Version: 3.1.0

Events reference

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.
requisitionList/alert	Listens	Fired by Requisition List (requisitionList) when an alert or notification is triggered.
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

The following sections provide detailed information about each event, including its direction, event payload, and usage examples.

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.

Example

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

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

cart/initialized (emits)

Emitted when the component completes initialization.

Event payload

CartModel | null

See CartModel for full type definition.

Example

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

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

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.

Example

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

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

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.

Example

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

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

cart/product/removed (emits)

Emitted when an item is removed.

Event payload

Example

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

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

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.

Example

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

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

cart/reset (emits and listens)

Triggered when the component state is reset.

Event payload

Example

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

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

cart/updated (emits and listens)

Triggered when the component state is updated.

Event payload

CartModel | null

See CartModel for full type definition.

Example

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

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

checkout/initialized (listens)

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

Event payload

Cart | NegotiableQuote | null

See Cart, NegotiableQuote for full type definitions.

Example

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

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

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.

Example

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

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

requisitionList/alert (listens)

Fired by Requisition List (requisitionList) when an alert or notification is triggered.

Event payload

Example

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

events.on('requisitionList/alert', (payload) => {
  console.log('requisitionList/alert event received:', payload);
  // Add your custom logic here
});

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.

Example

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

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

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