Working with listing products and variants
There are two main patterns when working with listing and searching products using the Norce Commerce Product Service:
- using Norce Commerce Services methods and functions along with a cache for performance or
- using external search engines that are updated using the Norce Commerce Product Feed
(learn more about this pattern here).
You can also use a combination of both approaches, such as using an external search for initial searches and Norce Commerce Services for loading filters on the same result. The best solution depends on the systems you use and the size and complexity of your product catalog.
The ProductItem model
The productitem entity in Norce Commerce is complex, and the API may return a lot of data that is either utilized or discarded based on the client's requirements. Understanding and get a familiarity of the entities and the common elements of the productitem model is key.
- More on the ProductItem and ProductItem2 data model.
List, search and browse products
The primary method for finding products using Norce Commerce Services is ListProducts2. This method takes several input parameters and returns a list of ProductItem's (see below).
Input parameters can be categorized as contextual or user actionable.
User actionable parameters represent user actions such as choosing specific filters in a search list that narrow down the product results.
Contextual parameters are defined in the context of the method call execution.
For example, if a user enters a specific navigation in the app or searches for something, this action translates into a set of values passed as parameters to Norce Commerce Services. These could be a search string, a set of statuses, or a specific drop point (store) nearest to the user based on a choice or geographical algorithm.
Contextual parameters can be site-configured (e.g., which statuses to use), or based on user-selection (preferred language, logged in as a customer/company, access to special price lists, etc).
| Input parameter | Type | Description |
|---|---|---|
categorySeed | contextual | comma separated list of CategoryIds, commonly configured for a specific navigation list in the app. |
manufacturerSeed | contextual | comma separated list of ManufacturerIds, commonly configured for a specific navigation list in the app. |
flagSeed | contextual | comma separated list of FlagIds, commonly configured for a specific navigation list in the app. |
parametricsSeed | contextual | comma separated list of ParametricIds, commonly configured for a specific navigation list in the app. |
statusSeed | contextual | comma separated list of StatusIds, commonly configured for a the whole app. |
storeSeed | v | comma separated list of StoreIds, usually a choice by the user. |
pricelistSeed | contextual | comma separated list of PriceListIds, in some scenarios this is configured for a specific navigation list, but can also be a user specific choice or action. |
customerId | contextual | from the user or a user action, adds additional products and prices to the search (if it exists any) that is bound to the customer. |
companyId | contextual | from the user or a user action, adds additional products and prices to the search (if it exists any) that is bound to the company. (note that there must be a customerId passed in for a companyId to be applied) |
culturecode | contextual | usually from the user setting or action, overrides the default language for the application. |
sort | contextual or user actionable | usually initially set up in the context, but can sometimes be replaced from a user action. Sets the sort order of the list. |
pageSize | contextual or user actionable | usually initially set up in the context, but can sometimes be replaced from a user action. Sets the number of items to return per page. Read about paging here. |
pageNo | user actionable | set which page that should be returned. Read about paging here. |
searchString | contextual or user actionable | Sometimes this is a user action but can also be part of the contextual setup for a specific navigation list, see the "note" below. |
asVariants | contextual | obsolete, use ListVariantItems instead, see here. |
filter | user actionable | from a user action where they choose specific filtering, read more about filters here. |
The Norce free-text search feature searches for text in various fields of the product, including PartNo, ERPName, IntegrationPartNo, Referenced PartNo's, Supplier PartNo's, and EANcodes. Additionally, it searches for Name, VariantName, Manufacturer, Synonyms, Category Names (all in the hierarchy), Category default synonyms and product family names, all in the specified language or default language. These fields are included in the indexed search algorithm.
ListProducts2 is a powerful method and can do a lot, but it's also helpful to know about other listing methods that you can use. Here are some options:
| Name | Description |
|---|---|
| ListProductsByCustomer | Returns results based on a specific customer or company's price lists. |
| ListProductsByIds3 & ListProductsByPartNos | Take a list of ProductIds or PartNos as input. Use them to get more information about products you already have. |
| ListProductsByPromotionRequirement | Takes a PromotionId as an input. It's useful for displaying all products associated with a campaign or promotion on your app's campaign pages. |
| ListIncludedProducts | Requires a structured product or package PartNo as input. It returns a list of all products included in the package. |
| ListProductsByPriceList2 | This method utilizes the next generation of product listing (see below). From the pricelistSeed input parameter, it returns results based solely on that list of products. Use this method to display products associated with a specific campaign or price list, or when a price list handles specific assortments for you. |
Listing with a dynamic result
Product listings can be overwhelming due to the large amount of data that is returned. In response, Norce developed a more flexible version of listings that allows you to choose how much information you want returned by passing in a parameter called "expand." This feature enables you to request only the necessary information and reduces the load on Norce Commerce's Product Service.
Currently only ListProductsByPriceList2 and ListVariantItems uses this new list pattern (read about Variants below).
Using "expand"
Expand is a string of specific values that can be passed in as a parameter. For example, None returns only the basic information, while PriceOnhand adds price and availability details to the result. Check the API reference documentation for a list of allowed values.
List products with variants
Leave out variant concerns
Variants are not commonly handled in product listings until a user wants to see more about a specific product, at which point the variant information comes into play. When calling the GetProduct method, a product item with variants will not have a partNo, but the get methods will work well with the Id and will return the product and its variants as described in a separate document.
However, sometimes you may want to display variant information on the listing itself. This could be useful if, for example, you want to display variant data when filtering by a variant parameter like color (showing product images in the corresponding color), or if you want to include buy buttons directly in the list view.
There are two ways to work with variants in product listings.
- Set the input parameter
AsVariantsto true, and - Use the method
ListVariantItems
AsVariants set to true
The first method is to use the asVariants input parameter, which returns a ProductItem for each variant in the result. When this option is used, the variant-specific fields in ProductItem are used (otherwise they are empty).
To display the result, you can use the GroupByKey option, which will be a productId for products without variants and 'v' + variantId for products with variants.
The ItemCount in the result set or in the filters is based on the number of products, not variants, and paging does not take variants into account either.
For example, a pageSize of 10 will return more ProductItems than 10 if asVariants = true and there are many variants on the products.
Filtering will ignore variants, count values will not take variants into account, and the filters are based on the parameters promoted to Filters in admin, not automatically adding variant type parameters.
You must ensure that this is done in the Admin UI.
ListVariantItems
Using the asVariants parameter above, is not a good solution for situations with a lot of variants as it can lead to large results and affect the performance.
In such cases, Norce Commerce provides another way to work with variants -ListVariantItems. This method takes a list of ProductId's as input and returns variant-specific information.
You can also apply further filtering to ListVariantItems, but only variant parameters will be used.
To use this method, you must take the productId's from the result of ListProducts and pass them as input to ListVariantItems. Match the result using GroupByKey with the paged list and display the desired information from the different variants.
ListVariantItems returns a dynamic result, which means it takes an expand input parameter allowing you to specify what you want to be returned.
Other Listing functionality
BestSelling and popular listings
Norce Commerce Product Service provides specific methods to retrieve bestselling and popular products, which are based on sales and view count statistics respectively. However, these methods are now less commonly used and are mostly replaced by sorting with the popularityRank parameter, which is more flexible and configurable.
Families
There are also list methods that lists products from the same family as one passed in, but these may be moved into the common ListProduct method in the future.
Search suggestion
SearchProductsLite2 is a special listing that enables you to set up a search suggestion functionality. When the user types a few characters in the search box, SearchProductLite is called to retrieve a small list of suggestions from Norce Commerce's Product Service text search.
Old and obsolete
TopProducts
The TopProducts listing is no longer supported and will be removed in the future.
Node
The list methods that use navigation nodes are also no longer supported and will be removed in the future.