Brands and Categories

We’ve explored the ways you can create, modify, and delete products. We’ve also learned about variants, variant options, and modifier options. Now we want to empower you with the ability to organize the products in ways that stretch your programming prowess.

In this lesson, we’ll discuss brands and categories; namely, how to create a category, update a category by ID, assign a product to different categories, and explore the power of the category tree.

Brands

Brands are a form of catalog taxonomy. A brand is a grouping of products that share a common identity. For example, you might have a brand for your own line of products, or you might have a brand for products that you sell from other manufacturers.

Brands can be associated with products. This means that you can create a brand and then associate it with one or more products. You can upload an image to a brand to use as the brand’s logo. Brands can have metafields. You can use metafields to store additional information about brands, such as the brand’s website address or the brand’s contact information.

Create a Brand

Create a brand by sending a POST request to /catalog/brands

Required Fields:

• name

GET a Brand

GET /catalog/brands/{brand_id}

Returns a single brand.

Create a Brand Image

POST /catalog/brands/{brand_id}/image

Creates a brand Image.

Categories

Categories are collections of products organized by the merchant for the primary purpose of merchandising the products on a BigCommerce storefront. The collection of categories for a store determines the navigational menu hierarchy and structure for most storefront themes. All products should be associated with at least one category, and a category needs to contain at least one product.

Categories Trees

If you are developing on a multi-storefront environment, you may need to manage multiple categories across multiple category trees. The API described in the previous example is a legacy API and will not work for multi-storefront. Instead, you should use Categories Trees to manage your categories.

Categories Trees - GET All Categories

Returns a list of categories across multiple category trees. To get a specific category in a tree, provide a category id.

GET /catalog/trees/categories

Category Trees - Create Categories

Creates new categories. tree_id or parent_id are required to create a category.

POST /catalog/trees/categories

Example Request and Response Bodies

[
  {
    "tree_id": 0,
    "parent_id": 0,
    "name": "string",
    "description": "string",
    "views": 0,
    "sort_order": 0,
    "page_title": "string",
    "search_keywords": "string",
    "meta_keywords": [
      "string"
    ],
    "meta_description": "string",
    "layout_file": "string",
    "is_visible": true,
    "image_url": "string",
    "custom_url": {
      "url": "string",
      "is_customized": true
    },
    "default_product_sort": "use_store_settings"
  }
]

Category Trees - Update Categories

Updates existing categories across multiple channels. To update a specific category in a tree, provide the category id.

PUT /catalog/trees/categories

Example Request:

{
  "requests": [
    {
      "tree_id": 1,
      "category_id": 2,
      "category_uuid": "d5e0e6e9-d809-4adf-9920-3a698629ce74",
      "parent_id": 0,
      "name": "New Category Name",
      "description": "This is the description for the new category.",
      "views": 0,
      "sort_order": 0,
      "page_title": "New Category Title",
      "search_keywords": "new category",
      "meta_keywords": [
        "new",
        "category"
      ],
      "meta_description": "This is the meta description for the new category.",
      "layout_file": "default",
      "is_visible": true,
      "image_url": "https://example.com/image.png",
      "url": {
        "path": "new-category",
        "is_customized": true
      },
      "default_product_sort": "use_store_settings"
    }
  ]
}

A category tree is collection of categories for a store that makes up the navigational menu hierarchy and structure for most storefront themes.

The Category Tree endpoint returns a simple view of the parent > child relationship of all categories in the store. This endpoint can be used to fetch the categories if building out a custom navigation for a store.

GET a Category Tree

Returns a category tree.

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

GET All Category Trees

Returns a list of all category trees.

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

Example Response:

{
  "data": [
    {
      "id": 1,
      "name": "Home",
      "channels": [
        1
      ],
      "children": [
        {
          "id": 2,
          "name": "Electronics",
          "channels": [
            1
          ],
          "children": [
            {
              "id": 3,
              "name": "Televisions",
              "channels": [
                1
              ]
            },
            {
              "id": 4,
              "name": "Computers",
              "channels": [
                1
              ]
            }
          ]
        },
        {
          "id": 5,
          "name": "Clothing",
          "channels": [
            1
          ],
          "children": [
            {
              "id": 6,
              "name": "Men's Clothing",
              "channels": [
                1
              ]
            },
            {
              "id": 7,
              "name": "Women's Clothing",
              "channels": [
                1
              ]
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 246,
      "count": 1,
      "per_page": 1,
      "current_page": 1,
      "total_pages": 246,
      "links": {
        "next": null,
        "current": "?limit=1&page=1"
      }
    }
  }
}

UPSERT a Category Tree

Updates or creates a new tree. If a tree object contains an ID, it is processed as an update operation using that ID. If no ID is provided, a new tree is created.

channel_id is required to create a category tree.

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

Example Request and Response Bodies:

{
    "id": 0,
    "name": "string",
    "channels": [
      0
    ]
}

Resources

• Brands
• Categories
• Categories API
• Category Trees