Broadleaf Microservices
  • v1.0.0-latest-prod

Category Details Endpoint

Overview

The catalog details request mapping of CatalogBrowseEndpoint provides access to a category and all data relevant for displaying a product list or category details page through a single API call. This passes the request along to the CatalogProvider first to gather the base catalog info; second, to the PricingProvider for pricing hydration from the pricing service. Additionally, users could add other providers into the flow to hydrate other information from external services like inventory or user reviews services.

Tip
 See the OpenAPI spec for the category details endpoint.

Request Details

Headers

The request made can contain two headers (along with the typical X-Context-Request one) as well as several parameters used to determine which category to fetch. The headers are used to provide additional context for pricing the category’s products and are passed along in pricing calls after retrieving the base catalog info:

  • X-Price-Context: Contains general context info including the locale, currency, and user targets associated with the caller’s context

    • User targets include an identifier and type for a user such as an email and CUSTOMER for a single user.

  • X-Price-Info-Context: Contains additional context info for gathering price info for specific products. It includes a list of the products converted into PriceableTargets as well as an optional list of predetermined PriceLists from which prices should be derived.

Note

A PriceableTarget is a DTO representing any kind of entity that can be priced. It includes

  • the ID,

  • the type (e.g., SKU, PRICING_KEY),

  • a map representing the priceable fields of the entity (e.g., basePrice → $10.99, salePrice → $9.99, cost → 1.99)

  • and a map of arbitrary attributes that the pricing engine can target such as the entity’s name, categories it belongs to, etc.

Parameters

The following parameters are passed along to the CatalogProvider and are used to determine which category to retrieve.

  • categoryUrl: URL that maps to a specific category. This is used if categoryId is not provided and is the typical way a category is identified by a commerce-facing app since the URL that a user has navigated to is available while the specific ID of the category is not.

  • categoryId: The specific ID of the category to retrieve

  • productPageInfo: Pagination info applied to the products retrieved along with the category

  • attributes: A map for any unspecified, miscellaneous parameters

Response Details

The response includes the following details consolidated onto a category object:

  • assets: All of the category’s assets' metadata including their:

    • type: The asset type: IMAGE, VIDEO, PDF, etc.

    • altText: Corresponds to the HTML alt attribute on an <img> tag.

    • title: Corresponds to the HTML title attribute on an <img> tag.

    • contentUrl: The full URL used to resolve the actual asset content such as a CDN path for an image

    • embedCode: HTML to embed on a frontend

    • tags: Additional, descriptive or identifying text

    • See ProductAsset javadocs for the full details.

  • breadcrumbs: List of navigational breadcrumbs based on the category’s request context or category hierarchy

    • products: Hydrated page of products with summary information sufficient for displaying a category details or product list page

  • promotionalProducts: Lists of the various kinds of promotional products such as featured mapped by their type

Tip
 See the CategoryDetails javadoc for further details.