BigCommerce Categories (Deprecated) API

openapi: 3.2.0
info:
  title: BigCommerce Catalog - Categories Categories (Deprecated) API
  description: "\n> The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog).\n\n> Warning:\n> - The [Catalog V3 Categories](/docs/rest-catalog/categories) endpoints were primarily useful in applications for single storefront stores and are deprecated. We still support these endpoints, but will not implement new features within them. The endpoints will continue working as is.\n> - To manage Categories, use the [Catalog V3 Category Trees - Categories](/docs/rest-catalog/category-trees/categories) endpoints. These endpoints work for both [MSF-enabled stores](/docs/storefront/multi-storefront) and single storefront stores, and are backwards-compatible with categories created using Catalog V3 Categories.\n\nCategory images have their own dedicated [create a category image](/docs/rest-catalog/categories/images#create-a-category-image) and [delete a category image](/docs/rest-catalog/categories/images#delete-a-category-image) endpoints. \n\nIn addition, categories have metafields that you can use to store information structured in key-value pairs; learn more about [creating category metafields](/docs/rest-catalog/categories/metafields#create-a-category-metafield), [updating category metafields](/docs/rest-catalog/categories/metafields#update-a-category-metafield), and [deleting category metafields](/docs/rest-catalog/categories/metafields#delete-a-category-metafield). \n\nThis API family also contains endpoints to [update product sort order](/docs/rest-catalog/categories/sort-order#update-product-sort-order) within a category. \n\n> To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. \n\n## Resources\n\n### Webhooks\nLearn more about [Category webhook events](/docs/integrations/webhooks/events#category).\n\n### Additional Catalog endpoints\n* [Brands](/docs/rest-catalog/brands)\n* [Category Trees](/docs/rest-catalog/category-trees)\n* [Products](/docs/rest-catalog/products)\n* [Product Modifiers](/docs/rest-catalog/product-modifiers)\n* [Product Variants](/docs/rest-catalog/product-variants)\n* [Product Variant Options](/docs/rest-catalog/product-variant-options)"
  termsOfService: https://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
  version: ''
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Categories (Deprecated)
paths:
  /catalog/categories:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      tags:
      - Categories (Deprecated)
      deprecated: true
      summary: BigCommerce Get All Categories
      description: 'When possible, use the [Catalog Trees - Get all categories](/docs/rest-catalog/category-trees/categories#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.'
      operationId: getCategories
      parameters:
      - name: id
        in: query
        description: 'Filter items by ID.

          '
        schema:
          type: integer
      - name: id:in
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: id:not_in
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: id:min
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: id:max
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: id:greater
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: id:less
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: name
        in: query
        description: 'Filter items by name.

          '
        schema:
          type: string
      - name: name:like
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: parent_id
        in: query
        description: 'Filter items by parent_id. If the category is a child or sub category it can be filtered with the parent_id. '
        schema:
          type: integer
      - name: parent_id:in
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: parent_id:min
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: parent_id:max
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: parent_id:greater
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: parent_id:less
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: page_title
        in: query
        description: 'Filter items by page_title.

          '
        schema:
          type: string
      - name: page_title:like
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: keyword
        in: query
        description: Filter items by keywords. eg. new, towel, bath
        schema:
          type: string
      - name: is_visible
        in: query
        description: 'Filter items by if visible on the storefront. '
        schema:
          type: boolean
      - name: page
        in: query
        description: Specifies the page number in a limited (paginated) list of products.
        schema:
          type: integer
      - name: limit
        in: query
        description: Controls the number of items per page in a limited (paginated) list of products.
        schema:
          type: integer
      - name: include_fields
        in: query
        description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
        schema:
          type: string
      - name: exclude_fields
        in: query
        description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
        schema:
          type: string
      - name: sort
        in: query
        description: "Controls the sort order of the response, for example, `sort=name`.\n\nAllowed values: \n- `name`: sort categories in alphabetical order by category name.\n- `id`: sort in ascending order by category ID.\n- `parent_id`: sort in ascending order by the ID of the parent category.\n- `sort_order`: sort in ascending order by sort order value."
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Category Base
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Category'
                  meta:
                    $ref: '#/components/schemas/metaCollection_Full'
              example:
                data:
                - id: 19
                  parent_id: 0
                  name: Garden
                  description: <p>This is the garden description</p>
                  views: 0
                  sort_order: 2
                  page_title: page title
                  meta_keywords:
                  - meta keyword
                  meta_description: meta description
                  layout_file: category.html
                  image_url: ''
                  is_visible: true
                  search_keywords: search keywords
                  default_product_sort: use_store_settings
                  custom_url:
                    url: /garden/
                    is_customized: false
                - id: 20
                  parent_id: 0
                  name: Publications
                  description: ''
                  views: 0
                  sort_order: 4
                  page_title: ''
                  meta_keywords:
                  - ''
                  meta_description: ''
                  layout_file: category_with_facets.html
                  image_url: ''
                  is_visible: true
                  search_keywords: ''
                  default_product_sort: use_store_settings
                  custom_url:
                    url: /publications/
                    is_customized: false
                - id: 21
                  parent_id: 0
                  name: Kitchen
                  description: ''
                  views: 0
                  sort_order: 3
                  page_title: ''
                  meta_keywords:
                  - ''
                  meta_description: ''
                  layout_file: category_with_facets.html
                  image_url: ''
                  is_visible: true
                  search_keywords: ''
                  default_product_sort: use_store_settings
                  custom_url:
                    url: /kitchen/
                    is_customized: false
                - id: 22
                  parent_id: 0
                  name: Utility
                  description: ''
                  views: 0
                  sort_order: 5
                  page_title: ''
                  meta_keywords:
                  - ''
                  meta_description: ''
                  layout_file: category_with_facets.html
                  image_url: ''
                  is_visible: true
                  search_keywords: ''
                  default_product_sort: use_store_settings
                  custom_url:
                    url: /utility/
                    is_customized: false
                - id: 23
                  parent_id: 0
                  name: Shop All
                  description: ''
                  views: 0
                  sort_order: 0
                  page_title: ''
                  meta_keywords:
                  - ''
                  meta_description: ''
                  layout_file: category_with_facets.html
                  image_url: ''
                  is_visible: true
                  search_keywords: ''
                  default_product_sort: use_store_settings
                  custom_url:
                    url: /shop-all/
                    is_customized: false
                - id: 39
                  parent_id: 19
                  name: Bath
                  description: ''
                  views: 0
                  sort_order: 0
                  page_title: ''
                  meta_keywords:
                  - ''
                  meta_description: ''
                  layout_file: category.html
                  image_url: ''
                  is_visible: true
                  search_keywords: ''
                  default_product_sort: use_store_settings
                  custom_url:
                    url: /garden/bath/
                    is_customized: false
                meta:
                  pagination:
                    total: 6
                    count: 6
                    per_page: 50
                    current_page: 1
                    total_pages: 1
                    links:
                      current: ?page=1&limit=50
    post:
      tags:
      - Categories (Deprecated)
      deprecated: true
      summary: BigCommerce Create a Category
      description: "When possible, use the [Category Trees - Create categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint instead.\n\nCreates a *Category*.\n\nUse this endpoint when an API only works with categories of a default BigCommerce storefront (`channel_id=1`). \n\nUse the [Create categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint when an API works with categories across different category trees that belong to different storefront channels.\n\n**Required Fields**:\n- `parent_id`: \n\t- To create a child category, set the `parent_id` to the parent category.\n\t- To create a top level category, set the `parent_id` to `0`.\n- `name`\n\n**Read-Only Fields**:\n- `id`\n\n**Limits**:\n- 16,000 categories per store limit.\n- 1,000 categories per product limit.\n- 50 characters category name length.\n- 8 levels of category depth limit.\n- 65,642 characters category description length limit.\n\n **Note:**\n The default rate limit for this endpoint is 40 concurrent requests.\n"
      operationId: createCategory
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              title: Category
              type: object
              description: Common Category object properties.
              properties:
                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.

                    Required in a POST if creating a child category.'
                  example: 2
                  x-required:
                  - post
                name:
                  maxLength: 50
                  minLength: 1
                  type: string
                  description: 'The name displayed for the category. Name is unique with respect to the categoryʼs siblings.

                    Required in a POST.'
                  example: Bath
                  x-required:
                  - post
                description:
                  type: string
                  description: 'The product description, which can include HTML formatting.

                    '
                  example: <p>We offer a wide variety of products perfect for relaxing</p>
                views:
                  type: integer
                  description: 'Number of views the category has on the storefront.

                    '
                  example: 1050
                sort_order:
                  maximum: 2147483647
                  minimum: -2147483648
                  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.

                    '
                  example: 3
                page_title:
                  maxLength: 255
                  minLength: 0
                  type: string
                  description: 'Custom title for the category page. If not defined, the category name will be used as the meta title.

                    '
                  example: Bath
                search_keywords:
                  maxLength: 255
                  minLength: 0
                  type: string
                  description: 'A comma-separated list of keywords that can be used to locate the category when searching the store.

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

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

                    '
                layout_file:
                  maxLength: 500
                  minLength: 0
                  type: string
                  description: 'A valid layout file. Please refer to [the article on creating category files (Help Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations).

                    '
                  example: category.html
                is_visible:
                  type: boolean
                  description: '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:
                  type: string
                  description: 'Determines how the products are sorted on category page load.

                    '
                  enum:
                  - use_store_settings
                  - featured
                  - newest
                  - best_selling
                  - alpha_asc
                  - alpha_desc
                  - avg_customer_review
                  - price_asc
                  - price_desc
                image_url:
                  type: string
                  description: '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
                  x-url: true
                custom_url:
                  title: Custom Url Category
                  type: object
                  description: The custom URL for the category on the storefront.
                  properties:
                    url:
                      maxLength: 255
                      minLength: 0
                      type: string
                      description: 'Category URL on the storefront.

                        '
                      example: /shoes
                      x-required:
                      - post
                      - put
                      x-url: true
                    is_customized:
                      type: boolean
                      description: 'Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides).

                        '
                      x-required:
                      - post
                      - put
              required:
              - parent_id
              - name
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Category Response
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/category_Full'
                  meta:
                    $ref: '#/components/schemas/metaEmpty_Full'
        '207':
          description: Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occurred, such as when a `POST` or `PUT` request is successful, but saving the URL has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '409':
          description: 'The `Category` was in conflict with another category. This is the result of duplicate unique values, such as `name` or `custom_url`.

            '
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties:
                  errors:
                    title: Detailed Errors
                    type: object
                    properties: {}
                    additionalProperties: true
                  instance:
                    type: string
                  status:
                    type: integer
                    description: 'The HTTP status code.

                      '
                  title:
                    type: string
                    description: 'The error title describing the particular error.

                      '
                  type:
                    type: string
        '422':
          description: 'The `Category` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.

            '
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties:
                  errors:
                    title: Detailed Errors
                    type: object
                    properties: {}
                    additionalProperties: true
                  instance:
                    type: string
                  status:
                    type: integer
                    description: 'The HTTP status code.

                      '
                  title:
                    type: string
                    description: 'The error title describing the particular error.

                      '
                  type:
                    type: string
      x-codegen-request-body-name: category
    delete:
      tags:
      - Categories (Deprecated)
      deprecated: true
      summary: BigCommerce Delete Categories
      description: "When possible, use the [Category Trees - Delete categories](/docs/rest-catalog/category-trees/categories#delete-categories) endpoint instead.\n\nDeletes *Category* objects. At least one filter parameter is required to perform the `DELETE` operation.\n\n**Usage Notes**\n\n- Sending a `DELETE`request without specifying a filter parameter will result in a `422` error. \n- 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."
      operationId: deleteCategories
      parameters:
      - name: id
        in: query
        description: Filter items by ID.
        schema:
          type: integer
      - name: id:in
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: id:not_in
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: id:min
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: id:max
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: id:greater
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: id:less
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: name
        in: query
        description: 'Filter items by name.

          '
        schema:
          type: string
      - name: parent_id
        in: query
        description: 'Filter items by parent_id. If the category is a child or sub category it can be filtered with the parent_id. '
        schema:
          type: integer
      - name: page_title
        in: query
        description: 'Filter items by page_title.

          '
        schema:
          type: string
      - name: keyword
        in: query
        description: Filter items by keywords. eg. new, towel, bath
        schema:
          type: string
      - name: is_visible
        in: query
        description: 'Filter items by if visible on the storefront. '
        schema:
          type: boolean
      - name: name:like
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: parent_id:in
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: parent_id:min
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: parent_id:max
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: parent_id:greater
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: parent_id:less
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: page_title:like
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '204':
          description: ''
          content: {}
  /catalog/categories/{category_id}:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - $ref: '#/components/parameters/CategoryIdParam'
    get:
      tags:
      - Categories (Deprecated)
      deprecated: true
      summary: BigCommerce Get a Category
      description: 'When possible, use the [Catalog Trees - Get all categories](/docs/rest-catalog/category-trees/categories#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.'
      operationId: getCategory
      parameters:
      - name: include_fields
        in: query
        description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
        schema:
          type: string
      - name: exclude_fields
        in: query
        description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Category Response
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/category_Full'
                  meta:
                    $ref: '#/components/schemas/metaEmpty_Full'
        '404':
          description: 'The resource was not found.

            '
          content:
            application/json:
              schema:
                title: Not Found
                type: object
                properties:
                  status:
                    type: integer
                    description: '404 HTTP status code.

                      '
                  title:
                    type: string
                    description: The error title describing the particular error.
                  type:
                    type: string
                  instance:
                    type: string
                description: Error payload for the BigCommerce API.
    put:
      tags:
      - Categories (Deprecated)
      deprecated: true
      summary: BigCommerce Update a Category
      description: "When possible, use the [Catalog Trees - Update categories](/docs/rest-catalog/category-trees/categories#update-categories) endpoint instead.\n\nUpdates a *Category*.\n\n**Required Fields**\n* none\n\n**Read-Only Fields**\n- id\n\n**Note:** \nThe default rate limit for this endpoint is 40 concurrent requests."
      operationId: updateCategory
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              title: Category
              type: object
              description: Common Category object properties.
              properties:
                id:
                  type: integer
                  description: 'Unique ID of the *Category*. Increments sequentially.

                    Read-Only.'
                  readOnly: true
                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.

                    Required in a POST if creating a child category.'
                  example: 2
                  x-required:
                  - post
                name:
                  maxLength: 50
                  minLength: 1
                  type: string
                  description: 'The name displayed for the category. Name is unique with respect to the categoryʼs siblings.

                    Required in a POST.'
                  example: Bath
                  x-required:
                  - post
                description:
                  type: string
                  description: 'The product description, which can include HTML formatting.

                    '
                  example: <p>We offer a wide variety of products perfect for relaxing</p>
                views:
                  type: integer
                  description: 'Number of views the category has on the storefront.

                    '
                  example: 1050
                sort_order:
                  maximum: 2147483647
                  minimum: -2147483648
                  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.

                    '
                  example: 3
                page_title:
                  maxLength: 255
                  minLength: 0
                  type: string
                  description: 'Custom title for the category page. If not defined, the category name will be used as the meta title.

                    '
                  example: Bath
                search_keywords:
                  maxLength: 255
                  minLength: 0
                  type: string
                  description: 'A comma-separated list of keywords that can be used to locate the category when searching the store.

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

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

                    '
                layout_file:
                  maxLength: 500
                  minLength: 0
                  type: string
                  description: 'A val

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-categories-deprecated-api-openapi.yml