BigCommerce
BigCommerce Categories (Deprecated) API

The Categories (Deprecated) API from BigCommerce — 2 operation(s) for categories (deprecated).
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Categories (Deprecated) API
  version: 3.0.0
  termsOfService: https://www.bigcommerce.com/terms
  description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
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 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 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:
                  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:
            

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

Documentation

Specifications

Other Resources

OpenAPI Specification
