Categories (deprecated)
Get All Categories
GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categoriesRequest
When possible, use the Catalog Trees - Get all categories endpoint instead.
Returns a list of Categories. Optional filter parameters can be passed in.
Note: The default rate limit for this endpoint is 40 concurrent requests.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
example
Response
Body
dataarray[]
example
Create a Category
POST https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categoriesRequest
When possible, use the Category Trees - Create categories endpoint instead.
Creates a Category.
Use this endpoint when an API only works with categories of a default BigCommerce storefront (channel_id=1
).
Use the Create categories endpoint when an API works with categories across different category trees that belong to different storefront channels.
Required Fields:
parent_id
:- To create a child category, set the
parent_id
to the parent category. - To create a top level category, set the
parent_id
to0
.
- To create a child category, set the
name
Read-Only Fields:
id
Limits:
- 16,000 categories per store limit.
- 1,000 categories per product limit.
- 50 characters category name length.
- 8 levels of category depth limit.
- 65,642 characters category description length limit.
Note: The default rate limit for this endpoint is 40 concurrent requests.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
Body
Common Category object properties.
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: 2namestring
required>= 1 characters<= 50 charactersThe name displayed for the category. The name must be unique with respect to the category of siblings on the same level (you can duplicate the name for other siblings on another level). Required in a POST.
Example: Bathdescriptionstring
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: 1050sort_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.
Min: -2147483648Max: 2147483647Example: 3page_titlestring
>= 0 characters<= 255 charactersCustom title for the category page. If not defined, the category name will be used as the meta title.
Example: Bathsearch_keywordsstring
>= 0 characters<= 255 charactersA comma-separated list of keywords that can be used to locate the category when searching the store.
layout_filestring
>= 0 characters<= 500 charactersA valid layout file. Please refer to the article on creating category files (Help Center). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see Custom Template Associations.
Example: category.htmlis_visibleboolean
Flag to determine whether the category should be displayed to customers browsing the store. If
true
, the category will be displayed. Iffalse
, the category will be hidden from view.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
image_urlstring
Image URL used for this category on the storefront. Images can be uploaded using form file post to
/categories/{categoryId}/image
, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required.Example: https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.pngcustom_urlobject
The custom URL for the category on the storefront. If not provided, the URL will be autogenerated from the category name.
example
Response
Body
dataobject
Common Category object properties.
example
Delete Categories
DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categoriesRequest
When possible, use the Category Trees - Delete categories endpoint instead.
Deletes Category objects. At least one filter parameter is required to perform the DELETE
operation.
Usage Notes
- Sending a
DELETE
request without specifying a filter parameter will result in a422
error. - Sending a
DELETE
request for a category that contains products will result in a422
error. Move products to a new category by sending aPUT
request to the/catalog/products/{product_id}
endpoint before deleting a category.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
example
Response
Get a Category
GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categories/{category_id}Request
When possible, use the Catalog Trees - Get all categories endpoint instead. You can provide a category identifier using query parameters to retrieve a single category.
Returns a single Category. Optional parameters can be passed in.
Note: The default rate limit for this endpoint is 40 concurrent requests.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
example
Response
Body
dataobject
Common Category object properties.
example
Update a Category
PUT https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categories/{category_id}Request
When possible, use the Catalog Trees - Update categories endpoint instead.
Updates a Category.
Required Fields
- none
Read-Only Fields
- id
Note: The default rate limit for this endpoint is 40 concurrent requests.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
Body
Common Category object properties.
idinteger
read-onlyUnique ID of the Category. Increments sequentially. Read-Only.
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: 2namestring
required>= 1 characters<= 50 charactersThe name displayed for the category. The name must be unique with respect to the category of siblings on the same level (you can duplicate the name for other siblings on another level). Required in a POST.
Example: Bathdescriptionstring
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: 1050sort_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.
Min: -2147483648Max: 2147483647Example: 3page_titlestring
>= 0 characters<= 255 charactersCustom title for the category page. If not defined, the category name will be used as the meta title.
Example: Bathsearch_keywordsstring
>= 0 characters<= 255 charactersA comma-separated list of keywords that can be used to locate the category when searching the store.
layout_filestring
>= 0 characters<= 500 charactersA valid layout file. Please refer to the article on creating category files (Help Center). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see Custom Template Associations.
Example: category.htmlis_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.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
image_urlstring
Image URL used for this category on the storefront. Images can be uploaded using form file post to
/categories/{categoryId}/image
, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required.Example: https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.pngcustom_urlobject
The custom URL for the category on the storefront.
example
Response
Body
dataobject
Common Category object properties.
example
Delete a Category
DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categories/{category_id}Request
When possible, use the Category Trees - Delete categories endpoint instead. You can provide a category identifier using query parameters to delete a single category.
Deletes a Category.
Note: The default rate limit for this endpoint is 40 concurrent requests.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string