Checkout Data & Events

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

Version: 3.0.0-beta1

Events reference

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.
quote-management/quote-data	Listens	Fired by Quote-management (quote-management) when a specific condition or state change occurs.
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

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

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.

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

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

Fired by Cart (cart) when data is merged.

Event payload

{ oldCartItems: any[] }

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

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

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.

Example

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

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

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.

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 (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.

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

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.

Example

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

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

quote-management/quote-data (listens)

Fired by Quote-management (quote-management) when a specific condition or state change occurs.

Event payload

{
  quote: NegotiableQuoteModel;
  permissions: {
  requestQuote: boolean;
  editQuote: boolean;
  deleteQuote: boolean;
  checkoutQuote: boolean;
}
}

See NegotiableQuoteModel for full type definition.

Example

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

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

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.

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.

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 {
  type: '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 {
  type: 'quote';
  availablePaymentMethods?: PaymentMethod[];
  billingAddress?: Address;
  email?: string;
  isEmpty: boolean;
  isVirtual: boolean;
  name: string;
  selectedPaymentMethod?: PaymentMethod;
  shippingAddresses: ShippingAddress[];
  status: NegotiableQuoteStatus;
  uid: string;
}

NegotiableQuoteModel

Used in: quote-management/quote-data.

interface NegotiableQuoteModel {
  uid: string;
  name: string;
  createdAt: string;
  salesRepName: string;
  expirationDate: string;
  updatedAt: string;
  status: NegotiableQuoteStatus;
  buyer: {
    firstname: string;
    lastname: string;
  };
  templateName?: string;
  comments?: {
    uid: string;
    createdAt: string;
    author: {
      firstname: string;
      lastname: string;
    };
    text: string;
    attachments?: {
      name: string;
      url: string;
    }[];
  }[];
  history?: NegotiableQuoteHistoryEntry[];
  prices: {
    appliedDiscounts?: Discount[];
    appliedTaxes?: Tax[];
    discount?: Currency;
    grandTotal?: Currency;
    grandTotalExcludingTax?: Currency;
    shippingExcludingTax?: Currency;
    shippingIncludingTax?: Currency;
    subtotalExcludingTax?: Currency;
    subtotalIncludingTax?: Currency;
    subtotalWithDiscountExcludingTax?: Currency;
    totalTax?: Currency;
  };
  items: NegotiableQuoteCartItem[];
  shippingAddresses?: ShippingAddress[];
  canCheckout: boolean;
  canSendForReview: boolean;
}

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