BigCommerce Categories API

openapi: 3.2.0
info:
  title: BigCommerce Catalog - Category Trees Categories API
  description: '> 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).


    Our Catalog Category Trees and their [Categories](/docs/rest-catalog/category-trees/categories) endpoints are the more modern and performant counterparts to the [Categories (deprecated)](/docs/rest-catalog/categories) endpoints. Although the Category Trees endpoints and objects are designed to center an MSF-compatible, [multi-tenant category tree architecture](#categories), the endpoints work just as well in a single storefront context and support batch requests. Use [Catalog Trees Categories](/docs/rest-catalog/category-trees/categories) endpoints, instead of [Categories (deprecated)](/docs/rest-catalog/categories) endpoints.


    The Category Trees endpoints let you [get the Categories for a specific tree](/docs/rest-catalog/category-trees/categories#get-a-category-tree), and [bulk create](/docs/rest-catalog/category-trees/categories#create-categories), [bulk update](/docs/rest-catalog/category-trees/categories#update-categories), and [bulk delete](/docs/rest-catalog/category-trees/categories#delete-categories) Categories. You can also [bulk update the properties of Category Trees](/docs/rest-catalog/category-trees#upsert-category-trees), which includes changing the channels to which a Tree is assigned.


    The terms "category tree" and "catalog tree" are used interchangeably throughout the documentation.


    > To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**.


    ## Resources


    ### Webhooks

    Learn more about [Category Tree webhook events](/docs/integrations/webhooks/events/channels#category-trees).


    ### Additional Catalog endpoints

    * [Brands](/docs/rest-catalog/brands)

    * [Categories](/docs/rest-catalog/categories)

    * [Products](/docs/rest-catalog/products)

    * [Product Modifiers](/docs/rest-catalog/product-modifiers)

    * [Product Variants](/docs/rest-catalog/product-variants)

    * [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
paths:
  /catalog/trees/categories:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      summary: BigCommerce Get All Categories
      description: "Returns a list of categories. \n\nTo get a specific category in a tree, provide a category ID."
      tags:
      - Categories
      parameters:
      - name: category_uuid:in
        in: query
        schema:
          type: string
      - name: category_uuid:not_in
        in: query
        schema:
          type: string
      - name: category_id:in
        in: query
        schema:
          type: string
      - name: category_id:not_in
        in: query
        schema:
          type: string
      - name: tree_id:in
        in: query
        schema:
          type: string
      - name: tree_id:not_in
        in: query
        schema:
          type: string
      - name: parent_id:in
        in: query
        schema:
          type: string
      - name: parent_id:not_in
        in: query
        schema:
          type: string
      - name: name
        in: query
        schema:
          type: string
      - name: name:like
        in: query
        schema:
          type: string
      - name: page_title
        in: query
        schema:
          type: string
      - name: page_title:like
        in: query
        schema:
          type: string
      - name: keyword
        in: query
        schema:
          type: string
      - name: is_visible
        in: query
        schema:
          type: boolean
      - name: page
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
      - name: include_fields
        in: query
        schema:
          type: string
      - name: exclude_fields
        in: query
        schema:
          type: string
      responses:
        '200':
          description: List of categories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryList'
              examples:
                Get Category 12:
                  value:
                    data:
                    - category_id: 12
                      category_uuid: d1964756-5e1d-4c72-9fa0-e1a3f7be4a34
                      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
                      meta_keywords:
                      - string
                      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: string
                        is_customized: true
                    meta:
                      pagination:
                        total: 246
                        count: 5
                        per_page: 5
                        current_page: 1
                        total_pages: 50
                        links:
                          previous: ?limit=5&page=1
                          current: ?limit=5&page=2
                          next: ?limit=5&page=3
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequest'
      operationId: getAllCategories
    post:
      summary: BigCommerce Create Categories
      description: "Creates new categories. \n\nCreating a category requires:\n - `name`\n - `tree_id` or `parent_id` "
      parameters:
      - $ref: '#/components/parameters/ContentType'
      tags:
      - Categories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCategories'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                Create Category 36:
                  value:
                    data:
                    - category_id: 36
                      category_uuid: d2de0756-5e1d-4c72-9480-e1a3f7be4a34
                      parent_id: 0
                      tree_id: 1
                      name: Bath
                      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
        '207':
          description: Multi-Status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartialSuccessResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequest'
        '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:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequest'
      operationId: createCategories
    put:
      summary: BigCommerce Update Categories
      description: "Updates existing categories. \n\n To update a specific category in a tree, provide a category id."
      parameters:
      - $ref: '#/components/parameters/ContentType'
      tags:
      - Categories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCategories'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessNoContentResponse'
        '207':
          description: Partial success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartialSuccessNoContentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequest'
        '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:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequest'
      operationId: updateCategories
    delete:
      summary: BigCommerce Delete Categories
      description: "Deletes categories. \n\nTo delete a specific category in a tree, provide a category ID."
      tags:
      - Categories
      parameters:
      - name: category_uuid:in
        in: query
        schema:
          type: string
      - name: category_id:in
        in: query
        schema:
          type: string
      - name: tree_id:in
        in: query
        schema:
          type: string
      - name: parent_id:in
        in: query
        schema:
          type: string
      responses:
        '204':
          description: Categories are deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessNoContentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequest'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequest'
      operationId: deleteTreeCategories
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        errors:
          $ref: '#/components/schemas/MetaError'
        meta:
          $ref: '#/components/schemas/MetaData'
      x-tags:
      - Models
    ErrorBasic:
      type: object
      properties:
        status:
          description: 'The HTTP status code.

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

            '
          type: string
        type:
          type: string
      x-tags:
      - Models
    url:
      title: URL
      description: 'If not provided, the URL is autogenerated from the category name.

        '
      type: object
      properties:
        path:
          type: string
          example: /bath/
        is_customized:
          type: boolean
          example: false
    PartialSuccessResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GetCategories'
        errors:
          $ref: '#/components/schemas/MetaError'
        meta:
          $ref: '#/components/schemas/MetaData'
      x-tags:
      - Models
    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.

        Required in a POST if creating a child category.'
      example: 0
    tree_id:
      title: Tree ID
      type: integer
      description: The ID of the Category Tree.
      example: 1
    MetaData:
      type: object
      properties:
        total:
          type: integer
        success:
          type: integer
        failed:
          type: integer
      x-tags:
      - Models
    UpdateCategories:
      type: array
      items:
        allOf:
        - type: object
          properties:
            category_id:
              $ref: '#/components/schemas/category_id'
            name:
              $ref: '#/components/schemas/name'
            tree_id:
              $ref: '#/components/schemas/tree_id'
            parent_id:
              $ref: '#/components/schemas/parent_id'
          required:
          - category_id
        - $ref: '#/components/schemas/CategoryBase'
        - type: object
          properties:
            url:
              $ref: '#/components/schemas/url'
    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.

        Required in a POST.'
      example: Bath
    SuccessNoContentResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/MetaData'
      x-tags:
      - Models
    category_uuid:
      title: Category UUID
      type: string
      description: An additional unique identifier for the category. Read-Only.
      format: uuid
      readOnly: true
      example: d1964756-5e1d-4c72-9fa0-e1a3f7be4a34
    GetCategories:
      title: Get Categories
      allOf:
      - type: object
        properties:
          name:
            $ref: '#/components/schemas/name'
          category_id:
            $ref: '#/components/schemas/category_id'
          category_uuid:
            $ref: '#/components/schemas/category_uuid'
          tree_id:
            $ref: '#/components/schemas/tree_id'
          parent_id:
            $ref: '#/components/schemas/parent_id'
      - $ref: '#/components/schemas/CategoryBase'
      - type: object
        properties:
          url:
            $ref: '#/components/schemas/url'
    ErrorAdditional:
      type: object
      properties:
        errors:
          $ref: '#/components/schemas/DetailedErrors'
      x-tags:
      - Models
    CreateCategories:
      title: Create Categories
      type: array
      items:
        allOf:
        - type: object
          properties:
            name:
              $ref: '#/components/schemas/name'
            url:
              $ref: '#/components/schemas/url'
            parent_id:
              $ref: '#/components/schemas/parent_id'
            tree_id:
              $ref: '#/components/schemas/tree_id'
          required:
          - name
          - tree_id
          - parent_id
        - $ref: '#/components/schemas/CategoryBase'
    DetailedErrors:
      title: DetailedErrors
      description: Each key-value pair describes a failure or partial success case.
      type: object
      properties: {}
      additionalProperties: true
      x-internal: false
    PartialSuccessNoContentResponse:
      type: object
      properties:
        errors:
          $ref: '#/components/schemas/MetaError'
        meta:
          $ref: '#/components/schemas/MetaData'
      x-tags:
      - Models
    ErrorRequest:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorBasic'
      x-tags:
      - Models
    MetaPagination:
      type: object
      properties:
        pagination:
          type: object
          properties:
            total:
              type: integer
              example: 246
              minimum: 0
            count:
              type: integer
              example: 5
              minimum: 0
            per_page:
              type: integer
              example: 5
              minimum: 0
            current_page:
              type: integer
              example: 1
              minimum: 1
            total_pages:
              type: integer
              example: 50
              minimum: 0
            links:
              type: object
              properties:
                previous:
                  type: string
                  example: ?limit=5&page=1
                current:
                  type: string
                  example: ?limit=5&page=2
                next:
                  type: string
                  example: ?limit=5&page=3
      x-tags:
      - Models
    category_id:
      title: Category ID
      type: integer
      description: 'Unique ID of the *Category*. Increments sequentially.

        Read-Only.'
      readOnly: true
      example: 36
    CategoryList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GetCategories'
        meta:
          $ref: '#/components/schemas/MetaPagination'
    MetaError:
      allOf:
      - $ref: '#/components/schemas/ErrorBasic'
      - $ref: '#/components/schemas/ErrorAdditional'
      x-tags:
      - Models
    CategoryBase:
      title: Category
      type: object
      properties:
        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:
          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:
          type: string
          description: 'Custom title for the category page. If not defined, the category name will be used as the meta title.

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

            '
          example:
          - shower
          - tub
          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 [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.

            '
          example: category.html
        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.

            '
          example: https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png
          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.

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

            '
        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
    SuccessResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GetCategories'
        meta:
          $ref: '#/components/schemas/MetaData'
      x-tags:
      - Models
  parameters:
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.
      schema:
        type: string
        default: application/json
    Accept:
      name: Accept
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.
      schema:
        type: string
        default: application/json
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### 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](/docs/start/authentication/api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).'
      type: apiKey
      in: header