Categories | BigCommerce Dev Center

Catalog - Categories

The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the Catalog Overview.

Our Catalog Categories endpoints let you create individual categories and modify categories that organize a store's products, as well as delete categories.

Category images have their own dedicated create a category image and delete a category image endpoints.

In addition, categories have metafields that you can use to store information structured in key-value pairs; learn more about creating category metafields, updating category metafields, and deleting category metafields.

This API family also contains endpoints to update product sort order within a category.

These endpoints are primarily useful in applications for single storefront stores. To work with categories for an MSF-enabled store, see Category Trees.

To learn more about authenticating Catalog endpoints, locate the Authentication section at the top of each endpoint, then click Show Details.

Resources

Webhooks

Learn more about Category webhook events.

Additional Catalog endpoints

Get All Categories

GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categories

Request

Returns a list of Categories. Optional filter parameters can be passed in.

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.
id in query - integer
Filter items by id.
id:in in query - array
id:not_in in query - array
id:min in query - array
id:max in query - array
id:greater in query - array
id:less in query - array
name in query - string
Filter items by name.
name:like in query - array
parent_id in query - integer
Filter items by parent_id. If the category is a child or sub category it can be filtered with the parent_id.
parent_id:in in query - array
parent_id:min in query - array
parent_id:max in query - array
parent_id:greater in query - array
parent_id:less in query - array
page_title in query - string
Filter items by page_title.
page_title:like in query - array
keyword in query - string
Filter items by keywords. eg. new, towel, bath
is_visible in query - boolean
Filter items by if visible on the storefront.
page in query - integer
Specifies the page number in a limited (paginated) list of products.
limit in query - integer
Controls the number of items per page in a limited (paginated) list of products.
include_fields in query - string
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
exclude_fields in query - string
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/categories' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

dataarray[object]
metaobject
Data about the response, including pagination and collection totals.

example

{
  "data": [
    {
      "id": 19,
      "parent_id": 0,
      "name": "Garden",
      "description": "<p>This is the garden description</p>",
      "views": 0,
      "sort_order": 2,
      "page_title": "page title",
      "meta_keywords": [
        "meta keyword"
      ],
      "meta_description": "meta description",
      "layout_file": "category.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "search keywords",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/garden/",
        "is_customized": false
      }
    },
    {
      "id": 20,
      "parent_id": 0,
      "name": "Publications",
      "description": "",
      "views": 0,
      "sort_order": 4,
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "layout_file": "category_with_facets.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/publications/",
        "is_customized": false
      }
    },
    {
      "id": 21,
      "parent_id": 0,
      "name": "Kitchen",
      "description": "",
      "views": 0,
      "sort_order": 3,
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "layout_file": "category_with_facets.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/kitchen/",
        "is_customized": false
      }
    },
    {
      "id": 22,
      "parent_id": 0,
      "name": "Utility",
      "description": "",
      "views": 0,
      "sort_order": 5,
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "layout_file": "category_with_facets.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/utility/",
        "is_customized": false
      }
    },
    {
      "id": 23,
      "parent_id": 0,
      "name": "Shop All",
      "description": "",
      "views": 0,
      "sort_order": 0,
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "layout_file": "category_with_facets.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/shop-all/",
        "is_customized": false
      }
    },
    {
      "id": 39,
      "parent_id": 19,
      "name": "Bath",
      "description": "",
      "views": 0,
      "sort_order": 0,
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "layout_file": "category.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/garden/bath/",
        "is_customized": false
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 6,
      "count": 6,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?page=1&limit=50"
      }
    }
  }
}

Create a Category

POST https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categories

Request

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 to 0.
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.

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

object | application/json

Common Category object properties.

parent_idinteger
required
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: 2
namestring
required
The name displayed for the category. Name is unique with respect to the category's siblings. Required in a POST.
>= 1 characters<= 50 characters
Example: Bath
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.
>= 0 characters<= 255 characters
Example: Bath
search_keywordsstring
A comma-separated list of keywords that can be used to locate the category when searching the store.
>= 0 characters<= 255 characters
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"].
meta_descriptionstring
Custom meta description for the category page. If not defined, the store's default meta description will be used.
>= 0 characters<= 65535 characters
layout_filestring
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. For stores with a Stencil theme applied, see Custom Template Associations.
>= 0 characters<= 500 characters
Example: category.html
is_visibleboolean
Flag to determine whether the category should be displayed to customers browsing the store. If true, the category will be displayed. If false, 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 via 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.png
custom_urlobject
The custom URL for the category on the storefront.

example

{
  "parent_id": 2,
  "name": "Bath",
  "description": "<p>We offer a wide variety of products perfect for relaxing</p>",
  "views": 1050,
  "sort_order": 3,
  "page_title": "Bath",
  "search_keywords": "string",
  "meta_keywords": [
    "string"
  ],
  "meta_description": "string",
  "layout_file": "category.html",
  "is_visible": true,
  "default_product_sort": "use_store_settings",
  "image_url": "https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png",
  "custom_url": {
    "url": "/shoes",
    "is_customized": true
  }
}

Response

Body

object | application/json

dataobject
Common Category object properties.
metaobject
Response metadata.

example

{
  "data": {
    "parent_id": 2,
    "name": "Bath",
    "description": "<p>We offer a wide variety of products perfect for relaxing</p>",
    "views": 1050,
    "sort_order": 3,
    "page_title": "Bath",
    "search_keywords": "string",
    "meta_keywords": [
      "string"
    ],
    "meta_description": "string",
    "layout_file": "category.html",
    "is_visible": true,
    "default_product_sort": "use_store_settings",
    "image_url": "https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png",
    "custom_url": {
      "url": "string",
      "is_customized": true
    }
  },
  "meta": {}
}

Delete Categories

DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categories

Request

Deletes Category objects. At least one filter parameter is required to perform the DELETE operation.

Usage Notes

Sending a DELETErequest without specifying a filter parameter will result in a 422 error.
Sending a DELETE request for a category that contains products will result in a 422 error. Move products to a new category by sending a PUT request to the /catalog/products/{product_id} endpoint before deleting a category.

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.
id in query - integer
Filter items by id.
id:in in query - array
id:not_in in query - array
id:min in query - array
id:max in query - array
id:greater in query - array
id:less in query - array
name in query - string
Filter items by name.
parent_id in query - integer
Filter items by parent_id. If the category is a child or sub category it can be filtered with the parent_id.
page_title in query - string
Filter items by page_title.
keyword in query - string
Filter items by keywords. eg. new, towel, bath
is_visible in query - boolean
Filter items by if visible on the storefront.
name:like in query - array
parent_id:in in query - array
parent_id:min in query - array
parent_id:max in query - array
parent_id:greater in query - array
parent_id:less in query - array
page_title:like in query - array

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/categories' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Get a Category

GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categories/{category_id}

Request

Returns a single Category. Optional parameters can be passed in.

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_id in path - integer - required
The ID of the Category to which the resource belongs.
category_id in path - integer - required
The ID of the Category to which the resource belongs.
include_fields in query - string
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
exclude_fields in query - string
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/categories/[category_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

dataobject
Common Category object properties.
metaobject
Response metadata.

example

{
  "data": {
    "parent_id": 2,
    "name": "Bath",
    "description": "<p>We offer a wide variety of products perfect for relaxing</p>",
    "views": 1050,
    "sort_order": 3,
    "page_title": "Bath",
    "search_keywords": "string",
    "meta_keywords": [
      "string"
    ],
    "meta_description": "string",
    "layout_file": "category.html",
    "is_visible": true,
    "default_product_sort": "use_store_settings",
    "image_url": "https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png",
    "custom_url": {
      "url": "string",
      "is_customized": true
    }
  },
  "meta": {}
}

Update a Category

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categories/{category_id}

Request

Updates a Category.

Required Fields

none

Read-Only Fields

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.
category_id in path - integer - required
The ID of the Category to which the resource belongs.

Body

object | application/json

Common Category object properties.

idinteger
Unique ID of the Category. Increments sequentially. Read-Only.
parent_idinteger
required
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: 2
namestring
required
The name displayed for the category. Name is unique with respect to the category's siblings. Required in a POST.
>= 1 characters<= 50 characters
Example: Bath
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.
>= 0 characters<= 255 characters
Example: Bath
search_keywordsstring
A comma-separated list of keywords that can be used to locate the category when searching the store.
>= 0 characters<= 255 characters
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"].
meta_descriptionstring
Custom meta description for the category page. If not defined, the store's default meta description will be used.
>= 0 characters<= 65535 characters
layout_filestring
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. For stores with a Stencil theme applied, see Custom Template Associations.
>= 0 characters<= 500 characters
Example: category.html
is_visibleboolean
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.
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 via 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.png
custom_urlobject
The custom URL for the category on the storefront.

example

{
  "parent_id": 2,
  "name": "Bath",
  "description": "<p>We offer a wide variety of products perfect for relaxing</p>",
  "views": 1050,
  "sort_order": 3,
  "page_title": "Bath",
  "search_keywords": "string",
  "meta_keywords": [
    "string"
  ],
  "meta_description": "string",
  "layout_file": "category.html",
  "is_visible": true,
  "default_product_sort": "use_store_settings",
  "image_url": "https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png",
  "custom_url": {
    "url": "/shoes",
    "is_customized": true
  }
}

Response

Body

object | application/json

dataobject
Common Category object properties.
metaobject
Empty meta object; may be used later.

example

{
  "data": {
    "parent_id": 2,
    "name": "Bath",
    "description": "<p>We offer a wide variety of products perfect for relaxing</p>",
    "views": 1050,
    "sort_order": 3,
    "page_title": "Bath",
    "search_keywords": "string",
    "meta_keywords": [
      "string"
    ],
    "meta_description": "string",
    "layout_file": "category.html",
    "is_visible": true,
    "default_product_sort": "use_store_settings",
    "image_url": "https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png",
    "custom_url": {
      "url": "/shoes",
      "is_customized": true
    }
  },
  "meta": {}
}

Delete a Category

DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categories/{category_id}

Request

Deletes a Category.

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_id in path - integer - required
The ID of the Category to which the resource belongs.
category_id in path - integer - required
The ID of the Category to which the resource belongs.

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/categories/[category_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Catalog - Categories

Resources

Webhooks

Additional Catalog endpoints

Get All Categories

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

example

Create a Category

Request

Authentication

Parameters

Body

parent_idintegerrequired

namestringrequired

descriptionstring

viewsinteger

sort_orderinteger

page_titlestring

search_keywordsstring

meta_keywordsarray[string]

meta_descriptionstring

layout_filestring

is_visibleboolean

default_product_sortstring

image_urlstring

custom_urlobject

example

Response

Body

dataobject

metaobject

example

Delete Categories

Request

Authentication

Parameters

example

Response

Get a Category

Request

Authentication

Parameters

example

Response

Body

dataobject

metaobject

example

Update a Category

Request

Authentication

Parameters

Body

idinteger

parent_idintegerrequired

namestringrequired

descriptionstring

viewsinteger

sort_orderinteger

page_titlestring

search_keywordsstring

meta_keywordsarray[string]

meta_descriptionstring

layout_filestring

is_visibleboolean

default_product_sortstring

image_urlstring

custom_urlobject

example

Response

Body

dataobject

metaobject

parent_idinteger
required

namestring
required

parent_idinteger
required

namestring
required