Skip to content
Last updated

ProductItem Data Model in Norce Commerce Product Service

Overview:
The ProductItem model provides a simplified, high-performance representation of products for listing and search scenarios in Norce Commerce Product Service. It is designed for efficient retrieval and display, containing essential product data but omitting large or rarely used fields. For full product details, use the Product entity.

ProductItem Model Structure

The ProductItem entity is returned by product list endpoints and contains a subset of product data. It is optimized for scenarios where many products are displayed, such as category listings or search results.

  • ProductItem: Simplified product representation for listings.
  • Product: Full product entity with all details, returned by GetProduct calls.

Note: For a detailed comparison between ProductItem and Product, see Working with Products and Variants.

ProductItem Elements

Each ProductItem includes key product information needed for display and selection. For a full schema, see the API reference.

Product Identifiers

ProductItem includes several identifiers to uniquely reference products:

  • Id: Internal, unique within the Norce Commerce environment.
  • PartNo: External part number, often from ERP.
  • Manufacturer/PartNo: Manufacturer-specific identifier.
  • UniqueName: SEO-friendly, language-specific identifier.
  • GroupByKey: Used for grouping variants in certain listing scenarios.

Note: For products with variants (asVariants=false), identifiers may be empty, similar to the Product entity.

Text Information

ProductItem returns only essential text fields for performance:

  • Name: Product name.
  • VariantName: Name of the variant (if applicable).
  • SubHeader: Short subheading.
  • SubDescription: Brief description.
  • ParametricTextField: All global text parametrics.
  • Synonyms: Alternative names.

Tip: For full text details, use the GetProduct endpoint.

Parametrics

Parametrics are structured product attributes. In ProductItem, they are returned as comma-separated lists for efficiency:

  • ParametricValueSeed: Id1:Value1,Id2:Value2,... (for non-list parametrics).
  • ParametricListSeed: Id1:ListValueId1,Id2:ListValueId2,... (for list parametrics).
  • ParametricMultipleSeed: Id1:MultipleValueId1,Id1:MultipleValueId2,... (for multiple list parametrics).
  • VariantParametricSeed: Id1:Id2:Id3,... (IDs of variant-defining parametrics).

Note: HTML or large text parametrics are not returned, except for global text parametrics.

To resolve parametric IDs and values, use:

Product Flags

Flags are used to segment business logic. ProductItem includes:

  • FlagIdSeed: Comma-separated list of product flag IDs.
  • VariantFlagIdSeed: Variant-specific flags (if the item is a variant).

Tip: Use ListFlags to resolve flag details.

Images

ProductItem provides image references for display:

  • ImageKey: Main product image.
  • VariantImageKey: Main image for the variant (if applicable).
  • AdditionalImageKeySeed: Additional images by type and key pairs.

Note: File information is not included. To retrieve files, use the Product entity.

Price Information

ProductItem includes price fields similar to the Product entity, except for cost fields:

  • Price: Best price (excluding VAT).
  • PriceIncVat: Price including VAT.
  • PriceListId: Price list identifier.
  • PriceStandard: Standard price inherited from parent price list (excluding VAT).
  • PriceRecommended: Recommended price for comparison (excluding VAT).
  • PriceCatalog: Another price field for comparison (excluding VAT).

On Hand (Availability) Information

Availability fields in ProductItem:

  • OnHand: Aggregated stock.
  • OnHandStore: Store-specific stock.
  • OnHandSupplier: Supplier availability.

Each field provides current stock, incoming stock, next delivery date, and lead time.

Note: Read more about availability here.

Buying Information

Fields to assist with buying logic:

  • IsBuyable: Indicates if the product can be purchased.
  • RecommendedQuantity: Suggested default quantity.
  • IsRecommendedQuantityFixed: Restricts purchase to multiples of the recommended quantity.
  • StockDisplayBreakPoint: Used to determine how to display availability.

Note: Always validate "is buyable" in your backend logic.

Variants in ProductItem

Unlike the Product entity, ProductItem does not include a VariantCollection. Variant information is handled using parametric and flag seeds. For details, see Listing Products with Variants.

ProductItem2

ProductItem2 is used in dynamic product listings. It contains similar data to ProductItem, but fields are optional and returned only if specified in the input parameter expand.

For more information, see Listing with a Dynamic Result.