Products API\_handler

4 min

HTTP Verb – GET

URL – /api/v1/products/

Description – Return a single product

Base – HandlerBase<GetProductParameter, GetProductResult>

Handlers –

Order	Handler	Description
500	GetProduct	Uses 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.
600	AddToRecentlyViewed	If parameter AddToRecentlyViewed and WidgetSettings RecentlyViewedEnabled is true, calls ICatalogPipeline.AddToRecentlyViewedProducts passing in the Product ErpNumber.
700	GetAlsoPurchasedProducts	If 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//price

Description – Return pricing for a collection of products

Base – HandlerBase<GetProductsPriceCollectionParameter, GetProductsPriceCollectionResult>

Handlers –

Order	Handler	Description
500	ValidateContext	Uses 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.
600	CreatePricingServiceParameters	Each 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.
700	GetProductPricing	Uses 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.
800	CreateProductPriceDtos	Transforms the each pricing result into a ProductPriceDtoand stores the collection in the ProductPriceDtosproperty on the result object.

HTTP Verb – GET

URL – /api/v1/products//crosssells

Description – Return a collection of global website cross sell products

Base – HandlerBase<GetCrossSellCollectionParameter, GetCrossSellCollectionResult>

Handlers –

Order	Handler	Description
500	GetCrossSellCollectionHandler	Gets a cross sell product based on the productId parameter.

Order	Handler	Description
500	ValidateContext	Uses 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).
600	GetWebsiteCrossSellQuery	Creates 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.
700	GetProductCrossSellQuery	Creates 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.
800	CreateCrossSellProductDtos	Executes 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 –

Order	Handler	Description
500	GetProductCollectionHandler	Gets 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 –

Order	Handler	Description
\-999	OverrideV1WithV2	If 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.
500	ValidateContext	Uses 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).
525	GetTopSellers	If parameter GetTopSellers is true, calls ICatalogPipeline.GetTopSellerProducts and sets the ProductDtos to result.
535	ReturnTopSellers	If parameter GetTopSellers is true, returns result and skips other handlers in chain.
550	GetRecentlyViewed	If parameter GetRecentlyViewed is true, calls ICatalogPipeline.GetRecentlyViewedProducts and sets the result GetRecentlyViewedProductsResult.
575	GetFrequentlyPurchased	If parameter GetFrequentlyPurchased is true, calls ICatalogPipeline.GetFrequentlyPurchasedProducts and sets result GetFrequentlyPurchasedProductsResult.
600	DetermineFindMethod	Populates boolean flags on the result object to determine how to search for products. See additional information below.
700	FindProductsWithSearch	Searches 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.
800	FindProductsWithLookup	Creates 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.
900	ApplyExpands	Expands 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.
1000	ExecuteQuery	Executes 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).
1100	CreateProductDtos	Uses 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.
1200	SortAndPageByRegularPrice	Sorts 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.
1250	SortByRecentlyViewed	If result GetRecentlyViewedProductsResult is not null, sorts the results by the order of the GetRecentlyViewedProductsResult Products ViewDate descending.
1275	SortByFrequentlyPurchased	If result GetFrequentlyPurchasedProductsResult is not null, sorts the results by the order of the GetFrequentlyPurchased Products.
1300	CreateDynamicPersonalization	Logs 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.
1400	UpdateDynamicPersonalization	Assigns 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 Property	Description
LookupByIds	Set to "true" if the ProductsIds property on the parameter object contains at least 1 id.
LookupByNames	Set to "true" if the Names property on the parameter object contains at least 1 name.
LookupByErpNumbers	Set to "true" if the ErpNumbers property on the parameter object contains at least 1 name.
LookupByExtendedNames	Set to "true" if the ExtendedNames property on the parameter object contains at least 1 name.
FindWithSearch	Set to "true" if all the previous properties equal "false".