BigCommerce
Catalog API
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
  • Accept in header with default of application/json - string - required

    The MIME type of the response body.

  • category_uuid:in in query - string
  • category_uuid:not_in in query - string
  • category_id:in in query - string
  • category_id:not_in in query - string
  • tree_id:in in query - string
  • tree_id:not_in in query - string
  • parent_id:in in query - string
  • parent_id:not_in in query - string
  • name in query - string
  • name:like in query - string
  • page_title in query - string
  • page_title:like in query - string
  • keyword in query - string
  • is_visible in query - boolean
  • page in query - integer
  • limit in query - integer
  • include_fields in query - string
  • exclude_fields in query - string

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

      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
      • Accept in header with default of application/json - string - required

        The MIME type of the response body.

      • category_uuid:in in query - string
      • category_id:in in query - string
      • tree_id:in in query - string
      • parent_id:in in query - string

      example

      Response

      Categories are deleted

      Body

      object | application/json
      • meta
        object

      example

      Did you find what you were looking for?