Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Products API handler

Return a single product.

HTTP Verb – GET

URL – /api/v1/products/{productId}

Description – Return a single product

Base – HandlerBase<GetProductParameter, GetProductResult>

Handlers

OrderHandlerDescription
500GetProductUses the GetProductCollectionHandlerhandler chain to retrieve a product. The ProductIdproperty on the parameter object is used to find the product. If zero or more than one product is found, an error is returned. The product found is stored in the ProductDtoproperty on the result object.
600AddToRecentlyViewedIf parameter AddToRecentlyViewed and WidgetSettings RecentlyViewedEnabled is true, calls ICatalogPipeline.AddToRecentlyViewedProducts passing in the Product ErpNumber.
700GetAlsoPurchasedProductsIf parameter GetAlsoPurchasedProducts is false then bypasses handler. If WidgetSettings.EnableDynamicRecommendations is false then returns error. Otherwise calls ICatalogPipeline.GetAlsoPurchasedProducts and sets AlsoPurchasedProducts to result.ProductDto.

HTTP Verb – GET

URL – /api/v1/products/{productId}/price

Description – Return pricing for a collection of products

Base – HandlerBase<GetProductsPriceCollectionParameter, GetProductsPriceCollectionResult>

Handlers

OrderHandlerDescription
500ValidateContextUses the GetProductSettingsHandler handler chain to retrieve product search settings and stores them in the GetProductSettingsResult property on the result object. If either the CanSeeProducts or CanSeePrices property on the settings object equals "false", an error is returned (the current user cannot search for or see products or see product prices).
For each price parameter in the GetProductPriceParameters collection on the parameter object, the product is retrieved. Then, both the price parameter and product are added to the GetProductPriceParameterProductscollection on the result object.
600CreatePricingServiceParametersEach of the price parameters in the GetProductPriceParameterProducts collection on the result object are transformed into a PricingServiceParameter and stored in the PricingServiceParameters property on the result object. The pricing service parameters are used by the pricing service to retrieve prices.
700GetProductPricingUses the GetProductPricingpipeline to retrieve product prices. The pricing service parameters are passed to the pipeline to retrieve the pricing. The pricing results are stored in the GetProductPricingResultproperty on the result object.
800CreateProductPriceDtosTransforms the each pricing result into a ProductPriceDtoand stores the collection in the ProductPriceDtosproperty on the result object.

HTTP Verb – GET

URL – /api/v1/products/{productId}/crosssells

Description – Return a collection of global website cross sell products

Base – HandlerBase<GetCrossSellCollectionParameter, GetCrossSellCollectionResult>

Handlers

OrderHandlerDescription
500GetCrossSellCollectionHandlerGets a cross sell product based on the productId parameter.
OrderHandlerDescription
500ValidateContextUses the GetProductSettingsHandler handler chain to retrieve product search settings and stores them in the GetProductSettingsResult property on the result object. If the CanSeeProducts property on the settings object equals "false", an error is returned (the current user cannot search for or see products).
600GetWebsiteCrossSellQueryCreates the initial cross sells query that returns active cross sells for the current website. If the WebCrossSellproperty on the parameter object equals "false", this handler is skipped. The cross sells query is stored in the CrossSellQueryproperty on the result object.
700GetProductCrossSellQueryCreates the initial cross sells query that returns active cross sells for a specific product. If the WebCrossSellproperty on the parameter object equals "true", this handler is skipped. If a product cannot be found using theProductIdproperty on the parameter object, an error is returned. The cross sells query is stored in the CrossSellQueryproperty on the result object.
800CreateCrossSellProductDtosExecutes the CrossSellQuery. The result is stored in the CrossSells property on the result object. Also, uses the CreateProductDtos catalog pipeline to transform the cross sells into a collection of ProductDtos. The transformed products are stored in the CrossSellProductDtos property on the result object.

HTTP Verb – GET

URL – /api/v1/products

Description – Return a collection of products

Base – HandlerBase<GetProductCollectionParameter, GetProductCollectionResult>

Handlers

OrderHandlerDescription
500GetProductCollectionHandlerGets active products either through the Search Index (no values for parameters: ProductsIds, Names, ErpNumbers, ExtendedNames) or Database depending on parameter values if the current website is set to see products (user is not logged in will check the SignInRequiredToBrowse website configuration value. Also checks if the website is set as Restricted then checks if a current customer exists or if customer exists then if this website is in their AllowedWebsites list).

HTTP Verb – GET

URL – /api/v1/products

Description – Return a collection of products

Base – HandlerBase<GetProductCollectionParameter, GetProductCollectionResult>

Handlers

OrderHandlerDescription
-999OverrideV1WithV2If PerformanceSettings OverrideProductV1 is false, this handler is bypassed. If parameter GetOnlyFacetedSearches is true, this handler is bypassed. If parameter GetHiddenProducts is true and there are no ProductIds, this handler is bypassed. If parameter ReplaceProducts is true and there is not exactly one parameter ExtendedName, this handler is bypassed. This handler maps the V1 parameter to a V2 parameter and then calls the Products V2 handler chain to get the products and maps the results to the V1 results. It then calculates pricing and inventory (if they are not real-time) in a very efficient way still using the pricing and inventory pipelines, but with the list of products rather than one at a time. It then exits the handler chain returning the results and none of the following handlers are executed. If you want to turn this setting on, any customizations you have in the V1 product handler chain and pipelines would need to be made in the V2 product handler chain. Note: When expanding warehouses, if there are no warehouses assigned to a product, it will only return the default warehouse with a quantity of 0, this differs from V1 which will return all of the warehouses with a quantity of 0.
500ValidateContextUses the GetProductSettingsHandler handler chain to retrieve product search settings and stores them in the GetProductSettingsResult property on the result object. If the CanSeeProducts property on the settings object equals "false", an error is returned (the current user cannot search for or see products).
525GetTopSellersIf parameter GetTopSellers is true, calls ICatalogPipeline.GetTopSellerProducts and sets the ProductDtos to result.
535ReturnTopSellersIf parameter GetTopSellers is true, returns result and skips other handlers in chain.
550GetRecentlyViewedIf parameter GetRecentlyViewed is true, calls ICatalogPipeline.GetRecentlyViewedProducts and sets the result GetRecentlyViewedProductsResult.
575GetFrequentlyPurchasedIf parameter GetFrequentlyPurchased is true, calls ICatalogPipeline.GetFrequentlyPurchasedProducts and sets result GetFrequentlyPurchasedProductsResult.
600DetermineFindMethodPopulates boolean flags on the result object to determine how to search for products. See additional information below.
700FindProductsWithSearchSearches for products using a query. The search is executed against Elasticsearch. If the FindWithSearch property on the result object equals "false", this handler is skipped. If the product search was successful, the product search results and related data are stored on the result object. The actual product objects are stored on the SearchResultProductDtos property on the result object. Also, creates a query for the products that were found during search. This query executes against the Configured Commerce database, rather than Elasticsearch. The query is stored in the ProductQuery property on the result object.
800FindProductsWithLookupCreates the initial product query that returns products by id, name, or ERP number. This query will be executed against the Configured Commerce database. If the FindWithSearch property on the result object equals "true", this handler is skipped. If the LookupByIds or LookupByExtendedNames properties on the result object are equal to "true", the product query is filtered by ProductId using the ProductIds property on the parameter object (if using extended names, the related product ids are found first). If the LookupByNames property on the result object equals "true", the product query is filtered by Name. If the LookupByErpNames property on the result object equals "true", the product query is filtered by ErpNumber using the ErpNumbers property on the parameter object.
900ApplyExpandsExpands the ProductQuery by fetching related objects, but only if specified in the parameter.
If the GetPrices property on the parameter object equals "true", the query will also fetch the warehouses for each product.
If the GetDocuments property on the parameter object equals "true", the query will also fetch the documents for each product.
If the GetSpecifications property on the parameter object equals "true", the query will also fetch the specifications for each product.
If the GetAttributeValues property on the parameter object equals "true", the query will also fetch the attribute types and values for each product.
1000ExecuteQueryExecutes the ProductQuery after the query has been expanded, filtered, sorted, and paged. The result is stored in the Products property on the result object. If the FindWithSearch property on the result object equals "true", the rest of the handler is skipped. If zero products are found with the query, an error is returned. The NotAllProductsFound property on the result object is set to "true" if the number of products found by the query does not match the number of product parameters passed in (e.g. product ids, names, or ERP numbers).
1100CreateProductDtosUses the CreateProductDtos catalog pipeline to transform the products into a collection of ProductDtos. The transformed products are stored in the ProductDtos property on the result object.
1200SortAndPageByRegularPriceSorts and pages the products returned by the ProductQuery by regular price. If the "Pricing Service" setting equals "List Price", this handler is skipped (the search provider handles sorting). If the Sort property on the parameter object is NOT equal to "PriceLowToHigh" or "PriceHighToLow", this handler is skipped.
1250SortByRecentlyViewedIf result GetRecentlyViewedProductsResult is not null, sorts the results by the order of the GetRecentlyViewedProductsResult Products ViewDate descending.
1275SortByFrequentlyPurchasedIf result GetFrequentlyPurchasedProductsResult is not null, sorts the results by the order of the GetFrequentlyPurchased Products.
1300CreateDynamicPersonalizationLogs dynamic personalization data if the parameter has the ApplyPersonalization property equal to "true". If the categories associated with the request have any associated Personas ("Segments") which have AutoAssignGuestUser equal to "true", they will be saved into ElasticSearch for the user initiating the request.
1400UpdateDynamicPersonalizationAssigns Personas to the current session if conditions have been met for Personas with AutoAssignGuestUser equal to "true". This is done by calling ElasticSearch to query data posted by the CreateDynamicPersonalization handler. Updates the assigned persona cookie.

Order 600 DetermineFindMethod Specifications

Result PropertyDescription
LookupByIdsSet to "true" if the ProductsIds property on the parameter object contains at least 1 id.
LookupByNamesSet to "true" if the Names property on the parameter object contains at least 1 name.
LookupByErpNumbersSet to "true" if the ErpNumbers property on the parameter object contains at least 1 name.
LookupByExtendedNamesSet to "true" if the ExtendedNames property on the parameter object contains at least 1 name.
FindWithSearchSet to "true" if all the previous properties equal "false".