Docs
Catalog API
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
    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.

    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

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 in POST request, 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.

  • 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

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

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

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

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

  • 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 in POST request, 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.

    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

Response

Categories are deleted

Body

object | application/json
  • meta
    object

example

Did you find what you were looking for?