Skip to main content

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:
  • 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.

📄️ 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.