Elastic Path Catalogs API
A catalog contains the products available for sale either in your organization or store. A catalog also contains information about how to organize those products for navigation menus and search facets in a shopper experience. Before you create a catalog you must define the following resources: - Hierarchies: hierarchies and nodes to categorize the products. See [**Hierarchies**](/docs/api/pxm/products/hierarchies). - Products: product information, associated assets, and links to hierarchy nodes. See [**Products**](/docs/api/pxm/products/products). - Price Books: prices for the products associated with the hierarchies. See [**Price Books**](/docs/api/pxm/pricebooks). A catalog is a combination of hierarchies and a price book. ### Products Commerce automatically assigns types to the products you create. Product types can be used in catalogs. For example, in your catalog, you can filter on `parent` so that only your parent products are displayed in your storefront. You can use product tags to store or assign a key word against a product or service that you sell in your store. The product tag can then be used to describe or label that product. Product tags represent similarities between products who do not share the same attributes. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. Product tags can be used in catalogs. For example, you can categorize your products based on color. Your shoppers can then search your products by color, enabling shoppers to quickly find what they are looking for, increasing the likelihood of a purchase, and boosting conversion rates. ### Hierarchies The hierarchies determine which products appear in the catalog, that is, only the products that are associated with the selected hierarchies are included in the 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 [**create a Catalog**](/docs/api/pxm/catalog/create-catalog). #### Understanding How Products And Nodes Are Associated You can use `breadcrumb` metadata to understand how products and nodes are associated. it explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within your store. The `breadcrumb` information that you get in an endpoint response depends on whether the endpoint is retrieving product or node details. | Object | Product/Node | Description | | --- | --- | --- | | `breadcrumb` | Node | A list of nodes that a product is associated with. Up to 10 levels of nodes are displayed, depending on the number of levels of nodes you have. | | `bread_crumbs` | Product | The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of nodes are displayed, depending on the number of levels of nodes you have. | | `bread_crumb_nodes` | Product | An array of parent node IDs that a product is associated with. The `bread_crumb_node` metadata lists up to 10 levels of parent nodes, depending on the number of levels of parent nodes you have. | #### Understanding `bread_crumbs` Metadata The following diagram illustrates a parent and child nodes.  1. The product is in **Node 2**. The ID for **Node 2** is shown first in the first set of breadcrumbs. 1. **Node 2** is part of **Hierarchy 1**. The ID for **Hierarchy 1** is shown second. 1. **Node 1** is the parent node of **Node 2**. The ID for **Node 1** is shown last. 1. The product is also in **Node 3**. The ID for **Node 3** is shown first in the second set of breadcrumbs. 1. **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**: 1. The `bread_crumb_nodes` metadata is generated to show the new node appended to the top of the list. 1. The `bread_crumbs` metadata is updated with the new node. #### Understanding Breadcrumb Metadata for Child Products When a catalog is published, the breadcrumb information for a child product includes the metadata mentioned for the parent product, in addition to the information specific to the child product. For example, **Product A** is the parent product, associated with **Node 1** and **Node 2**. The metadata for child **Product B** includes **Node 1** and **Node 2**, in addition to its own metadata information. ### Nodes The nodes determine which products appear under this in the catalog, that is, only the products that are associated with the selected node are shown under this node. ### Price books 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. When creating a catalog, you can specify up to five price books. You must set 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](/docs/api/pxm/catalog/create-catalog).
Documentation
Specifications
openapi: 3.1.0
info:
version: 25.1126.6886238
x-version-timestamp: 2025-11-26 19:10:23+00:00
title: Addresses Introduction Account Addresses Catalogs API
description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.
You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.
'
contact:
name: Elastic Path
url: https://www.elasticpath.com
email: support@elasticpath.com
license:
url: https://elasticpath.dev
name: MIT
servers:
- url: https://useast.api.elasticpath.com
description: US East
- url: https://euwest.api.elasticpath.com
description: EU West
security:
- BearerToken: []
tags:
- name: Catalogs
description: 'A catalog contains the products available for sale either in your organization or store. A catalog also contains information about how to organize those products for navigation menus and search facets in a shopper experience.
Before you create a catalog you must define the following resources:
- Hierarchies: hierarchies and nodes to categorize the products. See [**Hierarchies**](/docs/api/pxm/products/hierarchies).
- Products: product information, associated assets, and links to hierarchy nodes. See [**Products**](/docs/api/pxm/products/products).
- Price Books: prices for the products associated with the hierarchies. See [**Price Books**](/docs/api/pxm/pricebooks).
A catalog is a combination of hierarchies and a price book.
### Products
Commerce automatically assigns types to the products you create. Product types can be used in catalogs. For example, in your catalog, you can filter on `parent` so that only your parent products are displayed in your storefront.
You can use product tags to store or assign a key word against a product or service that you sell in your store. The product tag can then be used to describe or label that product. Product tags represent similarities between products who do not share the same attributes. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. Product tags can be used in catalogs. For example, you can categorize your products based on color. Your shoppers can then search your products by color, enabling shoppers to quickly find what they are looking for, increasing the likelihood of a purchase, and boosting conversion rates.
### Hierarchies
The hierarchies determine which products appear in the catalog, that is, only the products that are associated with the selected hierarchies are included in the 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 [**create a Catalog**](/docs/api/pxm/catalog/create-catalog).
#### Understanding How Products And Nodes Are Associated
You can use `breadcrumb` metadata to understand how products and nodes are associated. it explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within your store.
The `breadcrumb` information that you get in an endpoint response depends on whether the endpoint is retrieving product or node details.
| Object | Product/Node | Description |
| --- | --- | --- |
| `breadcrumb` | Node | A list of nodes that a product is associated with. Up to 10 levels of nodes are displayed, depending on the number of levels of nodes you have. |
| `bread_crumbs` | Product | The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of nodes are displayed, depending on the number of levels of nodes you have. |
| `bread_crumb_nodes` | Product | An array of parent node IDs that a product is associated with. The `bread_crumb_node` metadata lists up to 10 levels of parent nodes, depending on the number of levels of parent nodes you have. |
#### Understanding `bread_crumbs` Metadata
The following diagram illustrates a parent and child nodes.
1. The product is in **Node 2**. The ID for **Node 2** is shown first in the first set of breadcrumbs.
1. **Node 2** is part of **Hierarchy 1**. The ID for **Hierarchy 1** is shown second.
1. **Node 1** is the parent node of **Node 2**. The ID for **Node 1** is shown last.
1. The product is also in **Node 3**. The ID for **Node 3** is shown first in the second set of breadcrumbs.
1. **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**:
1. The `bread_crumb_nodes` metadata is generated to show the new node appended to the top of the list.
1. The `bread_crumbs` metadata is updated with the new node.
#### Understanding Breadcrumb Metadata for Child Products
When a catalog is published, the breadcrumb information for a child product includes the metadata mentioned for the parent product, in addition to the information specific to the child product. For example, **Product A** is the parent product, associated with **Node 1** and **Node 2**. The metadata for child **Product B** includes **Node 1** and **Node 2**, in addition to its own metadata information.
### Nodes
The nodes determine which products appear under this in the catalog, that is, only the products that are associated with the selected node are shown under this node.
### Price books
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. When creating a catalog, you can specify up to five price books. You must set 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](/docs/api/pxm/catalog/create-catalog).
'
paths:
/catalogs:
post:
tags:
- Catalogs
summary: Creates a new catalog
description: 'Before you create a catalog, you must define the following resources:
- Hierarchies - hierarchies and nodes to categorize the products.
- Products - product information, associated assets, and links to hierarchy nodes.
- Price Books - prices for the products associated with the hierarchies. You can create multiple price books for different scenarios, such as seasonal sales, business versus retail customer pricing, and reward programs. When creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books. Priority is a number and the price book with the highest number has the highest priority.
'
operationId: createCatalog
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/catalog-create-data'
description: Creates a catalog with the following attributes.
required: true
responses:
'201':
description: The created catalog
content:
application/json:
schema:
$ref: '#/components/schemas/catalog-data'
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
get:
tags:
- Catalogs
summary: Gets all authorized catalogs
description: 'Retrieves a list of all the catalogs that you are authorized to view. Currently, published catalogs are limited to the current release and two releases prior to the current release. You can see the differences between the last 2 consecutive catalog releases using the delta link returned in the response of a [publish a catalog](/docs/api/pxm/catalog/publish-release) endpoint.
You can use the `is_full_delta` attribute returned from the `get a release of a catalog` endpoint to determine if you need to refresh the data in your company system before publishing a catalog release and injecting fresh data in a delta link. The `is_full_delta` attribute tells you if this is a full publish of a catalog release. Using a search service as an example, if the `is_full_delta` attribute is `true`, you should remove all data about that catalog from the search service before publishing a catalog release and injecting fresh data from the delta file. See [Publish a catalog](/docs/api/pxm/catalog/publish-release).
If the `is_full_publish` attribute returned in the response is `false`, data from the previous catalog release overlaid the existing data in the delta file. The `is_full_publish` attribute is always `true` the first time a catalog is published. When determining whether delta data needs to be refreshed, ignore this attribute and always use the `is_full_delta` attribute.
### Filtering
This endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available when filtering on this endpoint.
| Operator | Description | Supported Attributes | Example |
|:---|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--- |
| `eq` | Checks if the values of two operands are equal. If they are, the condition is true. | `name`, | `filter=eq(name,some-name)` |
| `in` | Checks if the values are included in the specified list. If they are, the condition is true. | `name` | `filter=in(name,some-name,some-name2)` |
| `like` | Checks if the operand contains the specified string. Wildcards are supported | `name` | `filter=like(name,*some-name*)` |
'
operationId: getCatalogs
parameters:
- $ref: '#/components/parameters/filter-catalog'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: The list of catalogs.
content:
application/json:
schema:
$ref: '#/components/schemas/catalog-list-data'
default:
description: An unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
/catalogs/{catalog_id}:
get:
tags:
- Catalogs
summary: Get a catalog by ID
description: Retrieves the specified catalog.
operationId: getCatalogByID
parameters:
- description: The catalog ID.
name: catalog_id
in: path
required: true
schema:
type: string
responses:
'200':
description: The catalog.
content:
application/json:
schema:
$ref: '#/components/schemas/catalog-data'
default:
description: An unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
put:
tags:
- Catalogs
summary: Updates a catalog
description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the catalog is not updated.
operationId: updateCatalog
parameters:
- description: The catalog ID.
name: catalog_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/catalog-update-data'
description: Updated catalog.
required: true
responses:
'200':
description: An updated catalog with the following attributes.
content:
application/json:
schema:
$ref: '#/components/schemas/catalog-data'
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
delete:
tags:
- Catalogs
summary: Deletes a catalog
description: Deletes an unpublished catalog. Use [**Delete a Release**](/docs/api/pxm/catalog/delete-release-by-id) and [**Delete All Releases**](/docs/api/pxm/catalog/delete-releases) to delete releases of a catalog. If the catalog is associated with any catalog rules, you must first update the catalog rules to remove the catalog.
operationId: deleteCatalogByID
parameters:
- description: The catalog ID.
name: catalog_id
in: path
required: true
schema:
type: string
responses:
'204':
description: A 204 response indicates that the catalog has been deleted.
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
components:
schemas:
catalog:
type: object
title: Catalog
description: Creates a catalog with the following attributes.
properties:
id:
type: string
description: A unique identifier of a catalog.
example: 8dbb35b2-ef04-477e-974d-e5f3abe6faae
attributes:
type: object
properties:
name:
description: The name of a catalog.
type: string
example: catalog-123
description:
description: A brief description of the catalog, such as the purpose of the catalog.
type: string
example: Catalog for Store 123
default: ''
hierarchy_ids:
description: The unique identifiers of the hierarchies associated with a catalog.
type: array
items:
type: string
pricebook_id:
description: The unique identifier of a price book associated with a catalog. If no price book is selected, the catalog is displayed without prices.
type: string
pricebook_ids:
$ref: '#/components/schemas/prioritized-pricebooks'
locales:
description: Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.
type: object
additionalProperties:
description: A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.
type: object
additionalProperties:
description: A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.
type: string
created_at:
description: The date and time a catalog is created.
type: string
example: '2020-09-22T09:00:00'
format: date-time
updated_at:
description: The date and time a catalog was updated.
type: string
example: '2020-09-22T09:00:00'
format: date-time
owner:
description: The owner of this resource, can be either `organization` or `store`.
type: string
enum:
- store
- organization
x-go-name: Owner
default: store
nullable: true
enable_price_segmentation:
description: This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing
type: boolean
example: true
default: false
x-go-name: EnablePriceSegmentation
include_draft_products:
description: When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).
type: boolean
example: false
default: false
x-go-name: IncludeDraftProducts
required:
- name
- hierarchy_ids
- created_at
- updated_at
relationships:
description: Relationships are established between different catalog entities. For example, a catalog rule and a price book are related to a catalog, as both are associated with it.
type: object
title: CatalogRelationships
properties:
rules:
description: The catalog rules related to a catalog.
type: object
properties:
links:
$ref: '#/components/schemas/related-link'
releases:
description: When a catalog is published, a catalog release is created. This is a URL to all catalog published releases available for this catalog.
type: object
properties:
links:
$ref: '#/components/schemas/related-link'
meta:
type: object
properties:
count:
description: The number releases available for a catalog.
type: integer
type:
type: string
example: catalog
enum:
- catalog
required:
- id
- type
- attributes
error:
type: object
title: APIError
description: APIError is a json-api style part of an error response.
properties:
detail:
type: string
example: not processable
x-go-name: Detail
status:
type: string
example: '422'
x-go-name: Status
title:
type: string
example: There was a problem processing your request.
x-go-name: Title
x-go-name: APIError
page-meta:
type: object
description: Contains the results for the entire collection.
title: PageMeta
properties:
results:
description: Total number of results for the entire collection.
type: object
properties:
total:
description: Total number of results for the entire collection.
type: integer
format: int64
page:
type: object
properties:
limit:
description: The maximum number of records for all pages.
type: integer
format: int64
offset:
description: The current offset by number of pages.
type: integer
format: int64
current:
description: The current number of pages.
type: integer
format: int64
total:
description: The total number of records for the entire collection.
type: integer
format: int64
error-response:
type: object
title: ErrorResponse
description: ErrorResponse is a json-api style Error response.
properties:
errors:
type: array
items:
$ref: '#/components/schemas/error'
x-go-name: Errors
x-go-name: ErrorResponse
catalog-data:
type: object
title: CatalogData
description: Container for a single catalog.
properties:
data:
$ref: '#/components/schemas/catalog'
links:
$ref: '#/components/schemas/links'
required:
- data
prioritized-pricebooks:
description: If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.
type: array
maxItems: 5
items:
type: object
properties:
id:
description: A unique identifier of a price book.
type: string
format: uuid
priority:
description: Priority is a number and the price book with the highest number has the highest priority.
type: integer
required:
- priority
- id
x-go-name: PrioritizedPricebook
catalog-update-data:
type: object
title: CatalogUpdateData
description: A catalog combines price books, product lists, and hierarchies.
properties:
data:
type: object
properties:
attributes:
type: object
properties:
name:
description: The name of the catalog.
type: string
minLength: 1
example: catalog-123
nullable: true
description:
description: A brief description of the catalog.
type: string
example: Catalog for Store 123
nullable: true
hierarchy_ids:
description: The unique identifiers of the hierarchies to associate with a catalog.
type: array
items:
type: string
nullable: true
pricebook_id:
description: The unique identifier of a price book to associate with a catalog. You can specify a `pricebook_id` or a `pricebook_ids` but not both. If you specify both, a `422 unprocessable entity` error is displayed.
type: string
nullable: true
pricebook_ids:
$ref: '#/components/schemas/prioritized-pricebooks'
locales:
description: Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.
type: object
additionalProperties:
description: A [three-letter language code](https://www.loc.gov/standards/iso639-2/) that represents the name of language you have used.
type: object
additionalProperties:
description: A [three-letter language code](https://www.loc.gov/standards/iso639-2/) that represents the name of language you have used.
type: string
enable_price_segmentation:
description: This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing
type: boolean
example: true
default: false
x-go-name: EnablePriceSegmentation
include_draft_products:
description: When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).
type: boolean
example: false
default: false
x-go-name: IncludeDraftProducts
id:
description: The unique identifier of the catalog to be updated.
type: string
x-go-name: ID
example: 8dbb35b2-ef04-477e-974d-e5f3abe6faae
type:
description: This represents the type of object being returned. Always `catalog`.
type: string
example: catalog
enum:
- catalog
required:
- type
- id
- attributes
required:
- data
catalog-list-data:
type: object
title: CatalogListData
description: Container for a list of catalogs.
properties:
data:
type: array
items:
$ref: '#/components/schemas/catalog'
meta:
$ref: '#/components/schemas/page-meta'
links:
$ref: '#/components/schemas/links'
required:
- data
catalog-create-data:
type: object
title: CatalogCreateData
description: Creates a catalog with the following attributes.
properties:
data:
type: object
properties:
attributes:
type: object
properties:
name:
description: The name of the catalog.
type: string
minLength: 1
example: catalog-123
description:
description: A brief description of the catalog.
type: string
example: Catalog for Store 123
nullable: true
hierarchy_ids:
description: The unique identifiers of the hierarchies to associate with a catalog.
type: array
items:
type: string
pricebook_id:
description: 'The unique identifier of the price book to associate with this catalog. You can specify either a `pricebook_id` or `pricebook_ids` but not both. If you specify both a `pricebook_id` and `pricebook_ids`, a `422 Unprocessable Entity` error is displayed.
'
type: string
pricebook_ids:
$ref: '#/components/schemas/prioritized-pricebooks'
locales:
description: Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.
type: object
additionalProperties:
description: A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.
type: object
additionalProperties:
description: A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.
type: string
enable_price_segmentation:
description: This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing
type: boolean
example: true
default: false
x-go-name: EnablePriceSegmentation
include_draft_products:
description: When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).
type: boolean
example: false
default: false
x-go-name: IncludeDraftProducts
required:
- name
- hierarchy_ids
type:
description: Represents the type of object being returned. Always `Catalog`.
type: string
example: catalog
enum:
- catalog
required:
- type
- attributes
required:
- data
related-link:
description: A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.
type: object
properties:
related:
description: A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.
type: string
required:
- related
links:
description: Links allow you to move between requests.
type: object
properties:
self:
description: Single entities use a `self` parameter with a link the specific resource.
type: string
format: uri
nullable: true
first:
description: Always the first page.
type: string
format: uri
nullable: true
last:
description: This is `null` if there is only one page.
type: string
format: uri
nullable: true
prev:
description: This is `null` if there is only one page.
type: string
format: uri
nullable: true
next:
description: This is `null` if there is only one page.
type: string
format: uri
nullable: true
parameters:
offset:
description: The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.
name: page[offset]
in: query
required: false
schema:
type: integer
format: int64
minimum: 0
maximum: 10000
limit:
description: The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.
name: page[limit]
in: query
required: false
schema:
type: integer
format: int64
minimum: 1
filter-catalog:
name: filter
in: query
description: 'This endpoint supports filtering, see [Filtering](#filtering).
'
required: false
schema:
type: string
securitySchemes:
BearerToken:
type: http
scheme: bearer