Skip to navigation
RESTAdminCatalogCategory TreesCategories

Create Categories

Creates new categories.

Limits:

  • 16,000 categories per store limit.
  • 1,000 categories per product limit.
  • 50 characters category name length.
  • 8 levels of child categories depth limit.
  • 65,535 characters category description length limit.

Creating a category requires:

  • name
  • tree_id or parent_id
  • The url property is optional, but if included, its path must be unique per channel and category. If the path is not unique, the category will still be created but the URL will not — the response returns a multi-status to indicate the partial success.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI NamePermissionParameter
Productsmodifystore_v2_products
Productsread-onlystore_v2_products_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.

Path parameters

store_hashstringRequired
Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json

The MIME type of the response body.

Request

This endpoint expects a list of objects.
namestringRequired1-50 characters

The name displayed for the category. Name is unique with respect to the categoryʼs siblings. Required in a POST.

parent_idintegerRequired

The unique numeric ID of the category parent. To create a top-level category, specify the tree_id. Otherwise, you can specify the parent_id. Required in a POST if creating a child category.

tree_idintegerRequired

The ID of the category tree. To create a top-level category, specify the tree_id. Otherwise, you can specify the parent_id.

urlobjectOptional
If not provided in POST request, the URL is autogenerated from the category name.
descriptionstringOptional
The product description, which can include HTML formatting.
viewsintegerOptional
Number of views the category has on the storefront.
sort_orderintegerOptional-2147483648-2147483647
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.
page_titlestringOptional
Custom title for the category page. If not defined, the category name will be used as the meta title.
meta_keywordslist of stringsOptional

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”].

meta_descriptionstringOptional0-65535 characters

Custom meta description for the category page. If not defined, the storeʼs default meta description will be used.

layout_filestringOptional0-50 characters

A valid layout file. (Please refer to this article on creating category files.) This field is writable only for stores with a Blueprint theme applied.

image_urlstringOptional

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.

is_visiblebooleanOptional

Flag to determine whether the product should be displayed to customers browsing the store. If true, the category will be displayed. If false, the category will be hidden from view.

search_keywordsstringOptional0-255 characters

A comma-separated list of keywords that can be used to locate the category when searching the store.

default_product_sortenumOptional
Determines how the products are sorted on category page load.

Response

Created
datalist of objectsOptional
metaobjectOptional

Errors

400
Bad Request Error
403
Forbidden Error
422
Unprocessable Entity Error