EP PXM Catalogs API · Commerce Cloud

Use the EP PXM Catalogs API to create, manage, and publish catalogs. You can also define catalog rules so that you can show catalogs with different pricing or different products to preferred customers or channels.

You can use the EP PXM Catalogs service with either the pcm/products resource or the v2/products resource.

EP PXM Catalogs with `pcm/products`

A catalog is a combination of one or more hierarchies and a price book. In the object descriptions, parameters that are unique to pcm/products are identified with PCM.

Hierarchies

Use the EP PXM Products API and Hierarchies API to create a hierarchy of products that can be included in a catalog. You can also specify the order you want your hierarchies to display in a published catalog. You can order your hierarchies on a catalog-by-catalog basis.

Hierarchy_sorting

For more information, see Update a Catalog.

Understanding How Products And Nodes Are Associated

You can use breadcrumb metadata to understand how products and nodes are associated. This is useful if you want to improve how your shoppers search your store.

There are two different types of breadcrumb metadata. The type of breadcrumb metadata that you see depends on whether the endpoint you are using is with a product or a node.

To see how products are associated with nodes, use:
- bread_crumbs metadata. The bread_crumbs metadata to see a tree of parent nodes and how products are associated with the parent nodes. If your products are all in a hierarchy root node, no bread_crumbs metadata is generated.
- bread_crumb_nodes metadata to see a list of parent nodes a product is associated with.
To see the parent nodes that a node is associated with, use bread_crumb metadata. The bread_crumb metadata lists the parent nodes that the node is associated with.

Understanding `bread_crumbs` metadata for products

An example of bread_crumbs metadata is shown below.

{
    “data”: {
            “type”: “product”,
            “attributes”: {
            /*** other product attributes ommitted ***/
           "bread_crumbs": {
            "04e748f1-83db-4013-85c8-9edfb0e1b5fa": [
               "e5a64eae-56c2-48cd-b8b1-f5d3be734d52",
               "94b882fa-85de-470e-acb3-5b11358e02de"
           ],
            "a96a898b-444c-40b6-9c27-5fc74d08e685": [
               "e5a64eae-56c2-48cd-b8b1-f5d3be734d52"
          ]
       }
     }
   }
}

The following diagram illustrates how the parent nodes are listed in the bread_crumbs example above.

Breadcrumbs

The product is in Node 2. The ID for Node 2 is shown first in the first set of breadcrumbs.
Node 2 is part of Hierarchy 1. The ID for Hierarchy 1 is shown second.
Node 1 is the parent node of Node 2. The ID for Node 1 is shown last.
The product is also in Node 3. The ID for Node 3 is shown first in the second set of breadcrumbs.
Node 3 is in the root of Hierarchy 1. The ID for Hierarchy 1 is shown last.

In the bread_crumb_nodes metadata, you can see a list of parent nodes a product is associated with. If you subsequently add a product to a new node, then the bread_crumb_nodes metadata appends the new node to the top of the list. Using the example above, if we add the product to Node 1:

The bread_crumb_nodes metadata is generated to show the new node appended to the top of the list.
The bread_crumbs metadata is updated with the new node.

{
    “data”: {
            “type”: “product”,
            “attributes”: {
            /*** other product attributes ommitted ***/
            "bread_crumb_nodes": [
                "94b882fa-85de-470e-acb3-5b11358e02de",
                "04e748f1-83db-4013-85c8-9edfb0e1b5fa",
                "a96a898b-444c-40b6-9c27-5fc74d08e685"
             ],
             "bread_crumbs": {
                "04e748f1-83db-4013-85c8-9edfb0e1b5fa": [
                   "e5a64eae-56c2-48cd-b8b1-f5d3be734d52",
                   "94b882fa-85de-470e-acb3-5b11358e02de"
               ],
               "94b882fa-85de-470e-acb3-5b11358e02de": [
                   "e5a64eae-56c2-48cd-b8b1-f5d3be734d52"
               ],
               "a96a898b-444c-40b6-9c27-5fc74d08e685": [
                   "e5a64eae-56c2-48cd-b8b1-f5d3be734d52"
            ]
         }
      }
   }
}

Understanding `bread_crumb` metadata for nodes

An example of bread_crumb metadata is shown below.

{
    “data”: {
            “type”: “product”,
            “attributes”: {
            /*** other product attributes ommitted ***/
            {
            "bread_crumb": [
                "04e748f1-83db-4013-85c8-9edfb0e1b5fa",
                "94b882fa-85de-470e-acb3-5b11358e02de",
                "a96a898b-444c-40b6-9c27-5fc74d08e685"
            ]
         }
      }
   }
}

The following diagram illustrates how the nodes are listed in the bread_crumb example above.

Breadcrumb

The bread_crumb metadata is an array of nodes that the node is associated with.

Pricebooks

A price book contains the prices for each of the products in the catalog. You can create multiple price books for different scenarios, such as seasonal sales, business versus retail customer pricing, and reward programs. If you have multiple price books, when a catalog is published, you can configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books. See Create a catalog.

Publishing catalogs

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.

When a catalog is ready to be used in a store, you publish it. 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 Catalog View API.

The `Catalog` object

PCM. Identifies the catalog, its product hierarchies, and a price book.

Attribute	Type	Description
`id`	`string`	The unique identifier for the catalog.
`type`	`string`	The type of object being returned. Always: `catalog`
`attributes.name`	`string`	The name of the catalog.
`attributes.description`	`string`	A description of the catalog, such as the purpose for the catalog.
`attributes.hierarchy_ids`	`[string]`	The unique identifiers of the hierarchies to associate with this catalog.
`attributes.pricebook_id`	`string`	The unique identifier of the price book to associate with this catalog. If no price book is selected, the catalog is displayed without prices.
`attributes.created_at`	`string($date-time)`	The date and time the catalog was created.
`attributes.updated_at`	`string($date-time)`	The date and time the catalog was updated.
`attributes.published_at`	`string($date-time)`	If published, the date and time the catalog was published.
`links`	`object`	A URL to the catalog.

The `Release` Object

Attribute	Type	Description
`id`	`string`	A unique identifier for the node.
`type`	`string`	The type of object being returned. Always: `catalog-release`.
`attributes.hierarchy_ids`	`[array]`	An array of references to the hierarchies in the release.
`catalog_id`	`string`	A unique identifier for the catalog.
`attributes.description`	`string`	A description of the node, such as the name of a category.
`attributes.name`	`string`	The name of the release.
`attributes.published_at`	`string($date-time)`	The date and time the release was published.
`meta`	`object`	The `meta` data includes: `is_full_delta` (see publish a catalog), `created_at`, `release_status` and `started_at` attributes.
`relationships`	`object`	The `relationships` data for the catalog.

The `Links` object

PCM. A URL to a catalog, node, or product.

Attribute	Type	Description
`self`	`string`	Refers to the object that calls this object.

The `Rule` object

If you have multiple catalogs, add catalog rules. A catalog rule defines the circumstances under which you want to display a catalog to a customer. For example, the catalog rule could be preferred customers or mobile apps or both. If you create catalog rules, be sure to create a base catalog rule to use when no other catalog rule fits the shopper request. A base catalog rule is defined with a type, name, and catalog_id only.

note

If you have one catalog for all customers and channels, you can omit creating this object.

Attribute	Type	Description
`type`	`string`	The type of object being returned. Always: `catalog_rule`
`attributes.name`	`string`	The name of the rule without spaces.
`attributes.description`	`string`	The purpose for this rule.
`attributes.catalog_id`	`string`	The unique identifier for the catalog to display in this rule. V2 If you want to display a catalog that contains v2 Products, Brands, Categories, and Collections, specify `legacy`.
`attributes.account_ids`	`[array]`	Specifies the list of accounts who are eligible to see this catalog. If this field is empty, the rule matches all accounts.
`attributes.customer_ids`	`[array]`	The list of customers who are eligible to see this catalog. If empty, the rule matches all customers.
`attributes.channels`	`[array]`	The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.
`attributes.tags`	`[array]`	A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.
`attributes.schedules`	`[array]`	Specifies a time period when a catalog is displayed, such as on a specific date or during summer. Requests populate the rule tag using the `EP-Context-Tag` header. The `schedules` attribute must include `valid_from` and `valid_to`. `valid_from` matches the date and time that the catalog is displayed from. `valid_to` matches the date and time the catalog is displayed to. Elastic Path Commerce Cloud runs on UTC time. You can offset the timezone by adding the offset to the end of the date and time. For example, a catalog which contains a sale hierarchy that should appear for a set timeframe may be scheduled to publish on a given date and time within a given timezone. For instance, a sale that should begin on 1st of June 2022 05:00 ET and end on the 15th of June 2022 at 23:50 PT would have a valid schedule of `"valid_from": "2022-06-01T05:00:00.000-05:00",` `"valid_to": "2022-06-15T11:59:99.000-08:00"`

Resolving catalog rules

When there is a request for a catalog, the store displays the catalog with the rule that matches the most attributes of the shopperʼs context.

The request triggers the following steps:

Compares the shopperʼs context against the defined catalog rules.
Determines the best match.
Retrieves the catalog associated with the matching catalog rule.

The follow examples show how the best match might be resolved:

A shopper matches one of the customer_ids in one catalog rule only. The catalog for that catalog rule is displayed.
A shopper matches one of the customer_ids in one catalog rule only, but doesnʼt match any of the tags specified in that catalog rule. Because there are no other catalog rules for this customer_id, the catalog for the catalog rule is displayed because it is the best match.
A shopper is browsing a store using the storeʼs mobile app, which matches channel=mobile in two catalog rules. The catalog displayed depends on matches with the tags or customer_ids attributes. If there is no other matching attribute, the first catalog rule found by the store is used. The best practice is to create catalog rules that cover all cases so that you avoid this situation.
An unknown shopper is browsing the only channel offered by the seller. The store displays the base catalog.

EP PXM Catalogs with `v2/products`

You can use the EP PXM Catalogs to retrieve products associated with a legacy catalog. The hierarchies come from the brands, categories, and collections that are associated with the products. The prices are defined in the products, which means that the Price Book API is not supported with the v2/products resource.

important

To serve products and hierarchies created using v2/products from Catalog View, you must create a catalog rule with a legacy catalog.

To apply the catalog to all shoppers, set catalog_id=legacy and leave the other optional catalog rule fields empty.
To constrain the catalog to a subset of shoppers, set catalog_id=legacy and also set the channel, customer_ids, or tags as appropriate for your scenario.

For more information, see The Legacy Catalog Object. In the object descriptions, parameters that are unique to v2/products are identified with V2.

The Legacy Catalog object

V2. To support v2 Products, there is a predefined legacy catalog that you can use to retrieve the products for your store. You can use this catalog with catalog rules.

Attribute	Type	Description
`id`	`string`	Always: `legacy`
`type`	`string`	Always: `catalog`
`attributes.hierarchy_ids`	`[string]`	The unique identifiers of the Brand, Category, and Collection resources associated with the v2 Products.

EP PXM Catalogs with pcm/products

Hierarchies

Understanding How Products And Nodes Are Associated

Understanding bread_crumbs metadata for products

Understanding bread_crumb metadata for nodes

Pricebooks

Publishing catalogs

The Catalog object

The Release Object

The Links object

The Rule object

note

Resolving catalog rules

EP PXM Catalogs with v2/products

important

The Legacy Catalog object

EP PXM Catalogs with `pcm/products`

Understanding `bread_crumbs` metadata for products

Understanding `bread_crumb` metadata for nodes

The `Catalog` object

The `Release` Object

The `Links` object

The `Rule` object

EP PXM Catalogs with `v2/products`