Catalog - Category Trees
Get All Categories
GET /stores/{store_hash}/v3/catalog/trees/categories
Request
Returns a list of categories.
To get a specific category in a tree, provide a category ID.
Authentication
- X-Auth-Token in header - required
Parameters
- store_hash in path - string
- Accept in header with default of application/json - string - required
The MIME type of the response body.
- category_uuid:in in query - string
- category_uuid:not_in in query - string
- category_id:in in query - string
- category_id:not_in in query - string
- tree_id:in in query - string
- tree_id:not_in in query - string
- parent_id:in in query - string
- parent_id:not_in in query - string
- name in query - string
- name:like in query - string
- page_title in query - string
- page_title:like in query - string
- keyword in query - string
- is_visible in query - boolean
- page in query - integer
- limit in query - integer
- include_fields in query - string
- exclude_fields in query - string
example
Response
List of categories.
Body
dataarray[object]
metaobject
Get Category 12
Create Categories
POST /stores/{store_hash}/v3/catalog/trees/categories
Request
Creates new categories.
Creating a category requires:
name
tree_id
orparent_id
Authentication
- X-Auth-Token in header - required
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - string - required
The MIME type of the request body.
Body
namestring
required>= 1 characters<= 50 charactersThe name displayed for the category. Name is unique with respect to the categoryʼs siblings. Required in a POST.
Example: Bath
urlobject
If not provided, the URL is autogenerated from the category name.
parent_idinteger
requiredThe unique numeric ID of the categoryʼs parent. This field controls where the category sits in the tree of categories that organize the catalog. Required in a POST if creating a child category.
Example: 0
tree_idinteger
requiredThe ID of the Category Tree.
Example: 1
descriptionstring
The product description, which can include HTML formatting.
Example: <p>We offer a wide variety of products perfect for relaxing</p>
viewsinteger
Number of views the category has on the storefront.
Example: 1050
sort_orderinteger
Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be.
Example: 3
page_titlestring
Custom title for the category page. If not defined, the category name will be used as the meta title.
Example: Bath
meta_keywordsarray[string]
Custom meta keywords for the category page. If not defined, the storeʼs default keywords will be used. Must post as an array like: ["awesome","sauce"].
Type: array[string]Example: ["shower","tub"]meta_descriptionstring
>= 0 characters<= 65535 charactersCustom meta description for the category page. If not defined, the storeʼs default meta description will be used.
layout_filestring
>= 0 characters<= 500 charactersA valid layout file. (Please refer to this article on creating category files.) This field is writable only for stores with a Blueprint theme applied.
Example: category.html
image_urlstring
Image URL used for this category on the storefront. Images can be uploaded via form file post to
/categories/{categoryId}/image
, or by providing a publicly accessible URL in this field. Must be either a full-qualified URL or an empty string.Example: https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png
is_visibleboolean
Flag to determine whether the product should be displayed to customers browsing the store. If
true
, the category will be displayed. Iffalse
, the category will be hidden from view.search_keywordsstring
A comma-separated list of keywords that can be used to locate the category when searching the store.
default_product_sortstring
Determines how the products are sorted on category page load.
Allowed: use_store_settings | featured | newest | best_selling | alpha_asc | alpha_desc | avg_customer_review | price_asc | price_desc
example
Response
Created
Body
dataarray[object]
metaobject
Create Category 36
Update Categories
PUT /stores/{store_hash}/v3/catalog/trees/categories
Request
Updates existing categories.
To update a specific category in a tree, provide a category id.
Authentication
- X-Auth-Token in header - required
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - string - required
The MIME type of the request body.
Body
category_idinteger
requiredUnique ID of the Category. Increments sequentially. Read-Only.
Example: 36
namestring
>= 1 characters<= 50 charactersThe name displayed for the category. Name is unique with respect to the categoryʼs siblings. Required in a POST.
Example: Bath
tree_idinteger
The ID of the Category Tree.
Example: 1
parent_idinteger
The unique numeric ID of the categoryʼs parent. This field controls where the category sits in the tree of categories that organize the catalog. Required in a POST if creating a child category.
Example: 0
descriptionstring
The product description, which can include HTML formatting.
Example: <p>We offer a wide variety of products perfect for relaxing</p>
viewsinteger
Number of views the category has on the storefront.
Example: 1050
sort_orderinteger
Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be.
Example: 3
page_titlestring
Custom title for the category page. If not defined, the category name will be used as the meta title.
Example: Bath
meta_keywordsarray[string]
Custom meta keywords for the category page. If not defined, the storeʼs default keywords will be used. Must post as an array like: ["awesome","sauce"].
Type: array[string]Example: ["shower","tub"]meta_descriptionstring
>= 0 characters<= 65535 charactersCustom meta description for the category page. If not defined, the storeʼs default meta description will be used.
layout_filestring
>= 0 characters<= 500 charactersA valid layout file. (Please refer to this article on creating category files.) This field is writable only for stores with a Blueprint theme applied.
Example: category.html
image_urlstring
Image URL used for this category on the storefront. Images can be uploaded via form file post to
/categories/{categoryId}/image
, or by providing a publicly accessible URL in this field. Must be either a full-qualified URL or an empty string.Example: https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png
is_visibleboolean
Flag to determine whether the product should be displayed to customers browsing the store. If
true
, the category will be displayed. Iffalse
, the category will be hidden from view.search_keywordsstring
A comma-separated list of keywords that can be used to locate the category when searching the store.
default_product_sortstring
Determines how the products are sorted on category page load.
Allowed: use_store_settings | featured | newest | best_selling | alpha_asc | alpha_desc | avg_customer_review | price_asc | price_desc
urlobject
If not provided, the URL is autogenerated from the category name.
example
Response
OK
Body
metaobject
example
Delete Categories
DELETE /stores/{store_hash}/v3/catalog/trees/categories
Request
Deletes categories.
To delete a specific category in a tree, provide a category ID.
Authentication
- X-Auth-Token in header - required
Parameters
- store_hash in path - string
- Accept in header with default of application/json - string - required
The MIME type of the response body.
- category_uuid:in in query - string
- category_id:in in query - string
- tree_id:in in query - string
- parent_id:in in query - string
example
Response
Categories are deleted
Body
metaobject