Shopper Catalog API

Use the Shopper Catalog View API to retrieve hierarchy, node and product information for a catalog release. When you publish a catalog for a store, you can define catalog rules so that you can show catalogs with different pricing or different products to preferred customers or channels. These endpoints can be used in your customer-facing frontends.

A catalog is a combination of one or more hierarchies, products, and a price book. Use the Products API and Hierarchies API to create a hierarchy of products that can be included in a catalog. Use the Price Book API to associate prices with products.

Characteristics of Shopper Catalogs

Shopper catalogs can have the following characteristics.

• Use catalog rules to schedule a catalog to appear during a particular date and time, such as a seasonal catalog. The catalog may have different pricing than the other catalogs. You can have multiple published catalogs.
• If you have defined catalog rules and you want to retrieve a published catalog for a particular channel or a user-defined tag, you must set the appropriate headers in the request:
  • EP-Channel - The channel, such as website or mobile app. See Create a Catalog Rule.
  • EP-Context-Tag - A tag defined in the store, such as clearance. See Create a Catalog Rule.

• When a catalog is ready to be used in a store, you publish it. See Publish a Catalog.
• You can create and publish catalogs for different contexts and channels. You can see the differences between the last 2 consecutive catalog releases. See Publish a Catalog.
• You retrieve catalogs for your shopper experience by using the Shopper Catalog View API. For more information on how you can retrieve a catalog as a shopper using the Catalog API.
• When a catalog is published for a store, the corresponding events contain store_id and org_id.
• When a catalog is published for an organization, the corresponding events contain org_id.
• Use the sort_order value in variations to program your storefront to display the variation options in the order that you want.

Shopper Catalog Caching

When conducting a GET on catalog endpoints, all data returned, including catalog releases, products, nodes and hierarchies, are cached for 5 minutes. This means, if you call the same endpoint again, the catalog data is retrieved from the cached objects pool, optimizing the performance and efficiency of your store front.

If you use any of the catalog endpoints with a filter or include query parameter, these are cached separately.

The cached entries disappear from the cached objects pool after 5 minutes.

📄️ Get all Hierarchies

Returns all hierarchies from a catalog.

📄️ Get a Hierarchy

Returns a hierarchy from the catalog.

📄️ Get a Hierarchy's Nodes

Returns all the nodes for the specified hierarchy.

📄️ Get a Hierarchy's Children

Returns the parent nodes for the specified hierarchy.

📄️ Get all Nodes

Returns all nodes in the catalog.

📄️ Get a Node

Returns a node from the catalog.

📄️ Get a Node's Children

Returns the child nodes for a node in the catalog.

📄️ Get all Products

Retrieves the list of products from the catalog. Only the products in a live status are retrieved.

📄️ Get a Product

Returns the specified product from the catalog. The product must be in the `live` status.

📄️ Get a Bundle's Component Products

With Product Experience Manager, you can [create](/docs/api/pxm/products/create-product) and manage bundles. A bundle is a purchasable product, comprising of one or more products that you want to sell together.

📄️ Get a Parent Product's Child Products

For a specified product and catalog release, retrieves a list of child products from a parent product. Any product other than a base product results in a `422 Unprocessable Entity` response. Only the products in a `live` status are retrieved.

📄️ Get a Hierarchy's Products

Returns the products associated with the specified hierarchy in the catalog. The products must be in the live status.

📄️ Get a Node's Products

Returns the products associated with the specified hierarchy node in the catalog. The products must be in the `live` status. If the products have been curated then the products are returned in the order specified in the `curated_products` attribute. A product that is curated has the `'curated_product': true` attribute displayed.

📄️ Configure a Shopper Bundle

Once you have configured your product bundles, you can display them in your storefront in your published catalog. Depending on how you have configured the minimum and maximum values for the product options in your components, you can allow your shoppers to choose which products they want to select. For example, you can enable a shopper to select 1 or more product options from a list of 10, giving your shoppers greater flexibility when selecting products in your store front.