Order initialization

The Order initializer configures how order data is managed and displayed, including order history, status tracking, and order details. Use initialization to customize order data structures and integrate order management features.

Version: 3.0.0-beta2

Configuration options

The following table describes the configuration options available for the Order 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.
orderRef	string	No	Pre-loads a specific order by its reference ID or order number. Useful for direct access to order details from email links or confirmation pages.
returnRef	string	No	Pre-loads a specific return request by its reference ID. Enables direct navigation to return request details and status tracking.
orderData	OrderDataModel | null	No	Injects initial order data on page load. Useful for server-side rendering or hydrating order details without an additional `GraphQL` request.
routeOrdersList	() => string	No

Default configuration

The initializer runs with these defaults when no configuration is provided:

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

// All configuration options are optional
await initializers.mountImmediately(initialize, {
  langDefinitions: {}, // Uses built-in English strings
  models: {}, // Uses default data models
  // Drop-in-specific defaults:
  // orderRef: undefined // See configuration options below
  // returnRef: undefined // See configuration options below
  // orderData: undefined // See configuration options below
  // routeOrdersList: undefined // See configuration options below
});

Language definitions

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

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

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 Order 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
OrderDataModel	Transforms order data from GraphQL including order details, items, shipping, billing, payment, and tracking information. Use this to add custom fields specific to your order management workflow.
CustomerOrdersReturnModel	Transforms CustomerOrdersReturnModel data from GraphQL.
RequestReturnModel	Transforms RequestReturnModel data from GraphQL.

The following example shows how to customize the OrderDataModel model for the Order drop-in:

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

const models = {
  OrderDataModel: {
    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 configuration

The Order initializer configures how order data is managed and displayed, including order history, status tracking, and order details. Use initialization to customize order data structures and integrate order management features.

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

await initializers.mountImmediately(initialize, {
  langDefinitions: {},
  models: {},
  orderRef: 'abc123',
  returnRef: 'abc123',
  orderData: {},
  routeOrdersList: 'value',
});

Note

Refer to the Configuration options table for detailed 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:

OrderDataModel

export type OrderDataModel = {
  giftReceiptIncluded: boolean;
  printedCardIncluded: boolean;
  giftWrappingOrder: {
    price: MoneyProps;
    uid: string;
  };
  placeholderImage?: string;
  returnNumber?: string;
  id: string;
  orderStatusChangeDate?: string;
  number: string;
  email: string;
  token?: string;
  status: string;
  isVirtual: boolean;
  totalQuantity: number;
  shippingMethod?: string;
  carrier?: string;
  orderDate: string;
  returns: OrdersReturnPropsModel[];
  discounts: { amount: MoneyProps; label: string }[];
  coupons: {
    code: string;
  }[];
  payments: {
    code: string;
    name: string;
  }[];
  shipping?: { code: string; amount: number; currency: string };
  shipments: ShipmentsModel[];
  items: OrderItemModel[];
  totalGiftCard: MoneyProps;
  grandTotal: MoneyProps;
  grandTotalExclTax: MoneyProps;
  totalShipping?: MoneyProps;
  subtotalExclTax: MoneyProps;
  subtotalInclTax: MoneyProps;
  totalTax: MoneyProps;
  shippingAddress: OrderAddressModel;
  totalGiftOptions: {
    giftWrappingForItems: MoneyProps;
    giftWrappingForItemsInclTax: MoneyProps;
    giftWrappingForOrder: MoneyProps;
    giftWrappingForOrderInclTax: MoneyProps;
    printedCard: MoneyProps;
    printedCardInclTax: MoneyProps;
  };
  billingAddress: OrderAddressModel;
  availableActions: AvailableActionsProps[];
  taxes: { amount: MoneyProps; rate: number; title: string }[];
  appliedGiftCards: {
    code: string;
    appliedBalance: MoneyProps;
  }[];
};

OrderItemProductModel

export type OrderItemProductModel = {
  onlyXLeftInStock?: number;
  priceRange?: {
    maximumPrice?: {
      regularPrice?: MoneyProps;
    };
  };
  uid: string;
  __typename: string;
  stockStatus?: string;
  canonicalUrl?: string;
  urlKey?: string;
  id: string;
  image?: string;
  imageAlt?: string;
  name: string;
  productType: string;
  sku: string;
  thumbnail: {
    url: string;
    label: string;
  };
  giftWrappingAvailable?: boolean;
};

OrderItemModel

export type OrderItemModel = {
  giftMessage: {
    senderName: string;
    recipientName: string;
    message: string;
  };
  giftWrappingPrice: MoneyProps;
  productGiftWrapping: {
    uid: string;
    design: string;
    selected: boolean;
    image: {
      url: string;
      label: string;
    };
    price: MoneyProps;
  }[];
  taxCalculations: {
    includeAndExcludeTax: {
      originalPrice: MoneyProps;
      baseOriginalPrice: MoneyProps;
      baseDiscountedPrice: MoneyProps;
      baseExcludingTax: MoneyProps;
    };
    excludeTax: {
      originalPrice: MoneyProps;
      baseOriginalPrice: MoneyProps;
      baseDiscountedPrice: MoneyProps;
      baseExcludingTax: MoneyProps;
    };
    includeTax: {
      singleItemPrice: MoneyProps;
      baseOriginalPrice: MoneyProps;
      baseDiscountedPrice: MoneyProps;
    };
  };
  productSalePrice: MoneyProps;
  status?: string;
  currentReturnOrderQuantity?: number;
  eligibleForReturn: boolean;
  productSku?: string;
  type?: string;
  discounted?: boolean;
  id: string;
  productName?: string;
  productUrlKey?: string;
  regularPrice?: MoneyProps;
  price: MoneyProps;
  product?: OrderItemProductModel;
  selectedOptions?: Array<{
    label: string;
    value: any;
  }>;
  thumbnail?: {
    label: string;
    url: string;
  };
  downloadableLinks: {
    count: number;
    result: string;
  } | null;
  prices: {
    priceIncludingTax: MoneyProps;
    originalPrice: MoneyProps;
    originalPriceIncludingTax: MoneyProps;
    price: MoneyProps;
    discounts: {
      label: string;
      amount: { value: number };
    }[];
  };
  itemPrices: {
    priceIncludingTax: MoneyProps;
    originalPrice: MoneyProps;
    originalPriceIncludingTax: MoneyProps;
    price: MoneyProps;
    discounts: {
      label: string;
      amount: { value: number };
    }[];
  };
  bundleOptions: Record<string, string> | null;
  totalInclTax: MoneyProps;
  priceInclTax: MoneyProps;
  total: MoneyProps;
  configurableOptions: Record<string, string | number | boolean> | undefined;
  giftCard?: {
    senderName: string;
    senderEmail: string;
    recipientEmail: string;
    recipientName: string;
    message: string;
  };
  quantityCanceled: number;
  quantityInvoiced: number;
  quantityOrdered: number;
  quantityRefunded: number;
  quantityReturned: number;
  quantityShipped: number;
  requestQuantity?: number;
  totalQuantity: number;
  returnableQuantity?: number;
  quantityReturnRequested: number;
};

CustomerOrdersReturnModel

export interface CustomerOrdersReturnModel {
  ordersReturn: OrdersReturnPropsModel[];
  pageInfo?: PageInfoProps;
}

RequestReturnModel

export interface RequestReturnModel {
  uid: string;
  number: string;
  status: string;
  createdAt: string;
}