Cart initialization

The Cart initializer configures how the cart manages shopping cart data, including items, pricing, discounts, and customer information. Use initialization to customize cart behavior, enable guest cart features, and transform cart data models to match your storefront requirements.

Version: 1.5.1

Configuration options

The following table describes the configuration options available for the Cart initializer:

Parameter	Type	Req?	Description
langDefinitions	LangDefinitions	No	Language definitions for internationalization (i18n). Override dictionary keys for localization or branding.
models	Record<string, any>	No	Custom data models for type transformations. Extend or modify default models with custom fields and transformers.
disableGuestCart	boolean	No	When set to `true`, prevents guest users from creating or accessing shopping carts, requiring authentication before cart operations.

Basic initialization

Initialize the drop-in with default settings:

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-cart';

await initializers.mountImmediately(initialize, {});

Language definitions

Override dictionary keys for localization or branding. The langDefinitions object maps locale keys to custom strings that override the drop-in’s default text.

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-cart';

const customStrings = {
  'AddToCart': 'Add to Bag',
  'Checkout': 'Complete Purchase',
  'Price': 'Cost',
};

const langDefinitions = {
  default: customStrings,
};

await initializers.mountImmediately(initialize, { langDefinitions });

Tip

For complete dictionary customization including all available keys and multi-language support, see the Cart Dictionary page.

Customizing data models

Extend or transform data models by providing custom transformer functions. Use the models option to add custom fields or modify existing data structures returned from the backend.

Available models

The following models can be customized through the models configuration option:

Model	Description
CartModel	Transforms cart data from GraphQL including items, totals, discounts, taxes, gift options, addresses, and payment methods. Use this to add custom fields or modify existing cart data structures.

The following example shows how to customize the CartModel model for the Cart drop-in:

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-cart';

const models = {
  CartModel: {
    transformer: (data) => ({
      // Add custom fields from backend data
      customField: data?.custom_field,
      promotionBadge: data?.promotion?.label,
      // Transform existing fields
      displayPrice: data?.price?.value ? `$${data.price.value}` : 'N/A',
    }),
  },
};

await initializers.mountImmediately(initialize, { models });

Drop-in-specific configuration

The Cart drop-in provides additional configuration options beyond the standard langDefinitions and models. These options customize drop-in-specific behaviors and features.

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-cart';

await initializers.mountImmediately(initialize, {
  // Drop-in-specific configuration
  disableGuestCart: true,
});

Note

Refer to the Configuration options table for descriptions of each option.

Configuration types

The following TypeScript definitions show the structure of each configuration object:

langDefinitions

Maps locale identifiers to dictionaries of key-value pairs. The default locale is used as the fallback when no specific locale matches. Each dictionary key corresponds to a text string used in the drop-in UI.

langDefinitions?: {
  [locale: string]: {
    [key: string]: string;
  };
};

models

Maps model names to transformer functions. Each transformer receives data from GraphQL and returns a modified or extended version. Use the Model<T> type from @dropins/tools to create type-safe transformers.

models?: {
  [modelName: string]: Model<any>;
};

Model definitions

The following TypeScript definitions show the structure of each customizable model:

CartModel

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