> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fabric.inc/llms.txt
> Use this file to discover all available pages before exploring further.
# Get category tree
> 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`.
**Note**:
1) If parent category does not exist in the system, you'll get a `404 - Not found` error
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.
## OpenAPI
````yaml pim get /api-category/v1/category/tree
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.
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:
1) **Create item attributes** using POST
/api-product/v1/product/attribute/bulk.
2) **Update attribute
mapping** using POST /api-product/v1/product/attribute/mapping
3)
**Create Primary category** using the POST /api-category/v1/category to
create the original organizational structure.
4) **Assign item
attributes** to Primary category using POST
/api-category/v1/category/item-attribute.
5) **Create items** using
POST /api-product/v1/product/bulk/insert.
6) **Create Alternate
category**, for distribution management and fulfilling various merchandising
objectives.
version: 2.0.0
contact:
email: support@fabric.inc
license:
name: fabric API License
url: https://fabric.inc/api-license
servers:
- url: https://live.copilot.fabric.inc
description: Production
security: []
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
paths:
/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`.
**Note**:
1) If parent category does
not exist in the system, you'll get a `404 - Not found` error
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
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.
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.
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.
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'
security:
- authorization: []
components:
parameters:
xSiteContent:
name: x-site-context
in: header
description: >-
The `x-site-context` header is a JSON object that contains information
about the source you wish to pull from. The mandatory `account` is the
24 character identifier found in Copilot. The `channel` (Sales channel
ID), `stage` (environment name), and `date` attributes can be used to
further narrow the scope of your data source.
required: true
schema:
type: string
example: >-
{"date": "2023-01-01T00:00:00.000Z", "channel": 12, "account":
"1234abcd5678efgh9ijklmno","stage":"production"}
schemas:
CategoryTree:
type: object
properties:
id:
description: A 24-character system-generated category ID
type: string
example: 6196b45b5cb04b7ce167cb46
nodeId:
description: Numeric category ID
type: number
example: 16
name:
description: Category name
type: string
example: PCs
hierarchy:
description: Category type
type: string
enum:
- PRIMARY
- ALTERNATE
example: ALTERNATE
isActive:
description: >-
true: Category is Active
false: Category is Inactive
**Note**: Inactive status is not applicable for Primary category.
type: boolean
example: true
attributes:
description: Details of attributes belonging to this category
type: array
items:
$ref: '#/components/schemas/Attribute'
children:
description: Children categories of this category
type: array
items:
$ref: '#/components/schemas/CategoryChild'
createdOn:
type: string
example: '2022-03-09T23:37:54.086Z'
description: Time of category creation (UTC format)
modifiedOn:
type: string
description: Time when category was last updated (UTC format)
example: '2022-03-09T23:37:54.086Z'
ClientError:
type: object
properties:
code:
description: Error code for machine consumption
type: string
example: 400
message:
description: Human-readable error description
type: string
example: Client error
ServerError:
type: object
properties:
code:
description: Error code
type: string
example: 500
message:
description: Human-readable error description
type: string
example: >-
An internal error occurred. If the issue persists please contact
support@fabric.inc.
Attribute:
type: object
properties:
id:
description: A 24-character system-generated attribute ID
type: string
example: 619a8ba6f1875f6dbcaf0521
name:
description: Attribute name
type: string
example: notes
description:
type: string
description: Attribute description
example: Notes for this particular category.
type:
type: string
enum:
- TEXT
- BOOLEAN
- SERIAL
- DECIMAL
- INTEGER
- DATETIME
example: TEXT
value:
type: string
example: Unable to fulfill demand.
description: Value corresponding to `type`
CategoryChild:
type: object
properties:
id:
description: A 24-character system-generated category ID
type: string
example: 619973877a22c466eee93219
name:
description: Category name
type: string
example: Apple
breadcrumbs:
description: Path of categories leading to root of categories
type: array
items:
$ref: '#/components/schemas/Breadcrumbs'
attributes:
description: Attributes and their details
type: array
items:
$ref: '#/components/schemas/Attribute'
children:
description: Details of children categories
type: array
items:
$ref: '#/components/schemas/CategoryChild'
Breadcrumbs:
type: object
properties:
id:
description: A 24-character system-generated category ID
type: string
example: 6196b44a5cb04b7ce167cb34
nodeId:
type: number
example: 10
description: Numeric category ID
name:
description: Category name
type: string
example: Computers
level:
description: Depth below the root of the tree
type: number
example: 0
hierarchy:
description: Category type
type: string
enum:
- PRIMARY
- ALTERNATE
example: ALTERNATE
isActive:
description: >-
true: Category is Active
false: Category is Inactive
**Note**: Inactive status is not applicable for Primary category.
type: boolean
example: true
createdOn:
type: string
example: '2022-03-09T23:37:54.086Z'
description: Time of category creation (UTC format)
modifiedOn:
type: string
description: Time when category was last updated (UTC format)
example: '2022-03-09T23:37:54.086Z'
securitySchemes:
authorization:
type: http
scheme: bearer
bearerFormat: JWT
description: S2S access token (JWT) from fabric Identity service (during Login)
````