BigCommerce Catalog - Categories is a feature that allows merchants to organize and classify their products into different categories. By creating categories, merchants can help customers easily navigate through their online store and find products that are relevant to their needs. This feature also helps in SEO optimization by creating structured hierarchy for products, making it easier for search engines to crawl and index the website.
openapi: 3.0.3
info:
title: BigCommerce Catalog - Categories
description: >2-
> The Catalog API manages products, categories, brands, bulk pricing rules,
and more. To learn more about catalog resources, see the [Catalog
Overview](/docs/store-operations/catalog).
> Warning:
> - The [Catalog V3 Categories](/docs/rest-catalog/categories) endpoints
were primarily useful in applications for single storefront stores and are
deprecated. We still support these endpoints, but will not implement new
features within them. The endpoints will continue working as is.
> - To manage Categories, use the [Catalog V3 Category Trees -
Categories](/docs/rest-catalog/category-trees/categories) endpoints. These
endpoints work for both [MSF-enabled
stores](/docs/storefront/multi-storefront) and single storefront stores, and
are backwards-compatible with categories created using Catalog V3
Categories.
Category images have their own dedicated [create a category
image](/docs/rest-catalog/categories/images#create-a-category-image) and
[delete a category
image](/docs/rest-catalog/categories/images#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](/docs/rest-catalog/categories/metafields#create-a-category-metafield),
[updating category
metafields](/docs/rest-catalog/categories/metafields#update-a-category-metafield),
and [deleting category
metafields](/docs/rest-catalog/categories/metafields#delete-a-category-metafield).
This API family also contains endpoints to [update product sort
order](/docs/rest-catalog/categories/sort-order#update-product-sort-order)
within a category.
> 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](/docs/integrations/webhooks/events#category).
### Additional Catalog endpoints
* [Brands](/docs/rest-catalog/brands)
* [Category Trees](/docs/rest-catalog/category-trees)
* [Products](/docs/rest-catalog/products)
* [Product Modifiers](/docs/rest-catalog/product-modifiers)
* [Product Variants](/docs/rest-catalog/product-variants)
* [Product Variant Options](/docs/rest-catalog/product-variant-options)
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
version: ''
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
variables:
store_hash:
default: store_hash
description: Permanent ID of the BigCommerce store.
description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Batch Metafields
- name: Categories (Deprecated)
- name: Images
- name: Metafields
- name: Sort Order
paths:
/catalog/categories:
get:
tags:
- Categories (Deprecated)
deprecated: true
summary: BigCommerce Get All Categories
description: >-
When possible, use the [Catalog Trees - Get all
categories](/docs/rest-catalog/category-trees/categories#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.
operationId: getCategories
parameters:
- name: id
in: query
description: |
Filter items by ID.
schema:
type: integer
- name: id:in
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:not_in
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:min
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:max
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:greater
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:less
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: name
in: query
description: |
Filter items by name.
schema:
type: string
- name: name:like
in: query
style: form
explode: false
schema:
type: array
items:
type: string
- name: parent_id
in: query
description: >-
Filter items by parent_id. If the category is a child or sub
category it can be filtered with the parent_id.
schema:
type: integer
- name: parent_id:in
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: parent_id:min
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: parent_id:max
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: parent_id:greater
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: parent_id:less
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: page_title
in: query
description: |
Filter items by page_title.
schema:
type: string
- name: page_title:like
in: query
style: form
explode: false
schema:
type: array
items:
type: string
- name: keyword
in: query
description: Filter items by keywords. eg. new, towel, bath
schema:
type: string
- name: is_visible
in: query
description: 'Filter items by if visible on the storefront. '
schema:
type: boolean
- name: page
in: query
description: Specifies the page number in a limited (paginated) list of products.
schema:
type: integer
- name: limit
in: query
description: >-
Controls the number of items per page in a limited (paginated) list
of products.
schema:
type: integer
- name: include_fields
in: query
description: >-
Fields to include, in a comma-separated list. The ID and the
specified fields will be returned.
schema:
type: string
- name: exclude_fields
in: query
description: >-
Fields to exclude, in a comma-separated list. The specified fields
will be excluded from a response. The ID cannot be excluded.
schema:
type: string
- name: sort
in: query
description: >-
Controls the sort order of the response, for example, `sort=name`.
Allowed values:
- `name`: sort categories in alphabetical order by category name.
- `id`: sort in ascending order by category ID.
- `parent_id`: sort in ascending order by the ID of the parent
category.
- `sort_order`: sort in ascending order by sort order value.
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: Category Base
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Category'
meta:
$ref: '#/components/schemas/metaCollection_Full'
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'
post:
tags:
- Categories (Deprecated)
deprecated: true
summary: BigCommerce Create a Category
description: "When possible, use the [Category Trees - Create categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint instead.\n\nCreates a *Category*.\n\nUse this endpoint when an API only works with categories of a default BigCommerce storefront (`channel_id=1`). \n\nUse the [Create categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint when an API works with categories across different category trees that belong to different storefront channels.\n\n**Required Fields**:\n- `parent_id`: \n\t- To create a child category, set the `parent_id` to the parent category.\n\t- To create a top level category, set the `parent_id` to `0`.\n- `name`\n\n**Read-Only Fields**:\n- `id`\n\n**Limits**:\n- 16,000 categories per store limit.\n- 1,000 categories per product limit.\n- 50 characters category name length.\n- 8 levels of category depth limit.\n- 65,642 characters category description length limit.\n\n **Note:**\n The default rate limit for this endpoint is 40 concurrent requests.\n"
operationId: createCategory
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
title: Category
type: object
description: Common Category object properties.
properties:
parent_id:
type: integer
description: >-
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
x-required:
- post
name:
maxLength: 50
minLength: 1
type: string
description: >-
The name displayed for the category. Name is unique with
respect to the categoryʼs siblings.
Required in a POST.
example: Bath
x-required:
- post
description:
type: string
description: |
The product description, which can include HTML formatting.
example: >-
<p>We offer a wide variety of products perfect for
relaxing</p>
views:
type: integer
description: |
Number of views the category has on the storefront.
example: 1050
sort_order:
maximum: 2147483647
minimum: -2147483648
type: integer
description: >
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_title:
maxLength: 255
minLength: 0
type: string
description: >
Custom title for the category page. If not defined, the
category name will be used as the meta title.
example: Bath
search_keywords:
maxLength: 255
minLength: 0
type: string
description: >
A comma-separated list of keywords that can be used to
locate the category when searching the store.
meta_keywords:
type: array
description: >
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"].
items:
type: string
meta_description:
maxLength: 65535
minLength: 0
type: string
description: >
Custom meta description for the category page. If not
defined, the storeʼs default meta description will be used.
layout_file:
maxLength: 500
minLength: 0
type: string
description: >
A valid layout file. Please refer to [the article on
creating category files (Help
Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/).
This field is writable only for stores with a Blueprint
theme applied. For stores with a Stencil theme applied, see
[Custom Template
Associations](/docs/rest-content/custom-template-associations).
example: category.html
is_visible:
type: boolean
description: >
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_sort:
type: string
description: >
Determines how the products are sorted on category page
load.
enum:
- use_store_settings
- featured
- newest
- best_selling
- alpha_asc
- alpha_desc
- avg_customer_review
- price_asc
- price_desc
image_url:
type: string
description: >
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.png
x-url: true
custom_url:
title: Custom Url Category
type: object
description: The custom URL for the category on the storefront.
properties:
url:
maxLength: 255
minLength: 0
type: string
description: |
Category URL on the storefront.
example: /shoes
x-required:
- post
- put
x-url: true
is_customized:
type: boolean
description: >
Returns `true` if the URL has been changed from its
default state (the auto-assigned URL that BigCommerce
provides).
x-required:
- post
- put
required:
- parent_id
- name
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
title: Category Response
type: object
properties:
data:
$ref: '#/components/schemas/category_Full'
meta:
$ref: '#/components/schemas/metaEmpty_Full'
'207':
description: >-
Multiple operations have taken place and the status for each
operation can be viewed in the body of the response. Typically
indicates that a partial failure has occurred, such as when a `POST`
or `PUT` request is successful, but saving the URL has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/error_Base'
'409':
description: >
The `Category` was in conflict with another category. This is the
result of duplicate unique values, such as `name` or `custom_url`.
content:
application/json:
schema:
title: Error Response
type: object
properties:
errors:
title: Detailed Errors
type: object
properties: {}
additionalProperties: true
instance:
type: string
status:
type: integer
description: |
The HTTP status code.
title:
type: string
description: |
The error title describing the particular error.
type:
type: string
'422':
description: >
The `Category` was not valid. This is the result of missing required
fields, or of invalid data. See the response for more details.
content:
application/json:
schema:
title: Error Response
type: object
properties:
errors:
title: Detailed Errors
type: object
properties: {}
additionalProperties: true
instance:
type: string
status:
type: integer
description: |
The HTTP status code.
title:
type: string
description: |
The error title describing the particular error.
type:
type: string
x-codegen-request-body-name: category
delete:
tags:
- Categories (Deprecated)
deprecated: true
summary: BigCommerce Delete Categories
description: >-
When possible, use the [Category Trees - Delete
categories](/docs/rest-catalog/category-trees/categories#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 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.
operationId: deleteCategories
parameters:
- name: id
in: query
description: Filter items by ID.
schema:
type: integer
- name: id:in
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:not_in
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:min
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:max
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:greater
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:less
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: name
in: query
description: |
Filter items by name.
schema:
type: string
- name: parent_id
in: query
description: >-
Filter items by parent_id. If the category is a child or sub
category it can be filtered with the parent_id.
schema:
type: integer
- name: page_title
in: query
description: |
Filter items by page_title.
schema:
type: string
- name: keyword
in: query
description: Filter items by keywords. eg. new, towel, bath
schema:
type: string
- name: is_visible
in: query
description: 'Filter items by if visible on the storefront. '
schema:
type: boolean
- name: name:like
in: query
style: form
explode: false
schema:
type: array
items:
type: string
- name: parent_id:in
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: parent_id:min
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: parent_id:max
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: parent_id:greater
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: parent_id:less
in: query
style: form
explode: false
schema:
type: array
items:
type: integer
- name: page_title:like
in: query
style: form
explode: false
schema:
type: array
items:
type: string
responses:
'204':
description: ''
content: {}
parameters:
- $ref: '#/components/parameters/Accept'
/catalog/categories/{category_id}:
get:
tags:
- Categories (Deprecated)
deprecated: true
summary: BigCommerce Get a Category
description: >-
When possible, use the [Catalog Trees - Get all
categories](/docs/rest-catalog/category-trees/categories#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.
operationId: getCategory
parameters:
- name: include_fields
in: query
description: >-
Fields to include, in a comma-separated list. The ID and the
specified fields will be returned.
schema:
type: string
- name: exclude_fields
in: query
description: >-
Fields to exclude, in a comma-separated list. The specified fields
will be excluded from a response. The ID cannot be excluded.
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: Category Response
type: object
properties:
data:
$ref: '#/components/schemas/category_Full'
meta:
$ref: '#/components/schemas/metaEmpty_Full'
'404':
description: |
The resource was not found.
content:
application/json:
schema:
title: Not Found
type: object
properties:
status:
type: integer
description: |
404 HTTP status code.
title:
type: string
description: The error title describing the particular error.
type:
type: string
instance:
type: string
description: Error payload for the BigCommerce API.
put:
tags:
- Categories (Deprecated)
deprecated: true
summary: BigCommerce Update a Category
description: >-
When possible, use the [Catalog Trees - Update
categories](/docs/rest-catalog/category-trees/categories#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.
operationId: updateCategory
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
title: Category
type: object
description: Common Category object properties.
properties:
id:
type: integer
description: |-
Unique ID of the *Category*. Increments sequentially.
Read-Only.
readOnly: true
parent_id:
type: integer
description: >-
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
x-required:
- post
name:
maxLength: 50
minLength: 1
type: string
description: >-
The name displayed for the category. Name is unique with
respect to the categoryʼs siblings.
Required in a POST.
# --- truncated at 32 KB (111 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/catalog-categories-openapi-original.yml