Docs
Catalog API
Category trees
Categories

Categories

Get All Categories

GET /catalog/trees/categories

Request

Returns a list of categories.

To get a specific category in a tree, provide a category ID.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • category_uuid:in in query - array
    Filter using a comma-separated list of one or more category UUIDs. To use category IDs, use the category_id:in parameter.
    Type: array[string]
  • category_uuid:not_in in query - array
    Filter using a comma-separated list to exclude one or more category UUIDs. To exclude using category IDs, use the category_id:not_in parameter.
    Type: array[string]
  • category_id:in in query - array
    Filter using a comma-separated list of one or more category IDs. To use category UUIDs, use the category_uuid:in parameter.
    Type: array[integer]
  • category_id:not_in in query - array
    Filter using a comma-separated list to exclude one or more category IDs. To exclude using category UUIDs, use the category_uuid:not_in parameter.
    Type: array[integer]
  • tree_id:in in query - array
    Filter using a comma-separated list of one or more category tree IDs.
    Type: array[integer]
  • tree_id:not_in in query - array
    Filter using a comma-separated list to exclude one or more category tree IDs.
    Type: array[integer]
  • parent_id:in in query - array
    Type: array[integer]
  • parent_id:not_in in query - array
    Type: array[integer]
  • page_title in query - string

    Filter items by page_title.

  • page_title:like in query - string
    Filter items by substring in the page title property. page_title:like=oil returns both Soil and mulch and Oil pastels.
  • name in query - string

    Filter items by name.

  • name:like in query - string
    Filter items by substring in the name property. name:like=stick returns both Stickers and Lipstick colors.
  • keyword in query - string
    Filter items by keywords found in the name, description, or sku fields, or in the brand name.
  • is_visible in query - boolean
    Filter items based on whether the product is currently visible on the storefront.
  • include_fields in query - array
    Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
    Type: array[string]
  • exclude_fields in query - array
    Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
    Type: array[string]
  • page in query - integer

    Specifies the page number in a limited (paginated) list of products.

  • limit in query with default of 50 - integer

    Controls the number of items per page in a limited (paginated) list of products.

example

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

Response

List of categories.

Body

object | application/json

  • data    array[object]

  • meta    object

Get Category 12

{
"data": [
{
"category_id": 12,
"category_uuid": "d1964756-5e1d-4c72-9fa0-e1a3f7be4a34",
"parent_id": 2,
"tree_id": 1,
"name": "Bath",
"description": "<p>We offer a wide variety of products perfect for relaxing</p>",
"views": 1050,
"sort_order": 3,
"page_title": "Bath",
"meta_keywords": [
"string"
],
"meta_description": "string",
"layout_file": "category.html",
"image_url": "https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png",
"is_visible": true,
"search_keywords": "string",
"default_product_sort": "use_store_settings",
"url": {

Create Categories

POST /catalog/trees/categories

Request

Creates new categories.

Limits:

  • 16,000 categories per store limit.
  • 1,000 categories per product limit.
  • 50 characters category name length.
  • 8 levels of child categories depth limit.
  • 65,535 characters category description length limit.

Creating a category requires:

  • name
  • tree_id or parent_id

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

array | application/json

  • name    string
    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

  • url    object

    If not provided in POST request, the URL is autogenerated from the category name.

  • parent_id    integer

    The unique numeric ID of the category parent. To create a top-level category, specify the tree_id. Otherwise, you can specify the parent_id. Required in a POST if creating a child category.

  • tree_id    integer

    The ID of the category tree. To create a top-level category, specify the tree_id. Otherwise, you can specify the parent_id.
    Example: 1

  • 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.

    Min: -2147483648
    Max: 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.

    Example: Bath

  • 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"].

    Type: array[string]
    Example: ["shower","tub"]

  • meta_description    string

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

    >= 0 characters<= 65535 characters

  • 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.

    >= 0 characters<= 50 characters
    Example: category.html

  • 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. Must be either a full-qualified URL or an empty string.

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

  • 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.

  • search_keywords    string

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

    >= 0 characters<= 255 characters

  • default_product_sort    string

    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

example

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

Response

Created

Body

object | application/json

  • data    array[object]

  • meta    object

Create Category 36

{
"data": [
{
"category_id": 36,
"category_uuid": "d2de0756-5e1d-4c72-9480-e1a3f7be4a34",
"parent_id": 0,
"tree_id": 1,
"name": "Bath",
"description": "<p>We offer a wide variety of products perfect for relaxing</p>",
"views": 1050,
"sort_order": 3,
"page_title": "Bath",
"meta_keywords": [
"loofah",
"bubbles"
],
"meta_description": "string",
"layout_file": "category.html",
"image_url": "https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png",
"is_visible": true,
"search_keywords": "string",
"default_product_sort": "use_store_settings",

Update Categories

PUT /catalog/trees/categories

Request

Updates existing categories.

To update a specific category in a tree, provide a category id.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

array | application/json

  • category_id    integer
    required

    Unique ID of the Category. Increments sequentially.
    Example: 36

  • name    string

    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

  • tree_id    integer

    The ID of the category tree. To create a top-level category, specify the tree_id. Otherwise, you can specify the parent_id.
    Example: 1

  • parent_id    integer

    The unique numeric ID of the category parent. To create a top-level category, specify the tree_id. Otherwise, you can specify the parent_id. Required in a POST if creating a child category.

  • 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.

    Min: -2147483648
    Max: 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.

    Example: Bath

  • 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"].

    Type: array[string]
    Example: ["shower","tub"]

  • meta_description    string

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

    >= 0 characters<= 65535 characters

  • 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.

    >= 0 characters<= 50 characters
    Example: category.html

  • 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. Must be either a full-qualified URL or an empty string.

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

  • 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.

  • search_keywords    string

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

    >= 0 characters<= 255 characters

  • default_product_sort    string

    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

  • url    object

    If not provided in POST request, the URL is autogenerated from the category name.

example

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

Response

OK

Body

object | application/json

  • meta    object

example

{
"meta": {
"total": 0,
"success": 0,
"failed": 0
}
}

Delete categories

DELETE /catalog/trees/categories

Request

Deletes categories.

To delete a specific category in a tree, provide a category ID.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • category_uuid:in in query - array
    Filter using a comma-separated list of one or more category UUIDs. To use category IDs, use the category_id:in parameter.
    Type: array[string]
  • category_id:in in query - array
    Filter using a comma-separated list of one or more category IDs. To use category UUIDs, use the category_uuid:in parameter.
    Type: array[integer]
  • tree_id:in in query - array
    Filter using a comma-separated list of one or more category tree IDs.
    Type: array[integer]
  • parent_id:in in query - array
    Type: array[integer]

example

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

Response

Categories are deleted

Body

object | application/json

  • meta    object

example

{
"meta": {
"total": 0,
"success": 0,
"failed": 0
}
}
Did you find what you were looking for?
Get a category treeGet All Categories