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 headerrequired
Parameters
- store_hash in path - string
- category_uuid:in in query - array
Filter using a comma-separated list of one or more category UUIDs. To use category IDs, use the
category_id:in
parameter.Type: array[string] - category_id:in in query - array
Filter using a comma-separated list of one or more category IDs. To use category UUIDs, use the
category_uuid:in
parameter.Type: array[integer] - tree_id:in in query - array
Filter using a comma-separated list of one or more category tree IDs.
Type: array[integer] - parent_id:in in query - arrayType: array[integer]
- category_uuid:not_in in query - array
Filter using a comma-separated list to exclude one or more category UUIDs. To exclude using category IDs, use the
category_id:not_in
parameter.Type: array[string] - category_id:not_in in query - array
Filter using a comma-separated list to exclude one or more category IDs. To exclude using category UUIDs, use the
category_uuid:not_in
parameter.Type: array[integer] - tree_id:not_in in query - array
Filter using a comma-separated list to exclude one or more category tree IDs.
Type: array[integer] - parent_id:not_in in query - arrayType: array[integer]
- page_title in query - string
Filter items by page_title.
- page_title:like in query - string
Filter items by substring in the page title property.
page_title:like=oil
returns bothSoil and mulch
andOil pastels
. - name in query - string
Filter items by name.
- name:like in query - string
Filter items by substring in the name property.
name:like=stick
returns bothStickers
andLipstick colors
. - keyword in query - string
Filter items by keywords found in the
name
,description
, orsku
fields, or in the brand name. - is_visible in query - boolean
Filter items based on whether the product is currently visible on the storefront.
- include_fields in query - array
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
Type: array[string] - exclude_fields in query - array
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
Type: array[string] - page in query - integer
Specifies the page number in a limited (paginated) list of products.
- limit in query with default of 50 - integer
Controls the number of items per page in a limited (paginated) list of products.
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 headerrequired
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - stringrequired
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.
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 headerrequired
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - stringrequired
The MIME type of the request body.
Body
category_idinteger
requiredread-onlyUnique 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.
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 headerrequired
Parameters
- store_hash in path - string
- category_uuid:in in query - array
Filter using a comma-separated list of one or more category UUIDs. To use category IDs, use the
category_id:in
parameter.Type: array[string] - category_id:in in query - array
Filter using a comma-separated list of one or more category IDs. To use category UUIDs, use the
category_uuid:in
parameter.Type: array[integer] - tree_id:in in query - array
Filter using a comma-separated list of one or more category tree IDs.
Type: array[integer] - parent_id:in in query - arrayType: array[integer]
example
Response
Categories are deleted
Body
metaobject