BigCommerce Docs

curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/catalog/trees/categories \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '[
  {
    "name": "Bath"
  }
]'

{
  "data": [
    {
      "name": "Bath",
      "category_id": 36,
      "category_uuid": "d2de0756-5e1d-4c72-9480-e1a3f7be4a34",
      "tree_id": 1,
      "parent_id": 0,
      "description": "<p>We offer a wide variety of products perfect for relaxing</p>",
      "views": 1050,
      "sort_order": 3,
      "page_title": "Bath",
      "meta_keywords": [
        "loofah",
        "bubbles"
      ],
      "meta_description": "string",
      "layout_file": "category.html",
      "image_url": "https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png",
      "is_visible": true,
      "search_keywords": "string",
      "default_product_sort": "use_store_settings",
      "url": {
        "path": "/bath/",
        "is_customized": false
      }
    }
  ],
  "meta": {
    "total": 1,
    "success": 1,
    "failed": 0
  }
}

Creates new categories.

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.

Creating a category requires:

name
tree_id or parent_id
The url property is optional, but if included, its path must be unique per channel and category. If the path is not unique, the category will still be created but the URL will not — the response returns a multi-status to indicate the partial success.

Creates new categories. 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. Creating a category requires: - `name` - `tree_id` or `parent_id` - The `url` property is optional, but if included, its path must be unique per channel and category. If the path is not unique, the category will still be created but the URL will not — the response returns a multi-status to indicate the partial success.

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.

### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

store_hashstringRequired

Permanent ID of the BigCommerce store.

Request

This endpoint expects a list of objects.

Response

Created

datalist of objectsOptional

metaobjectOptional

Errors

400

Bad Request Error

403

Forbidden Error

422

Unprocessable Entity Error

Create Categories

Authentication

OAuth scopes

Authentication header

Further reading

Path parameters

Headers

Request

Response

Errors

OAuth scopes

Authentication header

Further reading