For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
  • Overview
    • Quick Start
    • Sandboxes
    • Tools & SDKs
    • Support
  • Docs
    • Archive
          • SKU
          • Videos
          • Product Rules
          • Product Reviews
          • Product Options
          • Product Images
          • Option Values
          • Option Set Options
          • Option Sets
          • Options
          • Custom Fields
          • Categories
          • Bulk Pricing Rules
          • Products
          • Brands
    • Closed Beta Programs
Dev Portal
LogoLogo
On this page
  • Categories
  • Filters
  • Pagination
  • Response
  • Response
  • Response
  • Read-only Properties
  • Requirements
  • Request
  • Response
  • Read-only Properties
  • Requirements
  • Response
  • Delete Products before Categories
ArchiveStore OperationsCatalog V2 Products

Categories

Deprecated
Was this page helpful?
Previous

Custom Fields

Next

Bulk Pricing Rules

Built with

This is archived documentation. The V2 Catalog API is deprecated. For current API documentation, see the Catalog API.

Categories

Index of hierarchical categories used to organize and group products.

Category Object Properties
NameTypeDescription
idintA read-only field containing the unique numeric identifier of this category.
parent_idintThe ID of the parent category to which this category belongs.
(NOTE: the total number of parent categories cannot exceed seven.)
namestringThe name of the category. Must be unique.
descriptiontextA description for the category.
sort_orderintThe sort order of the category.
page_titlestringThe page title for the category page.
meta_keywordstextComma-separated list of meta keywords to include in the HTML.
meta_descriptiontextA meta description to include.
layout_filestringDEPRECATED. The layout template file used to render this category. This field is writable only for stores with a Blueprint theme applied. For Stencil stores, use the V3 Custom Templates API.
parent_category_listarrayA read-only field containing the ID of this category and the ID of its parent category, if any.
image_filestringA valid image.
is_visiblebooleanIs the category visible?
search_keywordsstringA comma-separated list of keywords that can be used to locate this brand.
urlstringThe context path of this category.
List Categories

Gets the list of categories. (Default sorting is by category id, from lowest to highest.)

GET /stores/{store_hash}/v2/categories

Filters

Filter parameters can be added to the URL query string to select specific categories in the collection.

ParameterTypeExample
parent_idstring/api/v2/categories?parent_id={value}
namestring/api/v2/categories?name={value}
is_visiblestring/api/v2/categories?is_visible={value}
min_idint/api/v2/categories?min_id={value}
max_idint/api/v2/categories?max_id={value}

Pagination

Parameters can be added to the URL query string to paginate the collection. The maximum limit is 250. If a limit isn’t provided, up to 50 categories are returned by default.

ParameterTypeExample
Pageint/api/v2/categories?page={number}
Limitint/api/v2/categories?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "parent_id": 0,
    "name": "Shop Mac",
    "description": "",
    "sort_order": 0,
    "page_title": "",
    "meta_keywords": "",
    "meta_description": "",
    "layout_file": "category.html",
    "parent_category_list": [
      1
    ],
    "image_file": "",
    "is_visible": true,
    "search_keywords": "",
    "url": "/shop-mac/"
  }
]
Get a Category

Gets a single category.

GET /stores/{store_hash}/v2/categories/{id}

Response

Example JSON returned in the response:

{
  "id": 10,
  "parent_id": 1,
  "name": "Xmen toys",
  "description": "",
  "sort_order": 2,
  "page_title": "",
  "meta_keywords": null,
  "meta_description": null,
  "layout_file": "category.html",
  "parent_category_list": [
    1,
    10
  ],
  "image_file": "d/apiy2uz6q__69888.jpg",
  "is_visible": true,
  "search_keywords": "",
  "url": "/xmen-toys/"
}
Get a Count of Categories

Gets a count of the total number of categories in the store.

GET /stores/{store_hash}/v2/categories/count

Response

Example JSON returned in the response:

{
  "count": 10
}
Create a Category

Creates a new category.

POST /stores/{store_hash}/v2/categories

Read-only Properties

The following properties of the category are read-only. If one or more of these properties are included in the request, it will be rejected.

  • id
  • parent_category_list

Requirements

The following properties of the category are required. The request won’t be fulfilled unless these properties are valid.

  • name

Note

To maximize system performance, BigCommerce caps the number of categories that can be added to a store at 16,000. If your POST causes the store to exceed the maximum of 16,000 categories, BigCommerce will return a 403 error.

In addition, BigCommerce caps the total number of parent categories at seven. If your POST includes the ID of a parent category in the parent_id field, BigCommerce will check that parent category and its parent and so on to determine the total number of parent categories. If your POST would cause the total number of parent categories to exceed seven, BigCommerce will return a 403 error.

Request

Example request object:

{
  "name": "Xmen toys"
}

Response

Example JSON returned in the response:

{
  "id": 10,
  "parent_id": 1,
  "name": "Xmen toys",
  "description": "",
  "sort_order": 2,
  "page_title": "",
  "meta_keywords": null,
  "meta_description": null,
  "layout_file": "category.html",
  "parent_category_list": [
    1,
    10
  ],
  "image_file": "d/apiy2uz6q__69888.jpg",
  "is_visible": true,
  "search_keywords": "",
  "url": "/xmen-toys/"
}
Update a Category

Updates an existing category.

PUT /stores/{store_hash}/v2/categories/{id}

Read-only Properties

The following properties of the category are read-only. If one or more of these properties are included in the request, it will be rejected.

  • id
  • parent_category_list

Requirements

The following properties of the category are required. The request won’t be fulfilled unless these properties are valid.

Note

To maximize system performance, BigCommerce caps the total number of parent categories at seven. If your PUT includes the ID of a parent category in the parent_id field, BigCommerce will check the parent and any children of the current category to determine the total number of parent categories. If your PUT would cause the total number of parent categories to exceed the maximum of seven, BigCommerce will return a 403 error.

Response

Example JSON returned in the response:

{
  "id": 10,
  "parent_id": 1,
  "name": "Xmen toys",
  "description": "",
  "sort_order": 2,
  "page_title": "",
  "meta_keywords": null,
  "meta_description": null,
  "layout_file": "category.html",
  "parent_category_list": [
    1,
    10
  ],
  "image_file": "d/apiy2uz6q__69888.jpg",
  "is_visible": true,
  "search_keywords": "",
  "url": "/xmen-toys/"
}
Delete a Category

Deletes a category.

DELETE /stores/{store_hash}/v2/categories/{id}

Delete Products before Categories

The Delete All Categories operation will not succeed unless the store has zero products. If any products in the store belong to any categories, the entire operation will fail. Therefore, if you really want to delete all the categories of the store, you must first delete all of the products in the store.

Delete All Categories

Deletes all the categories in the store.

DELETE /stores/{store_hash}/v2/categories