Unified Data Model

The Unified Data Model covers several categories of eCommerce.

Core: fundamental elements like Identifiers, Money and Price models, Pagination, and Image models. These data types provide the foundation for more complex structures.

Product & Catalog: data types for listing and managing products. It includes data types for Products, Product Variants, Product Attributes, Product Reviews, Categories, and Facets. Each data type has its unique properties to capture diverse product information.

Cart & Checkout: models the shopping cart and checkout process. It includes data types for the Cart itself, Address, Coupons, and Line Items, all essential for a smooth checkout process.

Customer: data types for managing customer data. It includes data types for Customer, Customer Address, and Order. These data types allow businesses to capture and manage customer information

Core

SfId

export type SfId = string;

An SfId serves as a unique identifier for various entities in the data model. It's defined as a string type and it is used throughout the model for identifying products, categories, customers, orders, and more.

SfMoney

export interface SfMoney {
  currency: string;
  amount: number;
  precisionAmount: string;
}

The SfMoney interface is used to represent any monetary value in the system. It carries details about the currency, the amount, and a precisionAmount which is used to accurately represent values with more than two decimal places, ensuring precise financial calculations.

export interface SfDiscountablePrice {
  isDiscounted: boolean;
  regularPrice: SfMoney;
  value: SfMoney;
}

The SfDiscountablePrice interface is used to represent the price of a product. It not only contains the regular price of the product, but it also captures whether the product is currently discounted and what the discounted price is. If the product is not discounted, the value is the same as the regularPrice.

SfPagination

export interface SfPagination {
  currentPage: number;
  pageSize: Maybe<number>;
  totalResults: number;
  totalPages: number;
}

The SfPagination interface is a utility that's used to handle pagination of data. This is especially crucial in eCommerce environments where potentially thousands of products, categories, or reviews may need to be displayed. It captures the current page, the total number of results, the total number of pages, and the size of each page (number of results per page).

SfImage

export interface SfImage {
  alt: Maybe<string>;
  url: string;
}

The SfImage interface represents any image in the system. It not only contains the URL of the image, but also an optional alternative text (alt). This alt text serves a dual purpose: it not only enhances accessibility by providing a text alternative for the image, but also can improve SEO (Search Engine Optimization) of the platform.

SfCurrency

export type SfCurrency = string;

The SfCurrency interface represents currency ISO value. It's defined as a string type.

Product & Catalog

SfProduct

export interface SfProduct {
  id: SfId;
  sku: Maybe<string>;
  name: Maybe<string>;
  slug: string;
  description: Maybe<string>;
  price: Maybe<SfDiscountablePrice>;
  primaryImage: Maybe<SfImage>;
  gallery: SfImage[];
  rating: Maybe<{
    average: number;
    count: number;
  }>;
  variants: SfProductVariant[];
  attributes: SfAttribute[];
  /*
   * Maximum available quantity for product, null if unlimited
   */
  quantityLimit: Maybe<number>;
}

The SfProduct interface represents a product in the eCommerce system. It has a unique id and an optional sku (Stock Keeping Unit), which is a unique identifier that businesses use to track inventory. The name is the title of the product, while slug is a URL-friendly version of the product name. description contains details about the product.

The price is an instance of SfDiscountablePrice, which contains information about the product's regular and discounted prices. primaryImage and gallery store visual information about the product.

The rating object contains information about customer reviews, such as the average score and total count of reviews.

The variants array contains different versions of the product, like different sizes or colors. attributes are additional characteristics of the product, like material or weight.

SfAttribute

export interface SfAttribute {
  label: string;
  name: string;
  value: string;
  valueLabel: string;
}

The SfAttribute interface describes extra characteristics of a product or a product variant. This can include things like color, size, weight, material, and other properties that can differ between products. The name is a unique identifier, while label is a human-readable version of the name. value is the attribute's value and valueLabel is a human-readable version of the value.

SfProductVariant

export interface SfProductVariant {
  id: SfId;
  slug: string;
  sku: Maybe<string>;
  name: Maybe<string>;
  /*
   * Maximum available quantity for variant, null if unlimited
   */
  quantityLimit: Maybe<number>;
  attributes: SfAttribute[];
}

The SfProductVariant interface represents different versions of a product. For example, a shirt might have variants for each color and size. Each variant has a unique id and sku, along with a slug for URL-friendly naming. The name is the variant's title. quantityLimit shows how many units of the variant are currently available. attributes contain the variant's characteristics, like size and color.

SfProductCatalogItem

export interface SfProductCatalogItem {
  id: SfId;
  sku: Maybe<string>;
  name: Maybe<string>;
  slug: string;
  price: Maybe<SfDiscountablePrice>;
  primaryImage: Maybe<SfImage>;
  rating: Maybe<{
    average: number;
    count: number;
  }>;
}

The SfProductCatalogItem interface describes a concise view of a product as it appears in your eCommerce platform's catalog. This can be on category pages, search results, or any other product listing page. It carries essential product details that help customers understand a product at a glance without navigating to the product detail page.

The id is a unique identifier for each product, while the sku, or Stock Keeping Unit, is an optional, unique identifier often used in inventory management. Not all products may have this information available.

The name presents the title of the product as customers see it on the platform. This field is optional as there may be cases where a name is not available.

The slug is a URL-friendly version of the name. It is used to build SEO-friendly URLs for each product.

The price field showcases the listing price of the product. Captured by the SfDiscountablePrice interface, it provides the capacity to handle and display discounted prices.

The primaryImage is the main visual representation of the product shown in the listings. This is an optional field as there could be scenarios where an image is not available or yet to be uploaded.

Lastly, rating is an optional field providing information about the product's rating. If present, it offers an average rating value and the total count of reviews for the product. This information can be absent if the product has not yet received any reviews.

SfProductReview

export interface SfProductReview {
  id: SfId;
  title: Maybe<string>;
  text: Maybe<string>;
  rating: Maybe<number>;
  /*
   * Name of the reviewer (Full name or nickname)
   */
  reviewer: Maybe<string>;
  /*
   * Creation date in ISO 8601 format
   */
  createdAt: string;
}

The SfProductReview interface represents customer reviews for a product. Each review has a unique id, a title, and text containing the actual review content. The rating is the score given to the product by the reviewer. reviewer is the name of the person who wrote the review and createdAt is the date when the review was written.

SfCategory

export interface SfCategory {
  id: SfId;
  name: string;
  slug: string;
  subcategories: Maybe<SfCategory[]>;
  parentCategoryId: Maybe<SfId>;
}

The SfCategory interface represents a product category. Each category has a unique id, a name, and a slug for URL-friendly naming. Categories can also contain subcategories, and parentCategoryId allowing you to create a category hierarchy.

SfFacet

export enum SfFacetTypes {
  MULTI_SELECT = "MULTI_SELECT",
  SINGLE_SELECT = "SINGLE_SELECT",
}

export type SfFacetType = `${SfFacetTypes}`;

export interface SfFacet {
  label: string;
  name: string;
  values: SfFacetItem[];
  type: Maybe<SfFacetType | (string & Record<never, never>)>;
}

interface SfFacetItem {
  label: string;
  value: string;
  productCount: Maybe<number>;
}

The SfFacet interface represents a facet for filtering products. Each facet has a label and name, type and an array of values. Facets can represent many different product attributes, like color, size, brand, or price range. SfFacetTypes denotes the facet type, typically set as MULTI_SELECT or SINGLE_SELECT by default. Storefronts can utilize this information to accurately represent attributes. Each SfFacetItem has a label, value, and optionally a productCount, which shows how many products match this facet value. This is useful for creating faceted navigation in an eCommerce storefront.

Cart & Checkout

SfCart

export interface SfCart {
  appliedCoupons: SfCartCoupon[];
  customerEmail: Maybe<string>;
  id: SfId;
  lineItems: SfCartLineItem[];
  shippingAddress: Maybe<SfAddress>;
  shippingMethod: Maybe<SfShippingMethod>;
  subtotalDiscountedPrice: SfMoney;
  subtotalRegularPrice: SfMoney;
  totalCouponDiscounts: SfMoney;
  totalItems: number;
  totalPrice: SfMoney;
  totalShippingPrice: Maybe<SfMoney>;
  totalTax: SfMoney;
}

The SfCart interface represents a shopping cart in the eCommerce system. It contains information about the cart's id, the customer's shippingAddress, customerEmail, and any appliedCoupons.

lineItems are the actual products that the customer has added to the cart.

subtotalDiscountedPrice is the total price of all items after product-level discounts have been applied, while subtotalRegularPrice is the total price without any discounts. totalCouponDiscounts is the total discount amount received from applied coupons.

totalItems is the total number of unique items in the cart, totalPrice is the final price that the customer has to pay (after all discounts and including tax and shipping), totalShippingPrice is the cost of shipping, and totalTax is the amount of tax.

SfAddress

export interface SfAddress {
  address1: Maybe<string>;
  address2?: Maybe<string>;
  city: Maybe<string>;
  country: Maybe<string>;
  firstName: Maybe<string>;
  lastName: Maybe<string>;
  phoneNumber: Maybe<string>;
  postalCode: Maybe<string>;
  state: Maybe<string>;
  titleCode: Maybe<string>;
}

The SfAddress interface represents a physical address. This is used for shipping addresses in the SfCart interface. It includes fields for the person's name, phone number, country, city, state, postal code, and two fields for street address.

SfCustomerAddress

export interface SfCustomerAddress extends SfAddress {
  id: SfId;
}

The SfCustomerAddress interface extends the SfAddress interface and represents a customer's address in the Unified Data Model. It inherits all the properties from SfAddress and adds an additional property:

• id: Unique identifier for the customer address.

The SfCustomerAddress entity is specifically used to store and manage customer addresses within an eCommerce platform. It includes essential fields for capturing a physical address, such as street address, city, state, postal code, and country. Additionally, it includes fields for the person's name (first name and last name) and phone number, providing a complete representation of a customer's shipping address.

SfCreateAddressBody

export interface SfCreateAddressBody {
  address1: string;
  address2?: Maybe<string>;
  city: string;
  country: string;
  firstName: string;
  lastName: string;
  phoneNumber: string;
  postalCode: string;
  state: string;
  titleCode: string;
}

The SfCreateAddressBody interface defines the structure for an address that users are required to provide during checkout.

SfShippingMethod

export interface SfShippingMethod {
  description: Maybe<string>;
  estimatedDelivery: Maybe<string>;
  id: string;
  name: string;
  price: SfMoney;
}

The SfShippingMethod interface represents a shipping method in the Unified Data Model. It includes the following properties:

• description: A description or additional information about the shipping method. This field is optional and may contain details about the shipping service or any special terms related to the method.
• estimatedDelivery: An estimated delivery time or timeframe for the shipping method. This field is optional and provides customers with an approximate expectation of when their order will be delivered.
• id: Unique identifier for the shipping method.
• name: The name or title of the shipping method. This field contains a concise label representing the shipping option.
• price: The cost of the shipping method, represented as an SfMoney object. This includes the currency and the amount.

The SfShippingMethod entity allows businesses to define and manage various shipping options available to customers during the checkout process. Shipping methods may include standard shipping, express shipping, free shipping, or any other custom shipping options provided by the eCommerce platform.

SfCartCoupon

export interface SfCartCoupon {
  code: string;
  id: string;
  name: Maybe<string>;
}

The SfCartCoupon interface represents a coupon that has been applied to the cart. Each coupon has a unique id and a code that the customer enters. The name is a human-readable description of the coupon.

SfCartLineItem

export interface SfCartLineItem {
  attributes: SfAttribute[];
  id: SfId;
  productId: SfId;
  image: Maybe<SfImage>;
  name: Maybe<string>;
  quantity: number;
  sku: Maybe<string>;
  slug: string;
  totalPrice: Maybe<SfMoney>;
  unitPrice: Maybe<SfDiscountablePrice>;
  quantityLimit: Maybe<number>;
}

The SfCartLineItem interface represents a product that a customer has added to their cart. It includes information about the product's id, sku, name, slug, and any attributes like color or size. It also contains an image of the product. Some ecommerce platforms use the same line item id as the product id.

quantity is the number of this product that the customer wants to buy. unitPrice is the price of a single unit of the product, and totalPrice is the unitPrice multiplied by the quantity.

Customer

In the context of eCommerce, customers are at the heart of the business. Understanding and managing customer data effectively is crucial for providing personalized experiences and building long-lasting relationships. The Unified Data Model (UDL) includes a section dedicated to managing customer data, allowing businesses to capture and utilize valuable customer information.

SfCustomer

import { SfId } from "./shared";

export interface SfCustomer {
  id: SfId;
  email: string;
  firstName: string;
  lastName: string;
}

The SfCustomer interface represents a customer in the Unified Data Model. It contains the following properties:

• id: Unique identifier for the customer.
• email: Customer's email address.
• firstName: Customer's first name.
• lastName: Customer's last name.

By including the SfCustomer interface in the Unified Data Model, businesses can efficiently store and manage customer data, allowing for a seamless customer experience across various platforms. Additionally, this data can be leveraged to provide personalized recommendations, targeted marketing, and better customer support, ultimately leading to increased customer satisfaction and loyalty.

Remember that while the UDL provides a solid foundation for managing customer data, businesses might have specific requirements for customer information based on their unique offerings and target audience. Customization of the model may be necessary to cater to these specific needs and ensure that customer data is captured accurately and effectively.

SfOrder

export interface SfOrder {
  id: SfId;
  orderDate: string;
  status: string;
  lineItems: SfOrderLineItem[];
  subtotalPrice: SfMoney;
  totalShippingPrice: SfMoney;
  totalTax: SfMoney;
  totalPrice: SfMoney;
  shippingAddress: SfAddress;
  billingAddress: Maybe<SfAddress>;
  shippingMethod: SfShippingMethod;
  paymentMethod: string;
}

The SfOrder interface represents a complete order in the Unified Data Model. It includes the following essential properties:

• id: Unique identifier for the order.
• orderDate: Date when the order was placed.
• status: Status of the order.
• lineItems: Array of SfOrderLineItem objects, each representing an individual line item within the order.
• subtotalPrice: Total price of all line items in the order, represented as an SfMoney object.
• totalShippingPrice: Total shipping price for the order, represented as an SfMoney object.
• totalTax: Total tax amount for the order, represented as an SfMoney object.
• totalPrice: Total price of the order, including the subtotal, shipping, and tax. Represented as an SfMoney object.
• shippingAddress: Shipping address for the order, represented as an SfAddress object.
• billingAddress: Billing address for the order, represented as an SfAddress object.
• shippingMethod: Selected shipping method for the order, represented as an SfShippingMethod object.
• paymentMethod: Payment method used for the order.

The SfOrder entity provides a comprehensive representation of an order, capturing all the necessary details required for efficient order management and processing. With this interface, businesses can seamlessly handle the entire order lifecycle, from order placement to fulfillment and payment.

SfOrderLineItem

export interface SfOrderLineItem {
  id: SfId;
  attributes: SfAttribute[];
  unitPrice: SfMoney;
  totalPrice: SfMoney;
  quantity: number;
  image: Maybe<SfImage>;
  productId: SfId;
  productName: string;
  sku: Maybe<string>;
}

The SfOrderLineItem interface represents an individual line item within an order in the Unified Data Model. It includes the following properties:

• id: Unique identifier for the order line item.
• attributes: Array of SfAttribute objects representing additional attributes associated with the line item.
• unitPrice: The unit price of the product in the line item, represented as an SfMoney object.
• totalPrice: The total price of the line item, calculated as the unit price multiplied by the quantity, represented as an SfMoney object.
• quantity: The quantity of the product in the line item.
• image: An SfImage object representing the product image associated with the line item.
• productId: Unique identifier for the product associated with the line item.
• productName: The name of product associated with the line item.
• sku: Optional product SKU (Stock Keeping Unit) associated with the line item.

The SfOrderLineItem entity allows businesses to effectively manage and process individual products within an order. By leveraging this interface, businesses can seamlessly handle various aspects of order fulfillment, inventory management, and pricing calculations.

SfOrderListItem

export type SfOrderListItem = {
  id: SfId;
  orderDate: string;
  status: string;
  totalPrice: SfMoney;
};

The SfOrderListItem interface provides a simplified version of an order, primarily used for listing orders made by customers. It includes the following properties:

• id: Unique identifier for the order.
• orderDate: Date when the order was placed.
• totalPrice: Total price of the order, represented as an SfMoney object.
• status: Status of the order.

The SfOrderListItem entity offers a concise overview of each order, allowing businesses to display essential order information to customers in a clear and organized manner. This simplified representation is particularly useful when presenting a list of orders in user accounts or order history sections, where customers can quickly review their past purchases.

By utilizing all three interfaces – SfOrderLineItem, SfOrder, and SfOrderListItem, businesses can effectively manage customer and order data, provide seamless customer experiences, and gain valuable insights into customer behavior and preferences. Customization may be necessary to adapt these entities to specific business requirements, ensuring a personalized solution that meets the unique needs of your eCommerce platform.