BigCommerce
Catalog API
Category Trees
Categories

Catalog - Category trees

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
    required

Parameters

  • store_hash in path - string
  • 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.

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

  • tree_id:in in query - array

    Filter using a comma-separated list of one or more category tree IDs.

  • parent_id:in in query - array
  • 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.

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

  • tree_id:not_in in query - array

    Filter using a comma-separated list to exclude one or more category tree IDs.

  • parent_id:not_in in query - array
  • 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.

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

  • 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

Response

List of categories.

Body

object | application/json

  • data    array[object]

  • meta    object

Get Category 12

Create Categories

POST /catalog/trees/categories

Request

Creates new categories.

Creating a category requires:

  • name
  • tree_id or parent_id

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

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, the URL is autogenerated from the category name.

  • parent_id    integer
    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: 0

  • tree_id    integer
    required

    The ID of the category tree.

    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.

    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<= 500 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.

  • 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

    Response

    Created

    Body

    object | application/json

    • data      array[object]

    • meta      object

    Create Category 36

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

    array | application/json

    • category_id      integer
      required
      read-only

      Unique ID of the Category. Increments sequentially. Read-Only.

      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.

      Example: 1

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

      Example: 0

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

      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<= 500 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.

    • 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, the URL is autogenerated from the category name.

      example

      Response

      OK

      Body

      object | application/json

      • meta        object

      example

      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
        required

      Parameters

      • store_hash in path - string
      • 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.

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

      • tree_id:in in query - array

        Filter using a comma-separated list of one or more category tree IDs.

      • parent_id:in in query - array

      example

      Response

      Categories are deleted

      Body

      object | application/json

      • meta        object

      example

      Did you find what you were looking for?
      Get a category treeGet All Categories