Create Categories

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/bigcommerce/main/json-schema/bigcommerce-create-categories-schema.json",
  "title": "Create Categories",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bigcommerce-categories-api-openapi.yml#/components/schemas/CreateCategories",
  "type": "array",
  "items": {
    "allOf": [
      {
        "type": "object",
        "properties": {
          "name": {
            "$ref": "#/$defs/name"
          },
          "url": {
            "$ref": "#/$defs/url"
          },
          "parent_id": {
            "$ref": "#/$defs/parent_id"
          },
          "tree_id": {
            "$ref": "#/$defs/tree_id"
          }
        },
        "required": [
          "name",
          "tree_id",
          "parent_id"
        ]
      },
      {
        "$ref": "#/$defs/CategoryBase"
      }
    ]
  },
  "$defs": {
    "CategoryBase": {
      "title": "Category",
      "type": "object",
      "properties": {
        "description": {
          "type": "string",
          "description": "The product description, which can include HTML formatting.\n"
        },
        "views": {
          "type": "integer",
          "description": "Number of views the category has on the storefront.\n"
        },
        "sort_order": {
          "type": "integer",
          "description": "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.\n"
        },
        "page_title": {
          "type": "string",
          "description": "Custom title for the category page. If not defined, the category name will be used as the meta title.\n"
        },
        "meta_keywords": {
          "type": "array",
          "description": "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\"].\n",
          "items": {
            "type": "string"
          }
        },
        "meta_description": {
          "maxLength": 65535,
          "minLength": 0,
          "type": "string",
          "description": "Custom meta description for the category page. If not defined, the storeʼs default meta description will be used.\n"
        },
        "layout_file": {
          "maxLength": 500,
          "minLength": 0,
          "type": "string",
          "description": "A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied.\n"
        },
        "image_url": {
          "type": "string",
          "description": "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.\n",
          "x-url": true
        },
        "is_visible": {
          "type": "boolean",
          "description": "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.\n"
        },
        "search_keywords": {
          "type": "string",
          "description": "A comma-separated list of keywords that can be used to locate the category when searching the store.\n"
        },
        "default_product_sort": {
          "type": "string",
          "description": "Determines how the products are sorted on category page load.\n",
          "enum": [
            "use_store_settings",
            "featured",
            "newest",
            "best_selling",
            "alpha_asc",
            "alpha_desc",
            "avg_customer_review",
            "price_asc",
            "price_desc"
          ]
        }
      }
    },
    "name": {
      "title": "Name",
      "maxLength": 50,
      "minLength": 1,
      "type": "string",
      "description": "The name displayed for the category. Name is unique with respect to the categoryʼs siblings.\nRequired in a POST."
    },
    "parent_id": {
      "title": "Parent ID",
      "type": "integer",
      "description": "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.\nRequired in a POST if creating a child category."
    },
    "tree_id": {
      "title": "Tree ID",
      "type": "integer",
      "description": "The ID of the Category Tree."
    },
    "url": {
      "title": "URL",
      "description": "If not provided, the URL is autogenerated from the category name.\n",
      "type": "object",
      "properties": {
        "path": {
          "type": "string"
        },
        "is_customized": {
          "type": "boolean"
        }
      }
    }
  }
}