Checkout Data & Events

The Checkout drop-in emits checkout state changes and listens to cart events, maintaining synchronization between the checkout flow and cart data throughout the order process.

Version: 2.1.0

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
checkout/values	Emits	Emitted when form or configuration values change.
cart/initialized	Listens	Fired by Cart (cart) when the component completes initialization.
cart/merged	Listens	Fired by Cart (cart) when data is merged.
cart/reset	Listens	Fired by Cart (cart) when the component state is reset.
cart/data	Emits and listens	Triggered when data is available or changes.
checkout/error	Emits and listens	Triggered when an error occurs.
checkout/initialized	Emits and listens	Triggered when the component completes initialization.
checkout/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)

Triggered when cart data is available or changes. This event provides the current cart state including items, totals, and addresses.

Event payload

Cart | null

See Cart 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 (listens)

Fired by Cart (cart) 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 (listens)

Fired by Cart (cart) when data is merged.

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/reset (listens)

Fired by Cart (cart) 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();

checkout/error (emits and listens)

Triggered when an error occurs during checkout operations such as address validation, payment processing, or order placement.

Event payload

CheckoutError

See CheckoutError for full type definition.

Usage

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

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

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

checkout/initialized (emits and listens)

Triggered when the checkout component completes initialization with either cart or negotiable quote data. This indicates the checkout is ready for user interaction.

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 (emits and listens)

Triggered when the checkout state is updated, such as when shipping methods are selected, addresses are entered, or payment methods are chosen.

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();

checkout/values (emits)

Emitted when form or configuration values change in the checkout. This event is useful for tracking user input, validating form fields, or synchronizing state across components.

Event payload

ValuesModel

See ValuesModel for full type definition.

Usage

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

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

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

shipping/estimate (emits and listens)

Triggered 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

ShippingEstimate

See ShippingEstimate for full type definition.

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.

Cart

The Cart interface represents a shopping cart including items, pricing, addresses, and shipping/payment methods.

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

interface Cart {
  availablePaymentMethods?: PaymentMethod[];
  billingAddress?: CartAddress;
  email?: string;
  id: string;
  isEmpty: boolean;
  isGuest: boolean;
  isVirtual: boolean;
  selectedPaymentMethod?: PaymentMethod;
  shippingAddresses: CartShippingAddress[];
}

CartModel

Used in: cart/initialized.

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

CheckoutError

Used in: checkout/error.

interface CheckoutError {
  /**
   * The primary, user-friendly error message. This should be safe to display
   * directly in the UI.
   * @example "Your card was declined."
   */
  message: string;

  /**
   * An optional, unique error code for programmatic handling. This allows the
   * ServerError component to show specific icons, links, or actions.
   * @example "payment_intent_declined"
   */
  code?: string;
}

NegotiableQuote

The NegotiableQuote interface represents a B2B negotiable quote, which functions similarly to a cart but includes additional negotiation features like price adjustments and approval workflows.

Used in: checkout/initialized, checkout/updated.

interface NegotiableQuote {
  availablePaymentMethods?: PaymentMethod[];
  billingAddress?: Address;
  email?: string;
  isEmpty: boolean;
  isVirtual: boolean;
  name: string;
  selectedPaymentMethod?: PaymentMethod;
  shippingAddresses: ShippingAddress[];
  status: NegotiableQuoteStatus;
  uid: string;
}

ShippingEstimate

Used in: shipping/estimate.

interface ShippingEstimate {
  address: PartialShippingAddress;
  availableShippingMethods?: ShippingMethod[];
  shippingMethod: ShippingEstimateShippingMethod | null;
  success?: boolean;
}

ValuesModel

Used in: checkout/values.

interface ValuesModel {
  email: string;
  isBillToShipping: boolean | undefined;
  selectedPaymentMethod: PaymentMethod | null;
  selectedShippingMethod: ShippingMethod | null;
}