Docs
Catalog API
Categories
Categories Deprecated

Categories (deprecated)

Get All Categories

GET /catalog/categories
⚠️
This endpoint is deprecated.

Request

When possible, use the Catalog Trees - Get all categories endpoint instead.

Returns a list of Categories. Optional filter parameters can be passed in.

Note: The default rate limit for this endpoint is 40 concurrent requests.

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.
  • id in query - integer

    Filter items by category ID.

  • id:in in query - array
    Explicitly include objects by passing a comma-separated list of IDs.
    Type: array[integer]
  • id:not_in in query - array
    Exclude objects by passing a comma-separated list of IDs.
    Type: array[integer]
  • id:min in query - integer
  • id:max in query - integer
  • id:greater in query - integer
  • id:less in query - integer
  • 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.
  • parent_id in query - integer
    Filter items by parent_id. If the category is a child or sub-category it can be filtered with the parent_id.
  • parent_id:in in query - array
    Type: array[integer]
  • parent_id:min in query - integer
  • parent_id:max in query - integer
  • parent_id:greater in query - integer
  • parent_id:less in query - 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.
  • 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.
  • sort in query - string

    Controls the sort order of the response, for example, sort=name.

    Allowed values:

    • name: sort categories in alphabetical order by category name.
    • id: sort in ascending order by category ID.
    • parent_id: sort in ascending order by the ID of the parent category.
    • sort_order: sort in ascending order by sort order value.

    Allowed: name | id | parent_id | sort_order

  • page in query - integer

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

  • limit in query - integer

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

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

example

Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

example

Create a Category

POST /catalog/categories
⚠️
This endpoint is deprecated.

Request

When possible, use the Category Trees - Create categories endpoint instead.

Creates a Category.

Use this endpoint when an API only works with categories of a default BigCommerce storefront (channel_id=1).

Use the Create categories endpoint when an API works with categories across different category trees that belong to different storefront channels.

Required Fields:

  • parent_id:
    • To create a child category, set the parent_id to the parent category.
    • To create a top level category, set the parent_id to 0.
  • name

Read-Only Fields:

  • id

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.

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

object | application/json
Common Category object properties.

  • 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: 2

  • name    string
    required

    The name displayed for the category. The name must be unique with respect to the category of siblings on the same level (you can duplicate the name for other siblings on another level). Required in a POST.
    >= 1 characters<= 50 characters
    Example: Bath

  • description    string

    The category 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.

    >= 0 characters<= 255 characters
    Example: Bath

  • 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

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

  • 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 the article on creating category files (Help Center). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see Custom Template Associations.

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

  • is_visible    boolean

    Flag to determine whether the category should be displayed to customers browsing the store. If true, the category will be displayed. If false, the category will be hidden from view.

  • 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

  • image_url    string

    Image URL used for this category on the storefront. Images can be uploaded using form file post to /categories/{categoryId}/image, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required.

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

  • custom_url    object

    The custom URL for the category on the storefront. If not provided, the URL will be autogenerated from the category name.

example

Response

Body

object | application/json

  • data    object

    Common Category object properties.

  • meta    object

    Response metadata.

example

Delete Categories

DELETE /catalog/categories
⚠️
This endpoint is deprecated.

Request

When possible, use the Category Trees - Delete categories endpoint instead.

Deletes Category objects. At least one filter parameter is required to perform the DELETE operation.

Usage Notes

  • Sending a DELETErequest without specifying a filter parameter will result in a 422 error.
  • Sending a DELETE request for a category that contains products will result in a 422 error. Move products to a new category by sending a PUT request to the /catalog/products/{product_id} endpoint before deleting a category.

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.
  • id in query - integer

    Filter items by category ID.

  • id:in in query - array
    Explicitly include objects by passing a comma-separated list of IDs.
    Type: array[integer]
  • id:not_in in query - array
    Exclude objects by passing a comma-separated list of IDs.
    Type: array[integer]
  • id:min in query - integer
  • id:max in query - integer
  • id:greater in query - integer
  • id:less in query - integer
  • name in query - string

    Filter items by name.

  • parent_id in query - integer
    Filter items by parent_id. If the category is a child or sub-category it can be filtered with the parent_id.
  • page_title in query - string

    Filter items by page_title.

  • 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.
  • name:like in query - string
    Filter items by substring in the name property. name:like=stick returns both Stickers and Lipstick colors.
  • parent_id:in in query - array
    Type: array[integer]
  • parent_id:min in query - integer
  • parent_id:max in query - integer
  • parent_id:greater in query - integer
  • parent_id:less in query - integer
  • 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.

example

Response

Get a Category

GET /catalog/categories/{category_id}
⚠️
This endpoint is deprecated.

Request

When possible, use the Catalog Trees - Get all categories endpoint instead. You can provide a category identifier using query parameters to retrieve a single category.

Returns a single Category. Optional parameters can be passed in.

Note: The default rate limit for this endpoint is 40 concurrent requests.

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_id in path - integer
    required

    The ID of the Category to which the resource belongs.

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

example

Response

Body

object | application/json

  • data    object

    Common Category object properties.

  • meta    object

    Response metadata.

example

Update a Category

PUT /catalog/categories/{category_id}
⚠️
This endpoint is deprecated.

Request

When possible, use the Catalog Trees - Update categories endpoint instead.

Updates a Category.

Required Fields

  • none

Read-Only Fields

  • id

Note: The default rate limit for this endpoint is 40 concurrent requests.

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_id in path - integer
    required

    The ID of the Category to which the resource belongs.

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

Body

object | application/json
Common Category object properties.

  • id    integer
    read-only

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

  • 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: 2

  • name    string
    required

    The name displayed for the category. The name must be unique with respect to the category of siblings on the same level (you can duplicate the name for other siblings on another level). Required in a POST.
    >= 1 characters<= 50 characters
    Example: Bath

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

    >= 0 characters<= 255 characters
    Example: Bath

  • 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

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

  • 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 the article on creating category files (Help Center). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see Custom Template Associations.

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

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

  • 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

  • image_url    string

    Image URL used for this category on the storefront. Images can be uploaded using form file post to /categories/{categoryId}/image, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required.

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

  • custom_url    object

    The custom URL for the category on the storefront.

example

Response

Body

object | application/json

  • data    object

    Common Category object properties.

  • meta    object

    Empty meta object; may be used later.

example

Delete a Category

DELETE /catalog/categories/{category_id}
⚠️
This endpoint is deprecated.

Request

When possible, use the Category Trees - Delete categories endpoint instead. You can provide a category identifier using query parameters to delete a single category.

Deletes a Category.

Note: The default rate limit for this endpoint is 40 concurrent requests.

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_id in path - integer
    required

    The ID of the Category to which the resource belongs.

example

Response

Did you find what you were looking for?
Delete Multiple MetafieldsGet All Categories