EP PXM Catalogs API
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.
pcm/products
EP PXM Catalogs with 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.
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. Thebread_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, nobread_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. Thebread_crumb
metadata lists the parent nodes that the node is associated with.
bread_crumbs
metadata for products
Understanding 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.
- 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"
]
}
}
}
}
bread_crumb
metadata for nodes
Understanding 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.
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.
Catalog
object
The 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. |
Release
Object
The 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. |
Links
object
The PCM. A URL to a catalog, node, or product.
Attribute | Type | Description |
---|---|---|
self | string | Refers to the object that calls this object. |
Rule
object
The 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 thetags
specified in that catalog rule. Because there are no other catalog rules for thiscustomer_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 thetags
orcustomer_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.
v2/products
EP PXM Catalogs with 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 thechannel
,customer_ids
, ortags
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. |