The Product data model in Norce Commerce Product Service
The primary entity in Norce Commerce is the Product. It contains a significant amount of data to be displayed to the end customer, as well as other information that is primarily for the frontend application. This makes it possible to add your own business logic.
The Product model is organized hierarchically, with the main Product entity serving as the root. It holds various data such as images, text, pricing, and availability information, and may include a list of variants. In such cases, the root Product stores all the general data shared among the variant products, while the variants store the unique information specific to each one.
Norce does not really have a master Product. When displaying variants, one of them is designated as the Product root in the Norce Commerce Services model, but it is not predetermined which one it will be at any given time. Variants are like a "cluster" of products that has some shared data.
The different product elements
In a product that has no variants, there are no variant elements, and all the data related to the product is contained within the root (product) element. Additionally, the products element contains some different types of information, see below.
An example product (without variants)
{ "Id": 31234587, "Name": "Forest Helmet Technical", "Description": "", "PartNo": "PRD0001273", "SubHeader": "", "Manufacturer": { "Id": 1685, "Name": "Husqvarna", "PartNo": "Foresthelmettechnical", "LogoPath": "", "LogoKey": null, "UniqueName": "husqvarna" }, "Image": null, "CampaignImage": null, "LargeImage": null, "ThumbnailImage": null, "Files": [], "FlagIdSeed": "915", "Price": 2191.20, "PriceCatalog": null, "PriceRecommended": null, "PriceFreight": null, "PriceFreightVatRate": null, "VatRate": 1.25, "RecommendedQuantity": 1.000, "OnHand": { "Value": 0.000, "IncomingValue": 0.000, "NextDeliveryDate": null, "LeadtimeDayCount": 0, "LastChecked": null, "IsActive": true, "IsReturnable": false, "Info": null }, "OnHandStore": { "Value": 0.000, "IncomingValue": 0.000, "NextDeliveryDate": null, "LeadtimeDayCount": null, "LastChecked": null, "IsActive": false, "IsReturnable": false, "Info": null }, "OnHandSupplier": { "Value": 0.000, "IncomingValue": 0.000, "NextDeliveryDate": null, "LeadtimeDayCount": 5, "LastChecked": "/Date(1487085384177+0100)/", "IsActive": true, "IsReturnable": false, "Info": null }, "Variants": [], "PriceListId": 1, "Key": "4ad9d701-170d-4446-a7b5-f09835cf71e0", "Updated": "/Date(1554808947000+0200)/", "NavigationNodeKey": "8cf3381a-4205-4fd8-8d90-034e8fa6e249", "CategoryId": 41722, "CategoryName": "Forest & Garden", "ImageKey": "3a689ca9-5d6c-481d-a080-66149fbd6034", "VariantParametrics": [ { "Name": "Cylindervolym", "Value": "123 cm3", "Id": 12330, "ValueId": null, "Description": "", "ValueDescription": null, "IsPrimary": true, "ValueIdSeed": "", "Value2": "123", "Uom": "cm3", "GroupId": 0, "GroupName": null, "SortOrder": 4 } ], "StatusId": 1, "MetaTags": "", "MetaDescription": "", "VariantName": null, "DescriptionHeader": "", "UniqueName": "forest-helmet-technical", "StockDisplayBreakPoint": null, "Parametrics": [ { "Name": "Cylindervolym", "Value": "123 cm3", "Id": 12330, "ValueId": null, "Description": "", "ValueDescription": null, "IsPrimary": true, "ValueIdSeed": "", "Value2": "123", "Uom": "cm3", "GroupId": 0, "GroupName": null, "SortOrder": 4 } ], "Families": [], "IsBuyable": true, "SubDescription": "", "Uom": "st", "UomCount": 1.000, "EanCode": "", "Type": 1, "Categories": [ { "Id": 41722, "Value": "Forest & Garden", "Code": "1010" }, { "Id": 41791, "Value": "Smycken", "Code": "" } ], "IsRecommendedQuantityFixed": false, "PopularityRank": null, "CostPurchase": 1202.63, "CostUnit": 0.00, "Title": null, "ActualWeight": 0.00, "IsDropShipOnly": false, "Synonyms": null, "IsSubscribable": false, "UnspscCode": "", "PriceStandard": 0.00, "Width": null, "Height": null, "Depth": null }
Product identifiers
The Id refers to the internal identifier assigned by Norce to the product, which is globally unique within a Norce Commerce environment(*) (but not across environments). On the other hand, the PartNo serves as the identifier that is either exposed or imported from other systems such as the ERP.
Meanwhile, there are other identifiers available such as the SEO-friendly UniqueName that is specific to the language used. Furthermore, under the Manufacturer element, there is also an identifier called Manufacturer.PartNo, which must be unique for the specified manufacturer. To retrieve product information for this product from Norce Commerce, you can use Id ( GetProduct ), PartNo (GetProductByPartNo), or UniqueName (GetProductByUniqueName) as needed.
(*) A Norce Commerce environment refers to environments such as “Prod” or “Stage”. Unique items within an environment, such as cached data, can be utilized in applications, but you cannot move hard coded Id´s between, for example Production and Lab environments as there is no guarantee that they are the same across different environments.
Text information
The product element in Norce Commerce includes language-specific data that describes the product for the customer or visitor. There are several pre-defined text fields with specific names, and there is also an option to use texts as a type of parametric (see below). How to display and utilize these fields depends on your client application.
The language used is determined by the primary (default) language for the application you use to call Norce Commerce, or by the culture code passed in the method call. In case no texts are specifically added for the culture you specified, it is possible to set up a fallback language. Some examples of language-specific texts include Name, Description, and Header.
Parametrics
Parametrics are structured information about the products. These can be of different types, including boolean, integer, decimal, text, html, list, and multiple list, and can be grouped using GroupName. All the parametrics set up for the product can be found in the Parametrics element.
Depending on how the client wants to present the product, these groups can represent different tabs, and some groups may even be hidden and used for internal processes instead. For parametrics that use list values (List and Multiple Lists), it may be necessary to look up specific values from the metadata for the parametric. This data is usually fetched separately and cached for extended periods of time ( use ListParametricInfo and ListParametricValues).
The element VariantParametrics contains the same information as Parametrics for products with no variants.
Product flags
The FlagIdSeed field in the product returns a list of flag IDs separated by commas. To determine the specific flags associated with the product, you can call the ListFlags and ListFlagGroups methods (and preferably cache the responses for an extended period of time). Flags have many uses, but are for the frontend typically utilized to segment business logic, such as tagging products for special treatment during the purchase process.
Images and files
Images and files in Norce Commerce are identified by a GUID value, which can be found in the ImageKey or Files field along with information about the extension and sometimes additional metadata. The file type is indicated by the Id field, which corresponds to the file type set up for the client in the admin UI. To retrieve the name of the file type, you can call ListFileTypeIds.
To access the image or file, use the following URL: https://[clientname].[environment] .cdn-norce.tech/[filekey] (*). If you need to resize images, you can add query parameters to the URL, as described in the Image Scaling and CDN documentation.
For Norce [Storm] the url is https://[clientname].cdn.storm.io/[filekey]
Price information
Norce Commerce Services returns the Best price for a product, which represents the lowest price from all valid price lists in the given context. For instance, a temporary campaign price may be the cheapest, and in such cases, the Price field will display it excluding VAT and the PriceIncVat has the same price but with VAT. The PriceListId will identify the campaign price list in this scenario, while the PriceStandard field inherits the standard price, allowing you to show it for comparison.
Additionally, CostUnit and CostPurchase are also included in the response, enabling you to display margins for internal users or utilize them in internal sales tool for creating quotes.
On hand information
A product's availability is returned as OnHand objects. These objects contain various details such as the Value (the quantity of the product that is currently in stock), IncomingValue, NextDeliveryDate (the date when incoming units are scheduled to arrive at the warehouse), and LeadTimeDayCount (an estimate of how long it typically takes for an item to reach a customer). This data allows you to determine exactly what to communicate to the customer regarding the product's availability.
There are three fields that provide on-hand information:
OnHand: This is the accumulated information from all warehouses that have the product in stock and are associated with the price list. Read the availability logic documentation for more information.OnHandStore: This provides information from all stores that are specified in the method calls using the "storeSeed" parameter.OnHandSupplier: This returns the availability from the primary supplier (if there is one).
Even though the field LeadTimeDayCount implies that the value represents the number of days until the customer usually receives the item, it is a relative value, and it's up to the client to interpret it as days, hours, or any other arbitrary measurement.
Read more about availability here.
Buying information
Finally, there are some fields that aim to assist in implementing the buying behavior. Some examples:
IsBuyable: A product can be marked as not buyable in Norce Commerce using a simple flag on the product (**).RecommendedQuantityandIsRecommendedQuantityFixed: When a product is added to a basket, theRecommendedQuantityvalue can suggest the default quantity. TheIsRecommendedQuantityFixedflag indicates whether the customer should be allowed to change the quantity to any value other than a multiple of theRecommendedQuantity.StockDisplayBreakpoint: This value can be set on a product or category in Norce Commerce and can be used to determine how to display availability information. For example, if the on-hand value is 12 and theStockDisplayBreakpointis 15, it may be appropriate to show more vague availability information instead of the exact quantity on the product page.
It is recommended to perform additional validation checks on the "is buyable" flag in your own backend layer. For instance, if you want to prevent customers from purchasing items that are out of stock, you must implement this logic on your side. An example is here.