Update Category

Deprecated

PUT

https://api.bigcommerce.com/stores/:store_hash/v3/catalog/categories/:category_id

PUT

/stores/:store_hash/v3/catalog/categories/:category_id

curl -X PUT https://api.bigcommerce.com/stores/store_hash/v3/catalog/categories/1 \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "parent_id": 2,
  "name": "Bath"
}'

{
  "data": {
    "id": 1,
    "parent_id": 2,
    "name": "Bath",
    "description": "<p>We offer a wide variety of products perfect for relaxing</p>",
    "views": 1050,
    "sort_order": 3,
    "page_title": "Bath",
    "search_keywords": "string",
    "meta_keywords": [
      "string"
    ],
    "meta_description": "string",
    "layout_file": "category.html",
    "is_visible": true,
    "default_product_sort": "use_store_settings",
    "image_url": "https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png",
    "custom_url": {
      "url": "/shoes",
      "is_customized": true
    }
  },
  "meta": {}
}

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

Updates a Category.

Required Fields

none

Read-Only Fields

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

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Products	modify	`store_v2_products`
Products	read-only	`store_v2_products_read_only`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see our Guide to API Accounts.

Path parameters

category_idintegerRequired

The ID of the Category to which the resource belongs.

store_hashstringRequired

Permanent ID of the BigCommerce store.

Request

Common Category object properties.

parent_idintegerRequired

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.

namestringRequired1-50 characters

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.

descriptionstringOptional

The product description, which can include HTML formatting.

viewsintegerOptional

Number of views the category has on the storefront.

sort_orderintegerOptional-2147483648-2147483647

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.

page_titlestringOptional0-255 characters

Custom title for the category page. If not defined, the category name will be used as the meta title.

search_keywordsstringOptional0-255 characters

A comma-separated list of keywords that can be used to locate the category when searching the store.

meta_keywordslist of stringsOptional

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_descriptionstringOptional0-65535 characters

Custom meta description for the category page. If not defined, the storeʼs default meta description will be used.

layout_filestringOptional0-500 characters

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.

is_visiblebooleanOptional

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_sortenumOptional

Determines how the products are sorted on category page load.

image_urlstringOptional

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.

custom_urlobjectOptional

The custom URL for the category on the storefront.

Response

dataobjectOptional

Common Category object properties.

metaobjectOptional

Empty meta object; may be used later.

Errors

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error