openapi: 3.0.0
info:
title: Product Catalog
description: >-
As brands and retailers grow, they often expand their item catalogs,
resulting in the need to enrich and manage more product (commonly referred
to as item in fabric) data. fabric Product Catalog alleviates the burden of
managing large amounts of item data by means of a central storage
repository. fabric Product Catalog helps you with improved data quality,
consistent customer experience, reduced time to market, easy integration
with external systems, reduced management costs and risks, faster and easier
updates, and easy scaling. You can create, import, enrich, validate,
distribute, and manage complex item information, centrally. As a result, you
deliver product experiences that drive sales through every channel. <br />
<br /> During onboarding, you are given the necessary credentials to access
Product Catalog - Copilot UI, APIs, or both. As a prerequisite, you create
the items to be sold, identify their unique as well as common properties,
and envision their organization into categories and sub categories. A basic
workflow is: <br /> 1) **Create item attributes** using POST
/api-product/v1/product/attribute/bulk. <br /> 2) **Update attribute
mapping** using POST /api-product/v1/product/attribute/mapping <br /> 3)
**Create Primary category** using the POST /api-category/v1/category to
create the original organizational structure. <br /> 4) **Assign item
attributes** to Primary category using POST
/api-category/v1/category/item-attribute. <br /> 5) **Create items** using
POST /api-product/v1/product/bulk/insert. <br /> 6) **Create Alternate
category**, for distribution management and fulfilling various merchandising
objectives.
version: 2.0.0
contact:
email: [email protected]
license:
name: fabric API License
url: https://fabric.inc/api-license
tags:
- name: Category
description: >-
Categories (also called hierarchies or nodes) are hierarchical structures
to organize items and services into intuitive groups. Organizing items in
this way simplifies item discovery and lifecycle management. There are two
types of categories - **Primary** and **Alternate**. They enable you to
create, organize, and distribute item data. - Primary category is the
original catalog tree with nested levels of categories that place each
item where it belongs, within a category. For example, `Computers` is a
parent category with `Laptops` and `Desktops` as children categories, and
`MacBook Pro` is an item within `Laptops`. This organization can be
represented as Computers > Laptops > MacBook Pro. - Alternate categories
serve as alternate organizations of the Primary category. Their main
purpose is distribution management by displaying items on your website
based on separate browsing structure configurations you set to help you
achieve various merchandizing objectives, such as organizational
requirements, multi-regional assortments, multi-channel assortments, and
collections. For example, a company that sells, repairs, and supports
computers and related items and services will have a Primary category
containing a full list of their SKUs. However, this Primary category is
not granular enough to use on their storefront. Hence, multiple Alternate
hierarchies are created to target specific shopper segment experiences.
For laptop consumers they'll have one Alternate category, which lists all
the laptops and PCs. For large businesses they'll have another Alternate
category, which lists all commercial laptops, PCs, printers, and servers.
Both of the Alternate categories act as filters of the Primary category,
tailored to the purpose of that merchandising strategy. **Category**, a
subset of Product Catalog endpoints, aims to simplify catalog management
by letting you create, update, and get one or more categories, category
attributes, and item attributes. In addition, you can add and update
category sources, source exclusions, and item attribute conditions.
**Note**: The root name of primary category is PRIMARY, and it cannot be
changed.
- name: Product
description: >-
**Product**, a subset of Product Catalog endpoints, aims at making item
management more efficient. They create, update, and get items, which may
be individual items or collection of items (called bundles). Each item has
a title, item ID, description, category, and assigned attributes. Multiple
options of a given item become variants of that item. For example, a
t-shirt with three sizes may have small, medium, and large variants. Each
variant has its own item ID, attributes, and other data points. Each
variant is nested under its parent item, allowing the different options to
appear on the same product page. You can also create or update one or more
item attributes and attribute groups.
- name: Attributes
description: >-
Item attributes are the objective and factual descriptions of items that
shoppers see when they browse through your site. Attributes may be
technical specifications like size, weight, etc., design specifications
like color, material, etc., or basic specifications like name,
description, and ID. Ites attributes are crucial as they directly
influence purchasing decisions. Complete and correct item information help
shoppers narrow down their search and filter items with minimal cognitive
load.
- name: Bulk Import
description: >-
Set of endpoints to help bulk import of items, bundles, categories and
attributes through CSV files
externalDocs:
description: Find out more about Product Catalog
url: /v3/product-catalog/user-guides/product-catalog/overview
servers:
- url: https://live.copilot.fabric.inc
description: Production
paths:
/api-category/v1/category:
post:
tags:
- Category
summary: Create Category
description: >-
Creates Primary or Alternate category to organize items into logical
groups. <br /> **Note**: <br /> 1) To add **Primary** category, only
`name` is required in the request. <br /> 2) To add a **child**
category, both `name` and `parentNodeId` are required. For **child**
category, you can additionally specify `order` of display. <br /> 3) To
add an **Alternate** category, both `name` and `type` are required. <br
/> **Note**: Category details including category ID received in the
response are required for subsequent calls. For example, it's required
to *Create item* (POST /v1/product/bulk/insert).
operationId: categoryCreate
security:
- authorization: []
- api_key: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCategoryRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyCategory'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
get:
tags:
- Category
summary: Get Categories
description: >-
Gets categories and their details including attributes, breadcrumbs, and
details of children categories. <br /> **Note**: <br /> 1) Specify
either `ids` or `nodeIds` to get specific categories. <br /> 2) Use
`type` to get a specific category type. <br /> 3) When query parameters
are omitted, this endpoint returns a paginated response listing all
Alternate categories in Active status. Using the query parameters `size`
and `page`, you can narrow down the search results.
operationId: getCategoriesById
security:
- authorization: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
- in: query
name: ids
description: >-
A 24-character system-generated category IDs. If `ids` and `nodeIds`
are omitted, this endpoint returns all Alternate categories in
Active status. Using `size` and `page`, you can narrow down the
search results.
example:
- 6196b45b5cb04b7ce167cb46
- 7196b45b5cb04b7ce167cb45
explode: false
schema:
type: array
items:
type: string
- in: query
name: nodeIds
description: >-
Numeric category IDs. When `ids` and `nodeIds` are omitted, specify
`size` and `page` to narrow down the search results.
example:
- 123
- 234
explode: false
schema:
type: array
items:
type: number
- in: query
name: keyword
description: >-
Keywords to search for categories. You will get a pagination
response. Using `size` and `page`, you can narrow down the search
results.
example: computers
schema:
type: string
- in: query
name: type
description: >-
Category type. <br /> **Note**: When omitted, you will get
`ALTERNATE` categories by default.
schema:
type: string
enum:
- PRIMARY
- ALTERNATE
- ALL
example: ALL
- in: query
name: status
description: >-
Category status. <br /> **Note**: If omitted, you will get Alternate
categories in Active status by default. <br /> **Note**: When `type`
is Primary, `status` must be Active. Inactive status is not
applicable for Primary category.
schema:
type: string
enum:
- ACTIVE
- INACTIVE
- ALL
example: ALL
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryPage'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
/api-category/v1/category/{nodeId}:
put:
tags:
- Category
summary: Modify Category
description: >-
Updates category details such as name, parent, and its order of
appearance amongst sibling categories.
operationId: categoryModify
security:
- authorization: []
- api_key: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
- in: path
name: nodeId
required: true
description: Numeric category ID
example: 1204
schema:
type: number
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyCategoryRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyCategory'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
/api-category/v1/category/search:
get:
tags:
- Category
summary: Find Categories
description: >-
Finds categories, by keywords, category identifiers, type, or status.
<br /> **Note**: <br /> 1) Categories and children categories must
already exist in the system. <br /> 2) When query parameters are
omitted, this endpoint returns a paginated response with all the
categories. Using `size` and `page`, you can narrow down the search
results. <br /> 3) GET /v1/category (Store admin context) or Algolia
search (Shopper context) is strongly recommended over this endpoint.
operationId: searchCategories
security:
- authorization: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
- in: query
name: keyword
description: >-
Keywords to search for categories. The response is paginated. Using
query parameters `page` and `size`, you can narrow down the search
results.
example: computers
schema:
type: string
- in: query
name: ids
description: >-
A 24-characters system-generated category IDs. If `ids` and
`nodeIds` are omitted, this endpoint returns a paginated response.
Using query parameters `page` and `size`, you can narrow down the
search results.
example:
- 6196b45b5cb04b7ce167cb46
- 7196b45b5cb04b7ce167cb47
explode: false
schema:
type: array
items:
type: string
- in: query
name: nodeIds
description: >-
Numeric category IDs. If `ids` and `nodeIds` are omitted, this
endpoint returns a paginated response. Using query parameters `page`
and `size`, you can narrow down the search results.
example:
- 15
- 16
explode: false
schema:
type: array
items:
type: number
- in: query
name: type
description: >-
Category type. <br /> **Note**: If omitted, you will get a paginated
response with `ALL` categories. Using query parameters `page` and
`size`, you can narrow down the search results.
schema:
type: string
enum:
- PRIMARY
- ALTERNATE
- ALL
example: ALL
- in: query
name: status
description: >-
Category status. If omitted, you will get a paginated response of
categories in `ACTIVE` status. Using the query parameters `page` and
`size`, you can narrow down the search results. <br /> **Note**:
When `type` is Primary, `status` must be Active. Inactive status is
not applicable for Primary category.
schema:
type: string
enum:
- ACTIVE
- INACTIVE
- ALL
example: ALL
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryPage'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
/api-category/v1/category/tree:
get:
tags:
- Category
summary: Get Category Tree
description: >-
Hierarchy of parent and children categories form a tree structure. This
endpoint returns a tree of categories rooted in the category identified
by `id` or `nodeId`.<br /> **Note**: <br /> 1) If parent category does
not exist in the system, you'll get a `404 - Not found` error <br /> 2)
If a child category does not exist for the given parent, you'll get a
success response but `children` property will show a blank array.
operationId: getCategoryTree
security:
- authorization: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
- in: query
name: id
description: >-
A 24-character system-generated ID of root category. Either `id` or
`nodeId` must be specified.
example: 6196b44a5cb04b7ce167cb34
schema:
type: string
- in: query
name: nodeId
description: Numeric category ID. Either `id` or `nodeId` must be specified.
example: 12
schema:
type: integer
- in: query
name: depth
description: >-
Limits the size of the hierarchical category tree returned in the
response. Depth of 0 means no children categories, attributes, or
breadcrumbs, are included in the response. Unless depth is
specified, entire category is returned up to the last set of
categories (that have no more children categories).
example: 1
schema:
type: number
- in: query
name: excludeAttributes
description: >-
Set `true` to exclude attributes from both parent and children
objects or false to include attributes in both parent and children
details. <br /> The default setting false.
example: true
schema:
type: boolean
- in: query
name: excludeBreadcrumbs
description: >-
Set `true` to exclude breadcrumbs from both parent and children
objects or false to include breadcrumbs in both parent and children
details. <br /> The default setting false.
example: true
schema:
type: boolean
- in: query
name: excludeItemIds
description: >-
Set `true` to exclude item IDs from both parent and children objects
or false to include item IDs in both parent and children details.
<br /> The default setting false.
example: true
schema:
type: boolean
- in: query
name: onlyIncludeAttributes
description: >-
Attributes are included based on their exact, case-sensitive names.
For example, if you specify the values as xyZ and Abc, the response
will include these attributes in both parent and child objects.
schema:
type: array
items:
type: string
example:
- Category Image
- Category Type
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryTree'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
/api-category/v1/category/sku:
get:
tags:
- Category
summary: Get Skus in a Category
description: >-
Gets SKUs of all items belonging to a category. <br /> **Note**: <br />
1) Categories must exist in the system to get SKUs in that category. If
SKUs are not available in the given category ID, this endpoint returns
an empty list.
operationId: getCategorySKUs
security:
- authorization: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
- in: query
name: id
description: >-
A 4-character system-generated category ID. Either `id` or `nodeId`
must be specified.
example: 6196b45b5cb04b7ce167cb46
schema:
type: string
- in: query
name: nodeId
description: Numeric category ID. Either `id` or `nodeId` must be specified.
example: 2
schema:
type: integer
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SKUPage'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
/api-category/v1/category/attribute:
post:
tags:
- Category
summary: Assign and Unassign Category Attributes
description: >-
Category attributes let you define characteristics of categories and
children categories. <br /> This endpoint assigns or unassigns
attributes of a single category. The primary purpose is to assign
attributes.
operationId: postCategoryAttributeByID
security:
- authorization: []
- api_key: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyCategoryAttributesRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryAttributes'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
get:
tags:
- Category
summary: Get Assigned Category Attributes
description: >-
Gets all attributes assigned to a category. <br /> **Note**: <br /> *Get
category* endpoint (GET /v1/category) returns categories, their
attributes, children categories, and breadcrumb details. So, this
endpoint is recommended if you have a category ID and only require its
attributes.
operationId: getCategoryAttributesByID
security:
- authorization: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
- in: query
name: id
description: >-
A 24-character system-generated category ID. Either `id` or `nodeId`
must be specified.
example: 619a8ba6f1875f6dbcaf0521
schema:
type: string
- in: query
name: nodeId
description: Numeric category ID. Either `nodeId` or `id` must be specified.
example: 2
schema:
type: integer
- in: query
name: status
description: >-
Attribute status. When `id` or `nodeId` is specified along with
`status` = `Assigned`, the response is faster because the data is
fetched from cache. When the `status` is `Unassigned`, the data is
fetched from the DB and the response could take longer.
schema:
type: string
enum:
- ASSIGNED
- UNASSIGNED
example: ASSIGNED
- $ref: '#/components/parameters/MandatoryPage'
- $ref: '#/components/parameters/MandatorySize'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AttributePage'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
/api-category/v1/category/item-attribute:
post:
tags:
- Category
summary: Assign and Unassign Item Attributes
description: >-
Categories are used to segregate and group items. You can specify
`mandatory` and `optional` attributes that all items within that
category must have. Attributes are used to store structured information
about items. <br /> Use this endpoint to create and manage item
attributes for the specified category.
operationId: postCategoryItemibuteByID
security:
- authorization: []
- api_key: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyCategoryItemAttributesRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryItemAttributes'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
get:
tags:
- Category
summary: Get Assigned Item Attributes
description: >-
Gets all the item attributes for the specified category. <br />
**Note**: Items may also inherit item attributes from parent categories.
operationId: getCategoryItemAttributes
security:
- authorization: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
- in: query
name: id
description: >-
A 24-character system-generated category ID. `id` and `nodeId` are
the two identifiers of a category. <br /> **Note**: If `id` is
specified, `status` must be specified as well.
example: 6196b45b5cb04b7ce167cb46
schema:
type: string
- in: query
name: nodeId
description: >-
Numeric category ID. `id` and `nodeId` are the two identifiers of a
category. <br /> **Note**: If `nodeId` is specified, `status` must
be specified as well.
example: 25
schema:
type: number
- in: query
name: status
description: >-
Status of item attributes. `Assigned` indicates item attributes are
already assigned to categories and `unassigned` indicates otherwise.
Applicable only when `id` or `nodeId` is specified.
schema:
type: string
enum:
- ASSIGNED
- UNASSIGNED
- $ref: '#/components/parameters/MandatoryPage'
- $ref: '#/components/parameters/MandatorySize'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetCategoryItemAttributes'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
/api-category/v1/category/source:
post:
tags:
- Category
summary: Add and Remove Category Source Inclusions
description: >-
Adds and removes category sources. <br /> Primary category is the
original catalog tree consisting of nested levels of children categories
and is used to place items where they belong. Alternate categories are
dynamic and populated from the Primary category, which is the original
source of items. Source for an Alternate category points to a Primary
category, and makes all items in the Primary category appear within the
Alternate category; it behaves like a symlink.
operationId: modifyCategoriesNodeSources
security:
- authorization: []
- api_key: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyNodeSourcesRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NodeSourcesAndExclusions'
'400':
description: client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
get:
tags:
- Category
summary: Get Category Source Inclusions
description: >-
Gets all the available category sources. <br /> Items are created under
the Primary category, and Alternate categories are created to export
alternate organizations of the Primary category. So, the Primary
category is the source of items that appear in Alternate categories. The
category sources are Primary categories that can be used as item sources
in Alternate categories. Sources behave similar to symlinks.
operationId: getCategoriesNodeSources
security:
- authorization: []
parameters:
- $ref: '#/components/parameters/xSiteContent'
- in: query
name: id
description: >-
A 24-character system-generated category ID. `id` and `nodeId` are
the two identifiers of a category and one of them must be specified.
schema:
type: string
example: 6170135a49b4af38190970fe
- in: query
name: nodeId
description: >-
Numeric category ID. `id` and `nodeId` are the two identifiers of a
category and one of them must be specified.
schema:
type: number
example: 12
- in: query
name: status
description: >-
Status of Category source. If omitted, 'ASSIGNED' status is used as
default.
schema:
type: string
enum:
- ASSIGNED
- UNASSIGNED
example: ASSIGNED
- $ref: '#/components/parameters/MandatoryPage'
- $ref: '#/components/parameters/MandatorySize'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NodeSources'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: Internal server error
content:
# --- truncated at 32 KB (219 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-pim-openapi.yml