Catalog Module

Back

Overview

The Catalog module is responsible for managing all product-related master data.
It defines how products are described, classified and enriched before they are used
by pricing, inventory and sales modules.

Catalog is a foundational module and is required for:

• product listings
• search and filtering
• pricing configuration
• inventory management
• SEO and merchandising

All operations are tenant-aware and scoped to the current tenant.

Services

The Catalog module consists of the following services:

• Brands - product brands and manufacturers
• Category - product categories and hierarchies
• Products - core product data
• Product Category - product category relations
• Product Colour - colour variants
• Product Size - size variants
• Product SEO - SEO metadata
• Product Property Value - dynamic product attributes
• Related Product - related and cross-sell products
• Property - attribute and property definitions
• Product System Types - variant dimension definitions (e.g. Colour, Size)
• Product Variants Type - concrete dimension values per product
• Product Variants - purchasable product variants
• Product Variants Attributes - dimension assignments per variant
• Product Images - product and variant images

Models

This module exposes and consumes the following models.

• Brand Model
• Category Model
• Product Model
• Product Colour Model
• Product Size Model
• Product SEO Model
• Product Property Value Model
• Property Model
• Product System Type Model
• Product Variants Type Model
• Product Variant Model
• Product Variant Attribute Model
• Product Image Model

Brand Model

Represents a product brand or manufacturer.

Fields:

• Id (type: long) - internal identifier
• Name (type: string?) - brand display name
• Code (type: string?) - unique brand code (per tenant)
• IsActive (type: bool?) - active flag

Validation:

• IsReadyToAdd()
  • requires Name and Code
• IsReadyToUpdate()
  • requires Id > 0
  • requires Name and Code
  • IsActive is optional

Category Model

Represents a product category.

Fields:

• Id (type: long?) - internal identifier
• Code (type: string?) - unique category code
• Name (type: string?) - category name
• Slug (type: string?) - SEO-friendly URL slug
• ParentId (type: long) - optional parent category
• IsActive (type: bool?) - active flag
• Products (type: List<ProductModel>?) - associated products (only included when explicitly requested)

Validation:

• IsReadyToAdd()
  • requires Name and Code
  • Slug is optional
• IsReadyToUpdate()
  • requires Id > 0
  • requires Name and Code
  • Slug is optional

Notes:

• Slug is used for SEO-friendly URLs
• Products are only included when explicitly requested via showProducts query parameter
• Product list respects entity access permissions when entityId is provided

Product Model

Represents a catalog product with pricing, stock, dynamic properties and variant data.

The product entity is the core element of the Catalog module and is used across pricing, inventory and sales domains.

Fields:

• Id (type: long) - internal product identifier
• SKU (type: string?) - product code / SKU
• Title (type: string?) - product display name
• Summary (type: string?) - short product summary
• Description (type: string?) - full product description
• Brand (type: BrandModel?) - associated brand object { Id, Name, Code, IsActive } (replaces flat BrandId)
• TaxCodeId (type: long?) - tax classification identifier
• UnitOfMeasureId (type: long?) - unit of measure identifier
• WeightKg (type: decimal?) - product weight in kilograms
• IsActive (type: bool) - active flag
• CreatedAt (type: DateTime) - creation timestamp
• UnitPrice (type: decimal?) - base unit price (product-level)
• Stock (type: List<StockModel>?) - product-level stock information
• SEO (type: ProductSEO?) - SEO metadata
• Properties (type: List<ProductPropertyModel>?) - dynamic product properties
• Images (type: List<ProductImageModel>?) - all product and variant images
• ProductSystemTypes (type: List<ProductSystemTypeModel>?) - dimension types used by this product's variants
• ProductVariantsType (type: List<ProductVariantsTypeModel>?) - all dimension values available for this product
• ProductVariants (type: List<ProductVariantDetailModel>?) - variants with nested attributes, images, stock and price

Notes:

• All fields are tenant-scoped
• Brand is returned as a full object — no extra API call needed to resolve the brand name
• UnitPrice and Stock at product level are product-wide defaults
• ProductVariants[].UnitPrice and ProductVariants[].Stock reflect per-variant pricing and stock (mapped via ProductVariantId)
• Properties allow extending the product model without schema changes
• Images contains all images — both product-level and variant-level
• ProductSystemTypes is derived from the product's variants (no additional query)
• ProductVariants is a rich nested model; flat variant data is available via the ProductVariants endpoint

Product Colour Model

Represents a colour variant.

Fields:

• Id (type: long) - internal identifier
• CreatedAt (type: DateTime) - creation timestamp
• Description (type: string?) - colour description or display name
• Code (type: string?) - unique colour code
• ImageSwatchURL (type: string?) - URL to colour swatch image
• IsActive (type: bool?) - active flag (default: true)

Validation:

• IsReadyToAdd()
  • requires Code, Description, ImageSwatchURL
• IsReadyToUpdate()
  • requires Id > 0
  • requires Code, Description, ImageSwatchURL

Product Size Model

Represents a size variant that can be assigned to products.

Fields:

• Id (type: long) - internal identifier
• CreatedAt (type: DateTime) - creation timestamp
• Description (type: string?) - size description
• Code (type: string?) - unique size code
• IsActive (type: bool?) - active flag

Validation:

• IsReadyToAdd()
  • requires Code and Description
• IsReadyToUpdate()
  • requires Id > 0
  • requires Code and Description

Product SEO Model

Represents SEO metadata associated with a product.

Fields:

• ProductId (type: long) - associated product identifier
• MetaTitle (type: string?) - SEO meta title
• MetaDescription (type: string?) - SEO meta description
• Slug (type: string) - URL-friendly product slug
• CanonicalUrl (type: string?) - canonical URL

Validation:

• IsValid()
  • requires ProductId
  • requires MetaTitle
  • requires MetaDescription
  • requires Slug
  • requires CanonicalUrl

Notes:

• Slug is normalized (lowercase, spaces replaced)
• Slug must be unique per product

Product Property Value Model

Represents a value assigned to a dynamic product property.

Fields:

• ProductId (type: long) - associated product identifier
• PropertyId (type: long) - associated property identifier
• Value (type: string?) - property value

Validation:

• IsEmpty()
  • returns true if ProductId == 0 or PropertyId == 0

Notes:

• (ProductId, PropertyId) must be unique

Property Model

Represents a definable product attribute.

Fields:

• Id (type: long) - internal identifier
• Name (type: string) - property display name
• Code (type: string) - unique property code
• DataType (type: string) - expected value type (e.g. string, number, boolean)

Validation:

• IsReadyToAdd()
  • requires Name and Code
• IsReadyToUpdate()
  • requires Id > 0
  • requires Name, Code, DataType

Notes:

• Properties are reusable
• DataType controls value interpretation

Product System Type Model

Represents a classification type used to describe product variants (e.g. a dimension such as Colour or Size).

Fields:

• Id (type: int) - internal identifier
• Name (type: string?) - display name (e.g. Colour)
• Code (type: string?) - unique code (e.g. colour)
• Display Type (type: string?) - UI rendering hint (e.g. swatch, dropdown, text)
• Is Active (type: bool) - active flag
• Sort Order (type: int) - display order
• Created At (type: DateTime) - creation timestamp

Validation:

• IsReadyToAdd()
  • requires Name, Code, Display Type
• IsReadyToUpdate()
  • requires Id > 0
  • requires Name, Code, Display Type

Product Variants Type Model

Represents an available attribute value for a product's variants (e.g. a selectable option within a given type, such as Midnight Blue for Colour).

Fields:

• Id (type: long) - internal identifier
• Product Id (type: long) - parent product identifier
• System Type Id (type: int) - associated system type identifier
• System Type Name (type: string?) - resolved system type name (read-only)
• Value (type: string?) - raw value (e.g. #191970)
• Display Value (type: string?) - human-readable label (e.g. Midnight Blue)
• Sort Order (type: int) - display order within the dimension
• Created At (type: DateTime) - creation timestamp

Validation:

• IsReadyToAdd()
  • requires Product Id > 0, System Type Id > 0, Value
• IsReadyToUpdate()
  • requires Id > 0
  • requires Product Id > 0, System Type Id > 0, Value

Notes:

• System Type Name is populated from the navigation property and is not writable

Product Variant Model

Represents a purchasable variation of a product (e.g. a specific attribute combination such as Blue + Small), flat and 1:1 with the database table.

Fields:

• Id (type: long) - internal identifier
• Product Id (type: long) - parent product identifier
• SKU (type: string?) - unique stock-keeping unit code
• Title (type: string?) - variant display name
• Weight Grams (type: int?) - variant weight in grams
• Is Active (type: bool) - active flag
• Sort Order (type: int) - display order
• Created At (type: DateTime) - creation timestamp

Validation:

• IsReadyToAdd()
  • requires Product Id > 0, SKU, Title
• IsReadyToUpdate()
  • requires Id > 0
  • requires Product Id > 0, SKU, Title

Notes:

• This flat model is used by the ProductVariants endpoints
• The full nested model (with attributes and images) is ProductVariantDetailModel, embedded in Product Model

Product Variant Attribute Model

Represents an attribute assignment on a product variant (e.g. a dimension value link such as Colour → Midnight Blue).

Fields:

• Id (type: long) - internal identifier
• Product Variant Id (type: long) - the variant this attribute belongs to
• Product System Type Id (type: int) - the dimension (e.g. Colour)
• Product Variants Type Id (type: long) - the specific value (e.g. Midnight Blue)

Validation:

• IsReadyToAdd()
  • requires Product Variant Id > 0, Product System Type Id > 0, Product Variants Type Id > 0
• IsReadyToUpdate()
  • requires Id > 0
  • requires all three foreign keys

Product Image Model

Represents a visual asset linked to a product or one of its variants (e.g. a gallery photo or a variant-specific image).

Fields:

• Id (type: long) - internal identifier
• Product Id (type: long) - parent product identifier
• Variant Id (type: long?) - variant identifier; null means product-level image
• URL (type: string?) - publicly accessible image URL
• Alt Text (type: string?) - accessibility description
• Is Primary (type: bool) - primary image flag
• Sort Order (type: int) - display order

Validation:

• IsReadyToAdd()
  • requires Product Id > 0 and URL
• IsReadyToUpdate()
  • requires Id > 0
  • requires Product Id > 0 and URL

Notes:

• Images with Variant Id = null are product-level images
• Images with a Variant Id are variant-specific
• The Products service returns all images in the top-level Images array and additionally nests variant images inside each variant