Category

Introduction

Categories are a hierarchy of products available on the store, presented in a tree structure. A store’s category structure determines the primary menu structure of most storefront themes, which are directly tied to it.

All products must be associated with at least one Category, although a Category does not need to contain any products. Unlike some e-commerce platforms, products on BigCommerce can be associated with more than one Category.

A product associated with categories does not currently have any priority or weighted order (there’s no “primary category”), which can make it difficult to integrate with some external systems which might wish to use a product’s categories to map to a category structure in that external system.

Try It Now

Create a Category. Replace the test data with your own.

Send requests directly from the browser (CORS must be enabled)

Path Params

1 path param not set

store_hash

$$.env

No $$.env variables are being used in this request.

OAuth Scopes

Products

Available Webhooks

Category

Related Endpoints

Get Categories

Object Properties

object

Common Category object properties.

parent_id

integer

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 /POST if creating a child category.

required

example: 2

name

string

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

required

minLength: 1

maxLength: 50

example: Bath

description

string

The product description, which can include HTML formatting.

example: <p>We offer a wide variety of products perfect for relaxing</p>

views

integer

Number of views the category has on the storefront.

example: 1050

sort_order

integer

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.

minimum: -2147483648

maximum: 2147483647

example: 3

page_title

string

Custom title for the category page. If not defined, the category name will be used as the meta title.

minLength: 0

maxLength: 255

example: Bath

search_keywords

string

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

minLength: 0

maxLength: 65535

meta_keywords

array[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_description

string

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

minLength: 0

maxLength: 65535

layout_file

string

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.

minLength: 0

maxLength: 500

example: category.html

is_visible

boolean

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_sort

string

Determines how the products are sorted on category page load.

Allowed Values: use_store_settings, featured, newest, best_selling, alpha_asc, alpha_desc, avg_customer_review, price_asc, price_desc

image_url

string

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.

x-url: true

example: https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png

custom_url

object

The custom URL for the category on the storefront.

url

string

Category URL on the storefront.

5 validations

is_customized

boolean

Returns true if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides).

1 validation

Category

On This Page

Introduction

OAuth Scopes

Available Webhooks

Related Endpoints

Object Properties